Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

Merge origin/main (14f12b9, #161 contract strings, on a351c05, v3.12.1) into plan/walk-cycle-witness-1028: the walk's Unreleased section stays above the contract strings section, no number yet

Soohong Kimed20bed5c86d
diff --cc CHANGELOG.md
index f7808a6,deef564..644fa29
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -2,84 -2,21 +2,99 @@@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased - A walk whose feet meet once a cycle is cut one cycle long only where its body or the order the feet are drawn in witnesses it, a walk that starts or stops in its take is named to film again, and video-set cuts a searched walk or run with motion-auto by default
+
+**Upgrading from 3.5.0: `video-set` now cuts searched walk and run loops with `--anchor motion-auto` and their view by default, and `video-loop --anchor motion-auto` recognises crossings that mark cycles where feet hide or step apart instead of cutting two cycles.** Every walk or run item whose loop is searched is now cut with `motion-auto` and its view, producing a different cut and different bytes; `--anchor none` gives the old cut, its pictures and reports byte for byte apart from the engine hash (`producer.implementation_sha256`). Idle, attack, once-hold, lifetime, and once-return items are cut as before. In `video-loop --anchor motion-auto` without `--view`, a walk whose feet are seen together over half the interval at a pass (`crossings.HIDE_SHARE`, 0.5) and whose picture repeats each interval is now counted on cycles only where the body's top line, read less the picture's own flow, rises and falls twice an interval, and that rise and fall must be the body's own, read against its lowest row and its upper body, so the picture moved or zoomed with it witnesses nothing: where the parent engine cut two cycles, the loop is now one cycle with new bytes; where the parent engine kept the search's cut with no `steps`, the cut is the same and the strip and report now record `steps: 2`; where nothing witnesses, its crossings stay on steps with a warning (`cycle-unwitnessed`). A walk whose crossings mark steps (brief passes, or from the side) is cut to the same bytes. With `--view` (or through `video-set`), a front, back, or diagonal walk is evaluated even with brief passes: such a walk is counted on cycles with the same witness, the view's foot cue only refusing where it turns over one interval on; where nothing witnesses, its crossings stay on steps with a warning, and `video-set` leaves a `cycle-unwitnessed` loop out of the cycle alignment. Every report whose clip stands still gains `stands` and `run_limit`, and reports where cycle reading is asked gain `cycles`, with `bob` where the picture passes and `cue` only where a view is given.
+
+- **New: crossing cycle detection (`local_cycle.read_cycles`, `local_cycle.bob_word`, `local_cycle.off_flow`, `local_cycle.twice_an_interval`, `local_cycle.own_beat`, `local_cycle.cue_word`, `crossings.HIDE_SHARE`, `crossings.Reading.hides`, `legs.body_signals`, `CYCLE_SLACK`, `CUE_FLOOR`, `CUE_SWAPPED`, `BOB_TWICE`, `BOB_FLOOR`, `BOB_ROWS`, `BOB_OWN`, `BOB_SCALE`, `BEAT_FRAMES`, `UNWITNESSED`).** In gap mode on a readable reading, when feet can hide behind one another (`reading.overlap` over `crossings.HIDE_SHARE`, 0.5) or when the view is given and is not `side`, crossing intervals are checked to see if they mark full cycles rather than single steps. `repeat_at(distances, span)` reads the mean distance of frames to those lagged by `span` over the clip's mean step from frame to frame. Comparing distances at half, one, and two intervals, crossings mark cycles when `one < half` and `one <= two + CYCLE_SLACK` (0.5), only where a witness that reads no leg says the interval holds two steps, the body's own rise and fall twice an interval: its top line (`legs.strike_signals` `top`) less its flow, read against its lowest row and upper body. New function `local_cycle.off_flow(values, interval)` returns `values` (per frame) less their flow: each frame minus the mean of the interval about it (a moving average one interval long, its two end frames weighted by the part of a frame the interval covers), kept only over the frames the interval fits about (the first and last `ceil(interval/2 - 0.5)` frames drop out), and what is left minus its least-squares straight line; a rise and fall once or twice an interval averages to nothing over one interval and is left whole, while a flow slower than the interval is taken out wholly where it bends no more than a cubic (a constant, a straight drift, an arc, a cubic) and in part where it is a slow sway a few intervals long. `local_cycle.bob_word(signals, interval)` reads the body's top line less its flow (`off_flow(top, interval)`), not the raw line; `swing` is the range of the line left over the body's median height, and `rows` is that range in pixel rows. Where the clip is under an interval long so nothing is left, `says` is null and `why` says its top line less its flow is not read; where `swing` is under `BOB_FLOOR` (0.005) or `rows` is under `BOB_ROWS` (2), `says` is null, `why` says the line's range less its flow is under 0.5 % of the body's height or 2 rows, so it does not rise and fall (the top line is read in whole pixel rows, so a picture drifting up or down makes the line step a row up and down as it rounds, and that rounding, less its own mean over an interval, stays under 2 rows), and `half` and `quarter` are not read. Otherwise it reads the line left's correlation half an interval on (`half`) and a quarter of an interval on (`quarter`), both with `crossings.correlation_on` (each the larger of the two whole lags about the span), saying `"cycles"` only where `half` is `BOB_TWICE` (0.28) or more and `quarter` is `-BOB_TWICE` (-0.28) or less (the line is as it was half an interval on and turned over a quarter on, which is a rise and fall twice an interval; a step's bob is turned over half an interval on, and any flow left over is as it was at both half and a quarter of an interval on so it cannot pass the quarter test), null otherwise with `why` giving both values. Where any frame's lowest solid row is the frame's last row (`legs.body_signals` `edge`), `says` is null, `why`: "its lowest row is the frame's last row in {n} of {N} frames: the feet may run off the frame, and the picture moving is not read off them" (there the lowest row is the frame's, not the feet's). `local_cycle.twice_an_interval(values, interval)` reads `values` (per frame) less their flow (`off_flow`), then a least-squares fit of a mean, the harmonic twice an interval (cos and sin of 4 pi k / `interval`) and the harmonic once an interval (cos and sin of 2 pi k / `interval`), k the frames left counted from the first; it returns the twice-an-interval harmonic as a complex amplitude (its cos coefficient less i times its sin coefficient), in the values' units (a line rising and falling a rows either way twice an interval reads a in magnitude; lines read so over the same frames and interval subtract as they move), or None where fewer than `BEAT_FRAMES` (8) frames are left; where none, `says` is null, `why`: "its top line's rise and fall twice an interval is not read against its lowest row and upper body: under 8 frames are left less the flow". `local_cycle.own_beat(signals, interval)` reads three lines with `twice_an_interval`: the top line (`top`), the lowest solid row (`reach`) and the lowest opaque row (`sole`); it returns, in rows up and down (twice the magnitude): `beat` (the top line's), `lowest` (the lowest row's), `sole`, `less_lowest` (the top line's less the lowest row's: the picture moving taken out), `bands` (`{rows, width, zoom, beat, reads, less}`, per band: its rows below the first solid row, its width in the median frame and `zoom`, in pixels, `beat` in pixels, `reads` is the band's `beat` over its `zoom` (the share of the zoom making the line's rise and fall that the band reads), read whatever its turn: a zoom moves a band's width in step with the line it lifts, but the band's own parts swinging across it (arms, a cape) move it too, in step with the line, against it, or a quarter of the beat off, and the zoom's part is not told from theirs. `less` is what is left of the top line's rise and fall twice an interval less as much of the zoom as the band reads: `less_lowest` times (1 - `reads`), and nothing where `reads` is 1 or more, so a band whose width moves against the line adds nothing to what is left, `reads` and `less` null where the band is not seen), `less_bands` (the least `less`, null where no band is seen), `still_bands` (the number of bands seen whose `reads` is at most 1 - `BOB_SCALE`, 0.4: they hold still on the beat), and `own`, the smaller of `less_lowest` and `less_bands` (None where a line is not read). The floor is the larger of `BOB_ROWS` and `BOB_FLOOR` of the body's median height; where `less_lowest` is under the larger of `BOB_OWN` (0.3) times `beat` and the floor, `says` is null, `why`: "its lowest row rises and falls with it: less the lowest row's, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}; at least 30% and {floor} rows): the picture moves with the body, and the body's own is not told from it"; where no band is seen (`less_bands` null), `says` is null, `why`: "no band of its upper body would show the picture zooming: zoomed in as far as its top line rises and falls twice an interval against its lowest row ({less_lowest} rows of {height}), no band's width moves 1 px (at most {largest zoom}): the picture zooming with the body is not told from the body's own"; where `less_bands` is under the largest of `BOB_OWN` times `beat`, the floor, and `BOB_SCALE` (0.6) times `less_lowest`, `says` is null, `why`: "its upper body's width changes with it: less as much of the zoom as its band {a}% to {b}% of its height below its top reads, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}), {ratio} of the {less_lowest} left against the lowest row (at least 30%, {floor} rows and 0.6): the picture may zoom with the body, and the body's own is not told from it"; otherwise `says` `"cycles"`. This tells them apart because a body rising and falling on its legs leaves its planted foot, the lowest solid row, on the ground, and carries its upper body's bands whole and leaves their widths: the picture moved up and down carries the lowest row with the top line by the same rows, so nothing is left of the line's rise against it, while the picture zoomed in and out widens each band as it lifts the line, as far as the band's outline lets it, so nothing is left once the zoom is taken out too. Where no band would show the zoom, or any band that would moves on the beat (arms swinging past the body's sides, a cape, or the picture zooming), nothing tells the picture zooming from the body's own, and nothing is witnessed; one band holding still says only that no zoom shows in that band (a head drawn narrower as the picture zooms in holds still so). Two limits the code does not catch: (a) a picture zoomed on the beat with every band seen drawn against the zoom, so that each band holds still, is read as the body's own (its band widths are those of an upper body rising whole on its legs; measured on one such drawing, every band within 0.78 px of such a body); (b) a body that rises and falls twice a step on its own legs reads as two steps an interval of one. A walk whose arms swing past its sides on the beat is not witnessed where a band seen moves on the beat (its `reads` over 0.4). Where a walk is not witnessed, its crossings stay on steps, or its cut is held, and either way it is named, never handed out as a cycle unnamed. New `legs.body_signals(frames)` reads per frame `bands`, each band's mean width in alpha, in pixels, read on the same rows in every frame, those of the clip's median body height (`legs.BANDS` = `((0.02, 0.10), (0.10, 0.18), (0.18, 0.26), (0.26, 0.34), (0.34, 0.42), (0.42, 0.50))`), and `edge`, 1 where the lowest solid row is the frame's last row, else 0; only the step count's witness reads them, merged by `loop.read_steps` into the signals it passes to `local_cycle.read_cycles`; `legs.strike_signals` is unchanged, so the loop report's `gait.silhouette.signals` is unchanged, and `--anchor none` still gives the old cut, its pictures and reports byte for byte apart from the engine hash. The directional foot cue (`legs.shade_cue` from the side or diagonal, `legs.depth_cue` from the front or back) is read with a view given by `local_cycle.cue_word(cue, interval, step=None)` and can only refuse cycles: under `CUE_FLOOR` (0.5) of the step it is drawn in (`legs.TONE`, 1/255, or a pixel row of median body height) it says `"alike"`; where it turns over one interval on (`crossings.correlation_on` at or below `CUE_SWAPPED`, `-0.2`) it says `"steps"`, refusing cycles because the other leg leads there; otherwise null. With no view no cue is read at all. Where the view's cue says `"steps"`, the count stands (two steps); else where the bob says `"cycles"`, cycles are marked; otherwise crossings stay on steps with `unwitnessed` true (`local_cycle.UNWITNESSED`) and a warning (`cycle-unwitnessed`). When cycles are marked, `Reading.mark_cycles` sets `per` to 2 and halves `step` and `step_range`: a cut one interval long is two steps, and the search's cut (`--anchor motion-auto`) taken on it writes `steps: {count: 2, by: crossings}`. A fixed cut (`--cycle fixed`, `fixed_count`) and the loop as it plays round (`ring_steps`) read the same; a fixed cut one interval long is counted two steps and not refused, and still writes no `steps`.
+- **Removed: the same-picture rule (`local_cycle.same_picture`, `local_cycle.same_picture_count`, `local_cycle.SAME_PICTURE_MAX`, count code `same-picture`, report fields `step_count.search.same_picture` and `step_count.same_picture`).** It kept the search's cut, with no `steps`, where the count said one step; it never cut one cycle where the search had found two. `local_cycle.read_cycles` takes its place.
+- **New: walk start-stop retake reporting (`loop.stand_retake`, `crossings.Reading.stands`).** In gap mode, runs where the feet stay together longer than `run_limit` (√2 times the median whole pass run) are recorded in `Reading.stands`. Where a clip shows its steps, contains `stands`, and the cut kept does not count two steps (`verdict` is not `two`) with no two-step cut closing between the standing frames, `loop.stand_retake` emits a `retake` report (`reason: "start-stop"`, `remedy: "retake"`), keeping the cut as cut without refusal under `--unfixed refuse`. Where a part also pops, one `retake` names both (`loop.retakes`): the first reason's record, `reasons: ["part-pop", "start-stop"]`, and each reason's numbers under its own key (`part_pop`, `start_stop`).
+- **Changed: `video-set` defaults gait anchoring to `motion-auto` (`batch.anchor_for`).** Without an explicit `--anchor`, `video-set` cuts each walk and run item whose loop is searched (`cycle_for` returns `auto` or `periodic`) with `motion-auto`, and assigns `none` to idle, attack, once-hold, lifetime, and once-return items; explicit `--anchor` options are applied to every item as before. `video-set` passes each item's view to `video-loop`. Any item whose loop names a retake carries `loop.retake`, appears in the set's `warnings`, and appends ` (film again: <reasons>)` to `table.md`.
+- **Changed: cycle alignment leaves out start-stop retake, cycle-unwitnessed and cycle-four-steps loops (`batch.align_gaits`, `video-set --align-cycles auto`, `local_cycle.four_steps`).** Takes flagged with `start-stop` retakes loop no two steps, loops whose cut nothing witnesses whole cycles (`cycle-unwitnessed`: crossings left on steps unwitnessed, or a cut the cut witness held) may hold half a cycle or two, and the warning says so, and loops whose cut witness says four steps (`cycle-four-steps`) hold two cycles where their strip counts two steps (`steps: 2`, which `video-cycle-align` reads as one cycle) and would play twice as fast if aligned as one cycle; all are excluded from gait cycle alignment, keeping their loops as cut while aligning the remaining directions. Excluded items are recorded under `left_out` (`{item: reasons}`, listing `["start-stop"]`, `["cycle-unwitnessed"]`, `["cycle-four-steps"]`, or `["start-stop", "cycle-unwitnessed"]`) with a stderr warning and a set warning; if fewer than two directions remain, alignment is skipped (`applied: false`, `why: "fewer than two directions left to align"`). A left-out loop whose step screen suspects one step is told in its warning what settles it (`video-loop --steps 1`), as `video-cycle-align` says when it stops on such a loop, and `batch.left_out_why` takes `one_step`.
+- **New: a walk's cut is held to its body's word before it is cut (`loop._witnessed`, `local_cycle.cut_word`, `local_cycle.unwitnessed`, `local_cycle.held_verdict`).** In `video-loop --anchor motion-auto` (`--cycle auto` or `periodic`), after `loop._by_steps` chooses the cut and before frames are cut, `loop._witnessed(cycle, frames=...)` holds the cut s/L to `local_cycle.cut_word(signals, length)`, which reads `local_cycle.bob_word` on two lines, `local_cycle.CUT_LINES` (`'screen'` on the screen, less its flow, and `'feet'` over its feet with `local_cycle.over_feet`, `feet=True`), at length L, L/2 and 2L (a picture swaying up and down once a cut or slower hides the body's rise and fall twice the cut on the screen, where the line over the feet reads it; a walk whose lean changes slowly on its feet tilts the ground under them, so the line over the feet takes in the two feet's heights by turns and reads no rise and fall, where the line on the screen reads it) and says the first either line says in `local_cycle.CUT_WORDS`: `"two steps"` (a cycle), `"four steps"` (two cycles), `"one step"` (once in the cut), or null. On two steps or four steps the cut stands (`{cut: [s, L], ...cut_word's record}`; where the cut stands and its lowest row rises and falls twice the cut more than its top line on the screen, the record carries `mark`; it holds nothing), and a cut of four steps (two cycles), its strip still counting two steps, makes `local_cycle.four_steps(cycle)` true, and `video-set` leaves the item out of cycle alignment (`left_out` `["cycle-four-steps"]`); anything else is held exactly as chosen (two clip crossing intervals where counted, else the search's cut), setting `cut_witness.held` to `"unwitnessed"`, warning `cycle-unwitnessed` (`local_cycle.held_verdict(cycle)` via `local_cycle.step_verdict`), and marking `local_cycle.unwitnessed(cycle)` true so `video-set` leaves the item out of cycle alignment (`left_out` `["cycle-unwitnessed"]`), while cuts the step count already held record `held: "step count"`. A reading of `"one step"` is held and never cut again two long because a body rising and falling once in the cut cannot be distinguished between half a cycle of legs drawn alike and a full cycle of a limp or bouncing legless body without reading legs, and the witness never lengthens or shortens a cut; walks whose body rises once a cycle, legless bodies bouncing once in the cut, and walks carried whole with no rise of their own are held and named even where a cut is a whole cycle. It now reads the cut `_two_lengths` handed it, so what it reads is the cut that will play: a cut made two lengths long is read at that length, and it stands, or is held and named, as any other cut.
+- **Changed: the body's own rise and fall is read against the lowest opaque row as well (`legs.body_signals` `sole`, `legs.OPAQUE`, `local_cycle.own_beat`).** `legs.body_signals(frames)` now returns `sole` per frame, taking the lowest row with an alpha of `legs.OPAQUE` (255) or the lowest solid row where none is opaque. `local_cycle.own_beat(signals, interval)` reads `sole` with `twice_an_interval` and takes `less_lowest` as the top line's rise and fall less the lowest solid row's or less the lowest opaque row's, whichever leaves less, returning `sole` as rows up and down. This prevents a translucent shadow drawn fixed on the screen under the feet from acting as the lowest solid row and registering picture shake twice an interval as the body's own rise against it, since opaque feet move with the picture.
+- **New: the order the feet are drawn in witnesses a walk's steps (`legs.feet_order`, `legs.CONTACT`, `local_cycle.order_word`, `ORDER_ROWS`, `ORDER_TRAVEL`, `ORDER_SWAY`, `ORDER_REACH`, `ORDER_SLACK`, `ORDER_WORDS`).** `legs.feet_order` tracks which foot is drawn lower in each frame, and `local_cycle.order_word` gates side changes to witness one, two, or four steps across a span from non-side views. From the front, the back, or a diagonal, the foot nearer the viewer is drawn lower, and the nearer foot changes sides once a step, twice a cycle. The view's label is not taken for it, because a generated walk's label may be wrong: the clip must show that its two sides of feet are its two legs, or nothing is witnessed. `read_cycles` and `cut_word` read the foot drawing order when body cues do not witness crossings or cuts, and search cuts that failed to close are held unwitnessed rather than stood by foot order. A diagonal walk whose feet pass each other on the screen, one foot always drawn lower and the other passing it on either side, shows the same changes a side walk does, and the order does not witness it; a side walk is never read on the order. Before its gates, `local_cycle.order_word` leaves out frames whose contacts touch no column of anything standing on the lowest row in any frame, recorded in `off_ground`, so a dipping tail is not read as a foot and changing sides to count half a cycle as a whole, at the cost of leaving out feet lifted over columns where nothing ever stands. As a named limit, a tail hanging over the columns the feet stand on is still read as a foot, held only by the gates after the reading (the sliding check, the ground travelled, and the upper body's sway).
+- **Changed: standalone `video-cycle-align` stops on held or four-step cuts (`align.held_cut`).** `video-cycle-align` run on its own reads the cut report beside each loop through `align.held_cut(loop_dir, meta_path, meta)`. Where nothing witnessed the cut whole cycles (`cycle-unwitnessed`) or the cut spans four steps (`cycle-four-steps`), the loop is named under `held` and the aligner stops under `--multi-cycle fail` before rewriting any files, adding "and nothing witnessed some of the cuts whole cycles". Under `--multi-cycle warn` it aligns the loop with a warning, matching `video-set` instead of aligning held loops as one cycle without a word.
+- CLI: `video-loop --view front|back|side|front_diagonal|back_diagonal` (default none) sets the clip view for cycle detection and foot cue selection.
+- Report fields: `cycle.step_count.cycles` (`{asked, interval, overlap, half, one, two, slack, cue, bob, cycles, unwitnessed, why}`, where `cue` and `bob` are recorded only where the picture passes, `cue: {range, floor, swapped, one, says, why}` only with a view, `one` absent where `says` is `"alike"`, `bob: {swing, rows, floor, twice, half, quarter, edge, body: {beat, lowest, sole, less_lowest, less_bands, still_bands, own, bands: {rows, width, zoom, beat, reads, less}, share, scale, least, scale_least, band_floor}, says, why}`, `half`, `quarter`, `edge` and `body` absent under the floors, `body` absent where under 8 frames are left, and `why` absent where it says `"cycles"`, and `unwitnessed` true only where nothing witnessed); the loop's warnings (`jolt.warnings`); `step_count.stands` and `step_count.run_limit`; `loop.retake` (`{reason: "start-stop", reasons, start_stop: {stands, run_limit, crossings, cut, verdict, code, why}, remedy: "retake"}`); the set report's item `loop.retake` (`{reason, reasons, remedy}`) and item `loop["cycle-unwitnessed"]` (`true`), and its state's `cycle_align.<state>.left_out` (`{item: reasons}`); the loop report's `cycle.cut_witness` (`{cut, says, by, lines, on, why, held, mark}`, `lines` (`{screen, feet}`, each `{says, bob, on, why}`), the feet line's `bob` and `on` with `over`, `by` only where it says a word, `on` with its `line` and `interval` only for four steps or one step, `why` only where `says` is null, `held` only where held, and `mark` only where marked); the printed summary's `cycle.cut_witness` (`{cut, says, by, held, mark}`, each where present). `cycle.step_count.cycles.order` and `cut_witness.order` record foot-order metrics (`apart`, `swing`, `floor`, `changes`, `slides`, `spacing`, `travel`, `sway`, `tilt`, `per`, `says`, `why`, `off_ground`), and `video-cycle-align` reports held suspect loops under `held` with `{reason, report}`.
+- Python callers: new `local_cycle.read_cycles(reading, distances, view=None, cue=None, cue_step=None, signals=None)`, `local_cycle.bob_word(signals, interval, feet=False)`, `local_cycle.twice_an_interval(values, interval)`, `local_cycle.own_beat(signals, interval)`, `local_cycle.cut_word(signals, length)`, `local_cycle.over_feet(signals, interval)`, `local_cycle.unwitnessed(cycle)`, `local_cycle.four_steps(cycle)`, `local_cycle.held_verdict(cycle)` (refuses with a `ValueError` a cut held on one step whose record names no line it was read on (no `by` or `lines`)), `legs.OPAQUE`, `local_cycle.BOB_OWN`, `local_cycle.BOB_SCALE`, `local_cycle.BEAT_FRAMES`, `legs.body_signals(frames)`, `legs.BANDS`, `legs.band_rows(median)`, `legs.band_widths(alpha, rows)`, `legs.zoomed(alpha, scale)`, `local_cycle.BAND_FLOOR`, `local_cycle.off_flow(values, interval)`, `local_cycle.cue_word(cue, interval, step=None)`, `local_cycle.BOB_TWICE`, `local_cycle.BOB_FLOOR`, `local_cycle.BOB_ROWS`, `local_cycle.CUT_LINES`, `local_cycle.CUT_WORDS`, `local_cycle.UNWITNESSED`, `local_cycle.FOUR_STEPS`, `local_cycle.CUE_FLOOR`, `legs.TONE`, `local_cycle.repeat_at(distances, span)`, `batch.anchor_for(state, cut, anchor)`, `batch.left_out_why(reasons, stands=False, one_step=False)`, `loop.stand_retake(cycle)`, `loop.retakes(*records)`, `loop.STAND_REASON`; `crossings._alternation` is now public `crossings.correlation_on(values, span)`; `align._feet`, `align._depth_cue`, `align._shade_cue`, and `align.SHADE_BAND` are moved to `legs.feet_halves`, `legs.depth_cue`, `legs.shade_cue`, and `legs.SHADE_BAND` (`align` keeps `_depth_cue` and `_shade_cue` aliases); `crossings.Reading` gains `interval`, `per`, `cycles`, `hides`, and `mark_cycles(said)`. `local_cycle.read_cycles` and `local_cycle.cut_word` take `order`, `cut_word` takes `declined`, and `align.held_cut` checks loop cut reports.
+- **Tests**: `tests/video/test_walk_steps.py` covers these synthetic walker cases (the walkers' bodies rise and fall on legs whose soles stay on the ground unless held still or drawn carried whole; the walkers whose body is witnessed (and those the cut's witness reads one step of) swing their arms within the body's sides, 8 px either way of its middle (`ARMS_IN`), the body's sides 28 px apart; the other walkers seen from the side, from behind or on a front diagonal swing them 16 px either way of the body's middle, past its sides; the walker seen from the front swings its arms up and down beside its body, and some walkers have no arms):
+ - a walker seen from behind whose far foot hides behind the near one (feet together over half the interval) across cycles of 20 frames on twos, 24 on threes, and 17.5 and 18.5 on ones: its top line rises and falls twice an interval, cutting one cycle within a frame with `cycles` true, `steps: 2`, and no cue read with no view, its bob's `body.share` at least `0.3`, `body.scale` at least `0.6`, `edge` 0, every band seen holds still on the beat (`still_bands` equals the bands seen), and its `why` naming the body's own; the same walker with its far leg drawn as the near one (legs alike), with no view and with `--view back_diagonal`, is still cut to one cycle because the view's cue says `"alike"` (which no longer refuses) and the bob witnesses;
+ - a front-diagonal walker whose near foot steps out toward the camera and passes the far one apart (feet together under half the interval, cycle 16 and 18): with `--view front_diagonal` cut to one cycle because its foot cue moves over the floor and does not turn over one interval on (`says` null) and its top line rises and falls twice an interval; without a view it is not asked and is cut to two cycles (32, 36 frames); its cut witness says `"four steps"`, its strip says `steps: 2`, and `local_cycle.four_steps` is true;
+ - the walker seen from behind (17.5 on ones; no view and `--view back_diagonal`) and the front-diagonal walker (16, `--view front_diagonal`) with their bodies held still: the top line does not rise and fall (the line left under `BOB_FLOOR` of the body's height and under `BOB_ROWS` rows), keeping two intervals (two cycles) with `cycles` false, `unwitnessed` true, and the warning naming the cut;
+ - a side walker whose two steps are one silhouette (46-frame cycle, near and far a tone or four apart), passes brief: not asked with no view or `--view side`, keeping two steps at 46 frames; the cut's witness then reads the cut: the arms move the bands they swing over on the beat, so nothing that reads no leg witnesses the cut whole cycles, and the cut is held as cut and named (`cycle-unwitnessed`, the warning), its why naming the upper body's width;
+ - the same 46-frame walker filmed as a front diagonal, its far leg four tones off the near one, `--view front_diagonal`: the picture passes, but the foot cue turns over one interval on (`says: "steps"`), keeping two steps at 46 frames; its cut is held as cut and named by the cut's witness (the warning), for the same reason;
+ - the same 46-frame walker with its legs drawn alike (arms still four tones apart) asked with `--view` set to `front`, `front_diagonal`, `back`, and `back_diagonal`: the picture passes, the cue says `"alike"`, and its top line rises and falls once an interval (a step), so its `half` correlation is negative, leaving nothing to witness and keeping two steps at 46 frames with `unwitnessed` true and the warning;
+ - the same 46-frame walker with its legs drawn alike and twice as wide (10 px either side of its line instead of 5), so the feet are seen together over half the interval and a pass could hide: asked with no view and with `--view` set to `side`, `front_diagonal`, and `back`, keeping two steps at 46 frames with `unwitnessed` true and the warning (with a view the cue says `"alike"`, and with no view no cue is read);
+ - the wide alike walker lit by a light fixed on the screen, lighter to the right (up to 12 tones across the feet), with no view and with `--view` set to `side`, `front_diagonal`, and `back_diagonal`: the shade of the feet moves with how far apart they are drawn and turns over half an interval on, but nothing witnesses, keeping two steps at 46 frames with the warning;
+ - the alike walker (legs 5 px) with the leg swinging forward lifted 6 px at its pass and a light fixed on the screen varying top to bottom (12 tones), asked with `--view` set to `front`, `front_diagonal`, `back`, and `back_diagonal`: the cue moves with the swing whichever leg swings and turns over half an interval on, but nothing witnesses, keeping two steps at 46 frames with the warning;
+ - the wide walker with its far leg four tones off the near one (where a pass can hide): with `--view side` or `front_diagonal` the cue turns over one interval on (`"steps"`), keeping two steps at 46 frames with no warning, while with no view no cue is read and nothing witnesses, keeping 46 frames with `unwitnessed` true and the warning;
+ - the wide legs-alike side walker (46-frame cycle, crossings every 23 frames, a pass can hide), carried up and down with the whole picture: along a smooth arc 24 px deep, and, with its body held still, along the same arc, along a sway 12 px either way, four intervals long (92 frames), and down a ramp 24 px over the clip, a row every three frames; each is cut two steps, 46 frames, with `unwitnessed` and the warning; for the bobbing walker its `half` is `-0.28` or less (less its flow its line rises and falls once an interval); for the still one its `rows` is under `BOB_ROWS`; before this change every one of the four was cut one step, counted two, and no warning said so;
+ - the walker seen from behind whose far foot hides behind the near one (cycle 17.5 frames on ones, legs drawn alike), carried along the arc and the cubic: cut one cycle; the bob says `"cycles"` with its `quarter` at `-0.28` or less;
+ - synthetic units meeting every 15 frames verify that where a pass can hide (feet together 9 frames at each meeting), a top line rising and falling every 7.5 frames (twice an interval) marks cycles (15 frames kept as one cycle, `steps: 2`), while rising and falling every 15 frames (once an interval) or held still keeps two steps of 15 (30 frames) with `unwitnessed` true and the warning; brief meetings with no view or `side` are not asked; on front diagonals with brief meetings, a cue turning over every 15 frames (one interval on) keeps two steps of 15 (30 frames) whatever the body does, and a cue turning over half an interval on and holding one interval on is no witness (30 frames with the warning when the top line is once an interval, 15 frames and one cycle when twice an interval); a still cue (range far under half a tone) or one flickering every 4 frames refuses nothing, letting the body decide (twice an interval: one cycle of 15; held still: 30 with the warning) on front diagonals with brief meetings, back diagonals where a pass can hide, and with no view where a pass can hide; and `bob_word` on an interval of 15 frames for a body 100 rows tall says `"cycles"` with 3 rows either way every 7.5 frames, says null every 15 or 30 frames, and says null under the floors at 0.2 rows either way without reading `half` or `quarter` (`swing` and `rows` are the range of `off_flow`'s line), while for a top line in whole rows on a picture held still or carried along an arc 24 rows deep, a cubic 48 rows either way, a sway 12 rows either way four intervals long, or a ramp of 6 rows over the clip, rising and falling twice an interval says `"cycles"` under every one, once an interval, or not at all, says null under every one, and not rising at all, on the still picture, the arc, the cubic or the ramp, the line left is under `BOB_ROWS`, and `off_flow` over intervals of 15 and 17.5 frames takes a cubic flow out wholly and leaves a rise and fall once or twice an interval as it was (less its straight line) over the frames the interval fits about;
+ - the walker seen from behind whose far foot hides (cycle 17.5 frames on ones, no view) and the front-diagonal walker whose near foot steps out (cycle 16, `--view front_diagonal`), their bodies rising and falling twice an interval carried whole, feet and all: cut two intervals, `unwitnessed`, the warning; the bob's `half` is `0.28` or more and its `quarter` `-0.28` or less (the top line alone rises and falls twice an interval), its `body.share` is under `0.3`, and its `why` says its lowest row rises and falls with it;
+ - the wide legs-alike side walker (46-frame cycle, its crossings its steps every 23 frames, a pass can hide), held still or rising and falling on its legs once a step, on a picture shaken up and down 3 px twice an interval (dy = round(3 sin(4 pi k / 23))): two steps, 46 frames, `unwitnessed`, the warning; held still, its bob's `half` is `0.28` or more and `quarter` `-0.28` or less, and its `why` says its lowest row rises and falls with it;
+ - the walker seen from behind (17.5, rising and falling twice an interval on its legs), its frames cut at the soles' row so the lowest row is each frame's last: two intervals, `unwitnessed`, the warning, `edge` over 0 and a `why` naming the frame's last row;
+ - `twice_an_interval` over intervals of 15 and 17.5 frames: a line rising and falling 3 rows either way twice an interval, with a rise and fall of 2 rows once an interval and a cubic flow 48 rows either way laid on it, reads 3 rows (within 0.15); the same rise and fall on a constant reads within 0.15 of it; 14 frames over an interval of 15 read None;
+ - `bob_word` over an interval of 15 frames, the body 100 rows tall, its lines in whole rows: a top line rising and falling 3 rows either way twice an interval with the lowest row still says `"cycles"` (`share` over 0.9, `scale` 1); the same rise and fall with the lowest row rising and falling with it (the body carried up and down whole, or held still on a picture shaken twice an interval: the same lines) says null, its `why` naming the lowest row; a rise and fall of 3 rows of its own on a picture shaken 12 rows with it (its own a fifth of the line's, under `BOB_OWN`) says null;
+ - `bob_word`: the body zoomed in and out twice an interval with the picture about its feet (3 % either way: the top line 3 rows, the lowest row still) or about its middle (6 %: the top line and the lowest row 3 rows either way, turned over from each other), its upper body's width and height scaled with it: null, `scale` under `0.6`, its `why` naming the upper body's width;
+ - `bob_word`: the planted rise and fall says `"cycles"`; the same with the lowest row on the frame's last row in one frame of 73 says null, `edge` 1, `why` "in 1 of 73 frames";
+ - read off drawn frames with `legs.strike_signals` and `legs.body_signals`: five walkers that do not rise and fall twice an interval on their legs (the wide legs-alike side walker, interval 23, held still, carried whole bobbing once a step, or rising and falling on its legs once a step; the walker seen from behind, legs alike, interval 17.5, held still or carried whole rising and falling twice an interval), each moved up and down with the whole picture 3, 6 or 12 px either way every d/4, d/2, d or 2d frames (d its interval) at four phases: none is witnessed. Three of them (the side walker held still and on its legs, the walker from behind held still) zoomed in and out 0.5, 1, 2 or 4 % either way every d/4, d/2 or d frames about the feet, the middle or the head, at two phases: none is witnessed;
+ - the wide walker, its head's top flat, round, pointed or two ears' tips, held still or rising and falling on its legs once a step, zoomed in and out 4 % either way with the picture about its feet, middle or head every quarter, half or whole cycle (11.5, 23 or 46 frames): never two steps an interval of a step (23 frames), nor a cut of a step said to be a cycle or two, nor a cut of two cycles (92) said to be one; cut through the loop, the walker with a pointed head or ears zoomed every quarter cycle (11.5 frames), and the walker with a pointed head held still zoomed about its feet twice a step, are never cut half a cycle unnamed;
+ - a top line rising and falling twice an interval on legs whose feet stay on the ground witnesses two steps an interval on a body whose sides run straight down; on a cone from a point at its top (where a zoom would move no band a pixel) or where any band of its upper body moves on the beat: every band widening and narrowing 2 px either way twice an interval a quarter of the beat on, with or without the band across its head's top holding still, is held by default, the word saying why ("its upper body's width changes with it"); with every band holding still the word says "cycles";
+ - the walker seen from behind whose far foot hides (17.5 on ones, no view) and the front-diagonal walker whose near foot steps out (16, `--view front_diagonal`), rising and falling 3 px on their legs once a step as the walkers cut one cycle do, their arms swinging 16 px either way of the body's middle, past its sides: cut two intervals, `unwitnessed`, the warning; `body.less_lowest` at least `BOB_OWN` of `body.beat`, `body.scale` under `0.6`, the largest band `reads` over `0.4`, `still_bands` fewer than the bands seen, and the why naming the upper body's width and that the picture may zoom with the body.
+ - the walkers the tests witness, or whose cut the cut's witness reads one step, drawn instead with their arms swinging 16 px either way of the body's middle, past its sides (nineteen forms, `PAST_ITS_SIDES`): none is a silent half cycle. A walk whose feet meet once a cycle (the walker whose far foot hides, 18.5 frames on ones, 20 on twos and 24 on threes; the same with its legs drawn alike, 17.5 and 20, with no view and with `--view back_diagonal`; the front-diagonal walker whose near foot steps out, 18, `--view front_diagonal`; the walker whose far foot hides, legs alike, carried along the arc and the cubic; the same walker turned 15 degrees about its feet over the clip) is cut two intervals, `unwitnessed`, the warning, its bob's `why` naming the upper body's width. Any other cut is held as chosen (`cut_witness.held` `"unwitnessed"`, its word null, the warning): 46 frames for the wide walker with its far leg four tones off (`--view side` and `--view front_diagonal`), 23 for the sliding foot and for the walker held still over a shadow on a picture shaken twice a step, 30 for the limp, and a cycle for the walks on a picture swaying once a cycle or slower.
+ - the wide walker held still on its legs, zoomed in and out 4 % either way with the picture about its feet twice a step (every 11.5 frames), its head drawn narrower as the picture zooms in, and the body under it swinging on the beat: its torso's half width 4 px either way a quarter of the beat off the zoom, in step with it, or against it; or a crown 13 rows deep drawn narrower as the picture zooms in over a cape widening and narrowing 4 px either way a quarter of the beat before the zoom: cut through the loop it is held (`unwitnessed`), never cut 23 frames (half a cycle) as two steps unnamed; read off its frames at an interval of 23, its top line rises and falls twice an interval (`half` at least `BOB_TWICE`, `quarter` at most `-BOB_TWICE`), at least one band holds still on the beat, and the word says null, its why naming the upper body's width.
+ - read off 128 drawn frames at an interval of 16, a column 20 px wide on feet planted at row 140, its top rising and falling 3 rows either way twice an interval, its crown (11 rows) and the column under its shoulders holding still, and its shoulders (the 41 rows under the crown) widening and narrowing 2 px either way a quarter of the beat on: five bands are seen, one holds still and four move on the beat, and the word says null, its why naming the upper body's width.
+ - the side walker rising and falling on its legs once a step (its crossings its steps), running: both soles lifted up to 1, 2, 3 or 6 px off the ground while the body is high; still or on a picture moved 6 px either way every d/2 (two phases) or every d frames: never witnessed;
+ - the side walker drawn as a view from behind or a diagonal draws feet, each sole up to 6, 12 or 24 px lower the further back its foot is, the foot moving forward lifted 8 px (the lowest row is the planted foot, sliding down the screen through its step); still, or on a picture moved 3, 6 (four phases) or 12 px either way every d/2 frames, or 6 px every d: never witnessed;
+ - synthetic start-stop clips with feet together for 15 frames at the head and 14 at the tail alongside passes of 8 and 3 frames flag retakes when the cut is uncertain, omit retakes when counted as two steps, and report no `stands` when feet only pass.
+ - `cut_word` units on a cut 16 frames long with a body 100 rows tall on feet that stay on the ground report "two steps", "four steps" (`on.interval` 8), "one step" (`on.interval` 32), and null as its top line rises and falls 3 rows either way every 8, 4, or 16 frames or is held still: both lines say the word, `by` is both lines; where null, each line's why is in `why`.
+ - a record held on one step with no `by` or `lines` (built from `cut_word`'s record of a top line rising and falling once in a cut 16 frames long, its reading over the feet kept at its top) is refused by name, a `ValueError`, through `held_verdict` and through `step_verdict`; the same with nothing read (`says` null, its why kept) gives one warning naming its why and `cycle-unwitnessed`.
+ - a unit with the body on a picture moved 3 rows up and down twice an interval of 15 frames and a translucent shadow fixed on the screen as its lowest solid row yields `says` null with "its lowest row rises and falls with it" when read against the lowest opaque row, and reports "cycles" with the lowest opaque row where the lowest solid row is.
+ - the shadow walker: through the loop it is drawn with its arms swinging past its sides, leaving the step count no feet to read so the search cuts 23 frames, held at 23 and named with null whether it rises and falls on its legs or is carried whole; drawn with its arms within its sides and read off its frames (`cut_word` on the cut's length), the word says "one step" when it rises and falls on its legs and null when carried whole; so drawn, the loop refuses it: its wrap jumps (the seam ratio over 2.0), as it does where the walker is held still on its legs.
+ - the same walker swinging its arms within its sides with each sole drawn up to 12 px lower the further back its foot is and the foot moving forward lifted 8 px has the step count count the search's 23 frames as two steps, returning "one step", held and named.
+ - the same walker over a shadow fixed on the screen apart under its feet on a picture shaken 12 px up and down every half step counts two steps by the crossings with a cut of 14 frames or under, held and named.
+ - the same walker on a picture moved 12 px up and down every two thirds of a step has the search cut 16 frames or under, held and named.
+ - the same walker swinging its arms within its sides held still on its legs over a shadow fixed on the screen touching its soles on a picture shaken 6 px twice a step reads no feet, cuts 23 frames; on the screen its top line rises and falls twice the cut with the picture (`half` at least `BOB_TWICE`, `quarter` at most `-BOB_TWICE`), and its lowest opaque row (the feet's) with it, more than the lowest solid row (the shadow), its why saying its lowest row rises and falls with it; over the lowest opaque row (`over` `sole`) its top line holds still (under `BOB_ROWS` rows: "does not rise and fall"); neither line witnesses the cut, and it is held and named (read over the lowest solid row alone, the shadow holding still, the picture's shaking witnesses "two steps" with every band of its upper body holding still on the beat).
+ - a walk rising and falling on its legs once a step, swinging its arms within its sides, its feet on the ground, on a picture swaying up and down once a cycle or slower (the wide walker with its legs drawn alike, crossings every 23 frames, a cycle of 46 frames, the picture swaying 12 px either way every 46 frames or 24 px every 69 frames; and the walker whose far foot passes hidden, 20 frames a cycle on twos, the picture swaying 24 px every 40 frames, up first) is cut one cycle, its cut witnessed `"two steps"` by the line over its feet (`by` includes `feet`), read over `reach` or `sole`, not held, no warning (read on the screen alone, the sway hides the body's rise and fall twice the cut, and the cycle would be held).
+ - the walker whose far foot passes hidden behind the near one, its legs drawn alike, its feet meeting once a cycle (17.5 frames), rising and falling on its legs once a step, turned 15 degrees about its feet over the clip (k/72 of it in frame k, on a canvas 60 px taller above and below: a lean changing slowly on its feet), swinging its arms within its sides: it cuts one cycle (within 1 frame of 17.5), the count reading its crossings as cycles (`cycles` true, `steps: 2`); on the screen the top line, less its flow, rises and falls of its own twice the cut, every band of its upper body seen holding still on the beat: the cut's witness says "two steps", the screen among the lines that say it (`by`), not held, no warning; read off its frames on a cut of 18, the line over its feet says null: it does not rise and fall twice an interval (the lean tilts the ground under the feet, and the line over them takes in the two feet's heights by turns), where the line on the screen says "two steps" (`by` the screen alone).
+ - a side walker whose legs four tones apart tell its steps apart on a 30-frame cycle, swinging its arms within its sides, filmed 100 frames, with its body sinking 3 px once a cycle and not at each step (a limp) is cut 30 frames by the search, two steps by the crossings, returning "one step", held and named, and is never cut 60 frames long.
+ - the legless body bouncing every 16 frames: the search cuts one bounce (16 frames, within 1) and the cut stands as cut, never cut again two long; it squashes as it bounces, so its upper body's widths, read on rows below its top, change with it on that beat: nothing witnesses the cut (`says` null), and it is held and named; read on twice its cut, its top line rises and falls twice that interval and the word says null, its why naming the upper body's width.
+ - the walker seen from the front whose feet stay apart (stepping foot drawn up to 3 px under the ground, the other as far over it; right foot swinging in to meet the left only while it is drawn higher, the other foot drawn lower and nearer the viewer, and back out before it is drawn lower; no foot standing on the ground sliding along it; arms swinging within the body's sides; body not rising and falling), 20-frame and 24-frame cycles, `--view front`: cut one cycle, `steps` 2, `cycles.order.says` "two steps", zero slides, travel under `ORDER_TRAVEL` of spacing, body word null, `cut_witness` "two steps" by `["order"]`; with `--view side`: cut two intervals, `cut_witness.held` "unwitnessed", no order read (previously cut two intervals with a warning).
+ - the walker from the side with legs drawn alike (46 frames, swinging leg lifted 6 px at pass) with no view and with `--view` front, front_diagonal, back, and back_diagonal: cut 46 frames, `steps` 2; crossing check has `cycles` false, `order.why` value stating a foot passes under the body; cut never stands on order.
+ - the walker whose feet stay apart (cycle 30) tested across spans in `local_cycle.order_word`: spans of 30, 60, and 15 frames, `says` value "two steps", "four steps", and "one step", span 22 none, also checking that no foot slides and that the upper body's sway stays under `ORDER_SWAY` of the tilt; picture rocked 10 degrees either way about feet once a cycle, feet drawn level and still, `says` null, `why` value stating it may rock on its feet; the same walker drawn with its right foot sliding along the ground, planted, to meet the left as both stand level and back out, `says` null, `why` value stating a foot slides (the order is not read where a foot on the ground passes under the body toward the other side); lifted-foot side walker with legs 5 and 10 px either side of line, `says` null, `why` value stating a foot passes under the body; rear walker with soles on one row, `says` null, `why` value stating feet are drawn level.
+ - the walker whose feet stay apart cut 20 frames, `--view front`, under `loop._witnessed`: cut stands on order, `by` `["order"]`; with step count `declined` record set: cut held, `cut_witness.held` "unwitnessed", `order.read` "two steps", `order.why` value stating order does not stand a length the closing refused.
+ - the walker seen from the front whose feet stay apart (cycle 30 frames, body still), its feet meeting on the screen once a cycle, or once a step where `each_step` is set (the left foot swinging in to meet the right while drawn higher), drawn with a tail (`_dipping_tail`: from the hip to a tip 28 px to its left, rising and falling 8 px either way on a 17-frame beat of its own, dipping into the foot band about a third of the time, never as low as the feet nor over a column they stand on): `order_word` over 30 frames (meeting once a cycle) says "two steps", over 15 frames (once a cycle) and over 15 frames (once a step) "one step", what the same walker drawn without the tail says, never "two steps" where the walker holds one, with `off_ground` exactly the frames whose left side is the tail and no counted change falling on them (before: the tail's frames were read as feet, and over 30 frames the walker meeting once a cycle said nothing).
+ - the 46-frame side walker lifting its swing foot 6 px, drawn with the tail 40 px behind: `off_ground` is the tail's frames, `says` is null and its why says a foot passes under the body (before: null as well, the tail's frames read as feet).
+ - slow test of the walker meeting once a step with the tail, `--view front`: its crossings are never read as cycles, the cut witness stands a cut on the order (`by` `["order"]`) only where the cut is within 1.5 frames of the 30-frame cycle, and no cut under three quarters of the cycle is handed out without a warning naming it (before: `video-loop` stopped on the division by zero).
+ - the walker meeting once a cycle (cycle 30, body still, no tail): `cut_word` returns on every cut length from 10 to 46 frames; on cuts of 25, 26, 34 and 35 frames it says null with a why containing "its top line holding still" (before: it stopped on cuts of 13, 17, 25, 26, 34 and 35 frames).
+- **Tests**: `tests/video/test_gait_guard_anchor_wide.py` and `tests/video/test_cycle_align.py` cover batch anchoring and cycle alignment:
+ - `batch.anchor_for` assigns `motion-auto` to walk and run loops while assigning `none` to cheer, walk with `--anchor none`, and pinned idle items, propagating loop retakes to item records, warnings, and markdown tables;
+ - `batch.align_gaits` excludes loops with a `start-stop` retake, a loop with `cycle-unwitnessed`, or a loop with both, names its reasons under `left_out` (`["start-stop"]`, `["cycle-unwitnessed"]`, `["start-stop", "cycle-unwitnessed"]`) and in the stderr warning, aligns remaining directions, and leaves the state unaligned when fewer than two directions remain.
+ - `batch.align_gaits` with three directions, two loops of one cycle (20 and 24 frames) and one loop of two cycles (40 frames) whose strip says `steps: 2` and whose cut witness says four steps: the two-cycle loop is left out under `left_out` (`["cycle-four-steps"]`) and named in the warning, its loop and strip kept as cut (40 frames, `steps: 2`), and the other two are aligned to their median length.
+ - three walker loops with reports beside them, the third loop marked held (`cut_witness.held` "unwitnessed") or four steps (`cut_witness.says` "four steps", strip `steps: 2`, walker two cycles long): standalone `video-cycle-align` stops with one suspect, `held` value `{reason, report}`, `settle` value `=1` and `=2`, nothing rewritten; `--multi-cycle warn` aligns and names reason; `--cycles` 1 or 2 aligns it, suspect `status` "counted" (previously aligned as one cycle without a word).
+- **Tests**: `tests/video/test_one_step_cut.py`: a side walker whose cycle (42 frames) the walk window cannot hold is cut one step long (21 frames) by the pixel search, its feet read as unseen, and the step screen names it; before, the test said nothing else speaks (no `steps` and no warning about steps), whereas now there are still no `steps`, the walker is carried whole on its legs, so its cut witness holds the cut (`cut_witness.held` is `"unwitnessed"`, `local_cycle.unwitnessed` is true), and the one warning that speaks of steps is the witness's (`local_cycle.held_verdict`), naming `cycle-unwitnessed`. In a set of two items, the same walker on a 25-frame cycle (front, cut a whole cycle) and the one-step side walk, their rows now carry the marks `run_set` records (`cycle-unwitnessed` from `local_cycle.unwitnessed`, and `step_screen`) instead of rows built without them; both are left out of the alignment (`left_out` `["cycle-unwitnessed"]` each, `why: "fewer than two directions left to align"`), each warning says nothing witnesses its cut whole cycles and it may hold half a cycle or two, only the side walk's warning adds that it may be one step (cut it again with `video-loop --steps 1` if it is), `video-cycle-align` run on the items' loops reads the step screen in the report beside the side walk's loop and stops on it (`one_step`), naming `--steps 1`, and the set table still marks the side walk's cycle `(one step?)`. The walker carried whole on its legs across the two set tests: `video-cycle-align` now stops on both loops, each named `held`, `reason` "cycle-unwitnessed", the side loop also suspected one step; a count of one cycle for each settles it.
+- **Tests**: `tests/video/test_cycle_suspects.py` and `tests/video/test_loop_prop_seam_held.py` cover standalone `video-cycle-align` on loops whose cut reports hold their cuts:
+ - three synthetic loops in `tests/video/test_cycle_suspects.py` (S and E one stride of 24 frames each, NE two strides of 15 frames, 30 frames held on twos, as a two-cycle cut leaves it, with NE's cut report beside it as `video-loop` writes it holding its cut because nothing witnesses it whole cycles): stopping the set, run twice, names NE with its report beside it both for what the report holds (`held`, reason `cycle-unwitnessed`, with the report's path: it may hold half a cycle, one or two, and the message names `video-loop` to cut it again if it is one step) and for its return at 15 frames (it may also hold 2 cycles of 15 frames), while with the report removed (a loop cut by other means) it is named only for its return with no `held` and no mention of `video-loop`, both offering settle `=1` and `=2` with nothing rewritten (previously one run, NE named only for its return, and the message never named `video-loop`); `--multi-cycle warn` aligns the set as it is, NE's warning starting with nothing having witnessed its cut whole cycles and adding that it may also hold 2 cycles (previously the warning started with it may hold 2 cycles); the command line (`align.main`) without a count exits naming the held cut and the return at 15 frames, and with `--cycles NE=2` aligns as before (previously the exit named only the return).
+ - two synthetic loops in `tests/video/test_loop_prop_seam_held.py` (one cut two steps long, one cycle, strip `steps: 2`, and one cut one cycle with no `steps`, neither walker's body rising and falling and its feet never passing, so both reports hold their cuts, nothing witnessing either whole cycles): on copies whose reports the test rewrites to witness their cuts (`cut_witness` saying "two steps" by the screen, nothing held), the aligner works as before: the two-step loop returns half way at its second step, which is no suspect (`status` "steps", `steps` 2, candidates `[2]`), and both loops are resampled to the median of their lengths as cut, nothing kept twice as long, the strip of the two-step copy still saying `steps: 2`, the other none; on the loops as cut, `video-cycle-align` stops on both, each named `held` with reason `cycle-unwitnessed`; a count of one cycle for each (`cycles`, the caller's word) aligns them as they are, to the same median length, each suspect `status` "counted"; a count of 2 for the two-step loop (and 1 for the other) still takes one half out of it, and its strip no longer says `steps`; two copies of the loop with no held part, aligned with a count of one cycle each, are written as before: no `cycles_kept` and no `steps` in their rows, their strip metadata with the same keys, and the cut's source (`source_cut`) as the cut wrote it (previously both aligned with no count, the two-step loop's return read as its steps).
+ - the synthetic cut of 13 cells with its record of its cells, aligned by `video-cycle-align` to 17 cells, in `tests/video/test_sway_read_on_recut.py` (with `--between rife` (a blend standing in for RIFE) the aligned strip record holds no `cell_record`, `cycle_align.cells_from` gives 17 cells, each `{"source": i}` cell is cell i of the cut pixel for pixel and each `{"between": [i, j], "t": t}` cell is a copy of no cell of the cut, `cycle.source/run.strip.json` is the cut's record with 13 cells, source frames 1 to 13, and `video-sway --read-on-cut` is refused `uncertain` on the pair the kept record gives (source frame 4), naming the first made cell, the loop as it was; with `--between nearest` every one of the 17 cells is one of the cut's, and `--read-on-cut` pairs source frame 4 with the cut's cell 3 at shift (3, 2) and carries it through, `cut_cells` equal to the `cells_from` sources).
+
+ ## Unreleased - Contract strings each written once and read by name
+
+ **Upgrading from 3.12.1: every output, report, JSON body, JSON key order, CLI choice and order, `--help` text, refusal and warning text keeps its bytes. Nothing a user runs behaves differently. One visible effect: `frames/extract.py` and `frames/decontam.py` changed, so `engine_revision` changes. The curation view's heal re-extracts each existing run once when it is next opened; the frames it writes have the same pixels. One edge: `python -m sprite_gen.serve.serve_curation`, `scripts/serve_curation.py` and `scripts/interpolate_frames.py` now load the image providers (`sprite_gen.gen`) when they start, because their default provider is read from a declared name. A malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` now stops them at start with its `ValueError`, instead of when a reroll or interpolate button is pressed. `sprite-gen curation` already loaded them, so it is unchanged. `python -m sprite_gen.video.loop` and `scripts/video_loop.py` read `gen.facing.FACINGS` when they run or build their arguments, so they load the image providers too, and a malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` now stops them with its `ValueError`, even for `--help` (`sprite-gen video-loop` already did). Importing `sprite_gen.video.loop` still loads no provider code.**
+
+ - **Internal: one declaration per contract string**: a key, kind, mode, provider name or key colour that two or more places write, read or branch on was spelt again at each place, so a one-letter typo passed every test (for example the curation server's `extractOk` spelt `extractOK` made the curator warn on every row with the suite green). Each is now declared once and every use names it:
+ - curation and composer servers: every key of the JSON the curator and composer read, in `serve_curation.Wire` (112 keys and the `X-Filename` download header) and `serve_compose.Wire` (16 keys, plus `TYPE_DIR`, `TYPE_IMAGE`); the heal report and progress file keys in `frames/extract.py` (`HEAL_*`, `PROGRESS_*`, `PROGRESS_PHASE_COMPONENTS`); `curation.CURATION_KIND`, `REF_ANCHOR`, `REF_BASIS`, `REF_GUIDE`, `BREATHE_PIXEL`, `BREATHE_SMOOTH`.
+ - image provider names `PROVIDER_CODEX`, `PROVIDER_GROK`, `PROVIDER_OPENAI` in `gen/base.py`, with `gen.PROVIDERS` and the other provider sets written with them; the curator's two buttons gated by one set, `serve_curation.CURATOR_PROVIDERS`; the reroll default is `gen.HARD_DEFAULT_PROVIDER`; the interpolate default is `interpolate.DEFAULT_PROVIDER` (codex, its own documented choice from the three-way comparison); the HTTP host names `address.OPENAI`, `XAI`, `ANTHROPIC`, `ELEVENLABS`; `retry.ELEVENLABS_BUSY`; `audio.manifest.KIND`, `SFX`, `BGM`; the workflow guide's journey, field and access names in `workflow/catalog.py` and `workflow/access.py`; `video-prompt` takes `gen.video.DEFAULT_MODEL` instead of a second copy; the choice to stop and ask when codex cannot run is `gen.CODEX_UNAVAILABLE_ASK`, which `gen.CODEX_UNAVAILABLE_CHOICES`, `gen.CODEX_UNAVAILABLE_DEFAULT` and the workflow catalogue read; the guide reports that choice under `gen.CODEX_UNAVAILABLE_SETTING`, the name it is saved by; `xai.AUTH_SOURCE_API_KEY` is `xai.AUTH_ENV`; `claude_login.CHILD_DROP` reads `anthropic_api.AUTH_ENV`; the codex binary's name is `codex_provider.BINARY`; `pixel_draw.EFFORTS` is `anthropic_api.EFFORTS`, the copy removed.
+ - key colours and modes: `cutout.KEY_TARGETS` with `MAGENTA` and `GREEN` beside it is the one table of key colours (`gen.chroma.KEYS` is built from it, `logo_matte.KEYS` is it, `slice_sheet.CHROMA_KEYS` is removed, the hex values in `prepare`, `unpack-atlas` and the curation server are derived from it); `cutout.KEYS` is cutout's own `--key` set; `OFF, AUTO, PALETTE = DECONTAM_MODES` and `CHROMA_RGB, CHROMA_YCBCR = CHROMA_MODES` are declared in `frames/extract.py`, and `frames.decontam.DECONTAM_MODES` and `video.frames.DECONTAM_MODES` are that same tuple; every `--decontam`, `--chroma-mode` and `--key` choice reads its declaration; `logo_matte.LETTERING_BOX`, `UNMIX`; `prompt_parts.CONFLICT`, `REPEAT`; `gen.chroma.KEY_BACKGROUND_TEXT`, `gen.logo.KEY_COLOUR_WORDS` and a scene report's `key_like_pixels` are keyed by `cutout.GREEN` and `MAGENTA`; `prop_plate.RGB` reads `KEY_TARGETS[MAGENTA]`; `video.frames.DECONTAM_DEFAULT` is `extract.AUTO` and video-frames' decontam branches read `OFF`, `AUTO` and `PALETTE`; `video-frames --alpha-mode` reads `effect.ALPHA_MODES`; the `method` a `gen.chroma` report states reads `extract.CHROMA_YCBCR` and `base.TRANSPARENCY_NATIVE`.
+ - kinds: `loop.REPORT_KIND`, `loop.REPORT_PASSED`; `spec.assets.ASSET_KIND`, `SET_SHEET_KIND` (`set_sheet.KIND` names it); `qa.motion.REPORT_KIND`; `video.evidence.SOURCE_KIND`; `nonloop.GAIT_STATES` (the copies in `qa.handed` and `video.batch` removed); `body_plan.BIPED`, `QUADRUPED`, `LEGLESS`; `effect.STATE` read by `video-set` and `video-prompt`; `pixel_gates.SPRITE`, `ICON`, `TILE`, `EFFECT` (`pixel_draw.KINDS` is that tuple); new names `spec.runio.REQUEST_KIND`, `video.frames.REPORT_KIND`, `video.align.REPORT_KIND`, `unpack_atlas.UNPACK_SOURCE_KIND`; `video-canvas` writes `prop_plate.CANVAS_REPORT`, the name the report is read by; the `kind` of a pixel-draw effect strip is `pixel_gates.EFFECT`; a `video-cycle-align` same-foot refusal states `align.RETAKE_FEET_REASON`.
+ - other copies: `sprite-request.json` and `curation.json` are read as `runio.REQUEST_FILENAME` and `curation.CURATION_FILENAME` everywhere they are written, opened or checked; `pixel_grid.PNG_MAGIC` is `base.PNG_MAGIC`; `restoration.ARTIFACT_SUFFIXES` is the one table of a restoration's five files (`restoration.ARTIFACTS` is its keys, the demo script reads it); `game_pack.SIDES` is `ui_kit.SIDES`; `video-canvas --facing`, `video-loop --facing` and a lateral view's check in `gen.handedness` read `gen.facing.FACINGS`; `effects.breathe.SIDE_NAMES` is keyed by `extract.FRAME_SIDES`.
+ - Values that no test bound before and that now cannot drift: the legless anatomy sentence key, `effect` in `video-set`'s states pinned to their first frame, the pixel-draw pick sheet's tile branch, the loop report kind `video-cycle-align` reads (its typo passed the fast bundle).
+ - Python callers: every name above is importable. Downstream imports keep the same objects: `sprite_gen.video.frames.DECONTAM_MODES`, `sprite_gen.frames.cutout.KEY_TARGETS`, `sprite_gen.gen.chroma.KEY_BACKGROUND_TEXT`, `set_sheet.KIND`, `pixel_draw.KINDS`, `batch.GAIT_STATES`. Removed: `slice_sheet.CHROMA_KEYS` (use `cutout.KEY_TARGETS`). `clip_prompt.DEFAULT_MODEL` is `gen.video.DEFAULT_MODEL`, imported (the same object). `qa.handed.GAIT_STATES` is now a frozenset (was a tuple); every use is a membership test. `sprite_gen.frames.cutout` now imports `frames.extract` when it loads (for the decontam defaults), so importing it loads more modules than before; `pixel_draw.EFFORTS`, `game_pack.SIDES` and `pixel_grid.PNG_MAGIC` stay importable as the same objects; `loop.FACINGS` is removed (use `sprite_gen.gen.facing.FACINGS`).
+ - **Curator**: the JS mirror `BREATHE_MODES` moved from `store.js` to `breathe.js`, with `BREATHE_SMOOTH` beside it; `gen-trigger.js`'s provider select mirrors `serve_curation.CURATOR_PROVIDERS`. No screen changes; `BREATHE_ROUND_KEYS` moved from `store.js` to `breathe.js`, beside the refusal that spelt the two keys.
+ - **Tests**: new `tests/serve/test_curator_wire_keys.py`: every key the curator and composer read is found in the scripts with the object it is read from, built from the declared value; every declared key is read or listed as unread, the unread ones spelt out in the test; the servers write no wire key, and send no header the curator reads, as text; every `Wire.X` the servers name exists. `tests/serve/test_curation_view_contract.py`: the reroll and interpolate buttons follow `CURATOR_PROVIDERS` and their declared defaults, and node runs `gen-trigger.js` to hold its select to `CURATOR_PROVIDERS` in order. `tests/effects/test_breathe_sidecar_roundtrip.py`: the curator's save payload kind is `CURATION_KIND`. `tests/frames/test_cutout.py` and `tests/frames/test_chroma_decontam.py`: every key table is the one table, every `--key`, `--decontam` and `--chroma-mode` flag reads its declaration, `cutout.KEYS` pinned as written. `tests/gen/test_codex_unavailable.py` (the codex-unavailable choices in order), `tests/gen/test_openai_provider.py` (adapter names equal `gen.PROVIDERS`), `tests/audio/test_sound.py` (the two ElevenLabs busy codes), `tests/workflow/test_capabilities.py` (the video model default), `tests/gen/test_prompt_assembly.py` (a repeat note's kind). The two absence guards that searched `serve_curation.py` for a key's spelling (`tests/serve/test_pixel_grid_always_available.py`, `tests/curate/test_logical_height_contract.py`) now search for its name; with the old spelling they would have passed while testing nothing. Red first: at 3.10.1 the new binding tests fail (for example the wire-key test finds 217 keys written as text in `serve_curation.py` and 55 in `serve_compose.py`; 8 `--decontam` parsers held their own copy; `video-set`'s `--key` was a copy). Mutation check: one character changed in a declared value fails a test in every family; before, 16 of 25 sampled curation key changes, the provider adapter name, either ElevenLabs busy code, the video model default and the loop report kind under the fast bundle left the suite green. `tests/frames/test_cutout.py` (no table in the package keys a key colour by its spelling (an AST scan of `sprite_gen`)), `tests/gen/test_codex_unavailable.py` (the guide reports the codex choice under the name it is saved by), `tests/gen/test_pixel_draw.py` (the effort order is the API's), `tests/compose/test_game_pack_v2.py` (a nine-slice's sides are `ui_kit`'s), `tests/gen/test_facing.py` (`video-loop --facing` takes the facings `gen.facing` declares), `tests/effects/test_breathe_reference_key.py` (the JS frame sides and border share equal `extract.FRAME_SIDES` and `BORDER_MIN_FRACTION`), `tests/spec/test_assets.py` (the kinds written to disk are pinned as written), `tests/gen/test_codex_login.py` (the codex binary pinned as written), `tests/video/test_source_restoration.py` (a restoration's five file suffixes pinned as written).
+
## v3.12.1 - A one-shot cut where no pair returns names its closest return, ratio and moved, and the report gains cycle.closest_return
**Upgrading from 3.12.0: Thresholds, the search window, which clips are cut, and every cut's pictures and report values are the same as 3.12.0.** Only the refusal text changes where no pair of frames returns, and `--report` gains `cycle.closest_return`. The refusal now names the closest return, its frames, its ratio of departure, and that pair's moved instead of reporting `moved 0.00`. Where a pair returns but what lies between is not an action, or where no pair departs at all, the refusal line is the 3.12.0 line as before.
diff --cc sprite_gen/video/loop.py
index 20baf43,32a3ae3..b0d06fd
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@@ -2455,10 -2350,9 +2458,11 @@@ def _cut_loop
raise SystemExit(f"video-loop: unknown --wrap-blend {wrap_blend!r}; expected one of {', '.join(wrap_blend_mod.MODES)}")
if unfixed not in UNFIXED_MODES:
raise SystemExit(f"video-loop: unknown --unfixed {unfixed!r}; expected one of {', '.join(UNFIXED_MODES)}")
+ from sprite_gen.gen.facing import FACINGS
if facing not in FACINGS:
raise SystemExit(f"video-loop: unknown --facing {facing!r}; expected one of {', '.join(FACINGS)}")
+ if view is not None and view not in handed_mod.VIEWS:
+ raise SystemExit(f"video-loop: unknown --view {view!r}; expected one of {', '.join(handed_mod.VIEWS)}")
if seam_pop_max is not None and not (math.isfinite(seam_pop_max) and seam_pop_max > 0):
raise SystemExit(f"video-loop: --seam-pop-max {seam_pop_max}: a bound over 0, or off")
if body_turn not in body_turn_mod.MODES: