Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(out-dir): run-contract §2-b-3 — a run never writes over, moves or deletes its inputs: the one judgment (runio.refuse_overlap), what counts as an input and as an output, the table of each verb's inputs and what it replaces, logo's and correction-loop's exceptions, the working folders of a run's own and the old fixed names left alone; logo.md and loop-review.md say the same of their verbs
Soohong Kimd6d420eea989
diff --git a/docs/logo.md b/docs/logo.mdindex a328c2d..095ca49 100644--- a/docs/logo.md+++ b/docs/logo.md@@ -57,8 +57,14 @@ sprite-gen logo --provider codex --text "STARFALL" --lettering logo/lettering.pn| `logo.preview.png` | the logo on a dark and on a light backdrop, side by side: where a halo or a hard edge would show || `logo.report.json` | the report |-A run removes an earlier run's `lettering.png`, `logo*.png` from its folder first, so a-file there is always this run's (an input named with `--mood` or `--lettering` is kept).+A run still removes an earlier run's `lettering.png` and `logo*.png` from its folder+first, so a file there is always this run's. A `--lettering` given as the folder's own+`lettering.png` (cut again in place) is kept, and `--mood` may be the folder's own+`mood.png`. An input given as any other file the run removes or writes, or as the report,+is refused before anything is made+([run-contract.md §2-b-3](run-contract.md#2-b-3-a-run-never-writes-over-moves-or-deletes-its-inputs)).+The run's working folder is a new one of its own (`.logo-work.<pid>-<random>`); a+`.logo-work` folder already there is never touched.## The reportdiff --git a/docs/loop-review.md b/docs/loop-review.mdindex dd9a416..126a236 100644--- a/docs/loop-review.md+++ b/docs/loop-review.md@@ -196,9 +196,10 @@ then names the windows the search measured and refused (`status: "refused"`, `wi`context_repeat_over_step`, `drift_line_residual_analysis_px`, `seam_pop`, and `refused`, why),best score first, those whose top could not be read (`seam_pop: null`, `seam_pop_skipped`) afterthose whose top closes, and those whose top jumps at the wrap last, so a caller that must deliver-anyway (a forced `--cycle fixed`) cuts one the engine measured rather than the whole clip. The scaled-back frames are-written to `<out-dir>/.gait-fallback-frames` and removed once the strip is built or the run-fails.+anyway (a forced `--cycle fixed`) cuts one the engine measured rather than the whole clip. The+scaled-back frames are written to a new folder of the run's own in the out dir,+`.gait-fallback-frames.<pid>-<random>`, and removed however the run ends. A+`.gait-fallback-frames` folder already there is never touched.Measured on six stored 3 s front walks that had failed with `no periodic cycle found`: fourloop now. A long kimono, which hides the legs, walked a 38 to 39 frame cycle (one clip alsodiff --git a/docs/run-contract.md b/docs/run-contract.mdindex 7c0ccf6..d50b155 100644--- a/docs/run-contract.md+++ b/docs/run-contract.md@@ -23,6 +23,7 @@- [1. Pipeline stages](#1-pipeline-stages)- [2. Run-dir folder contract](#2-run-dir-folder-contract)- [2-b-2. Reading a run never writes to it](#2-b-2-reading-a-run-never-writes-to-it)+- [2-b-3. A run never writes over, moves or deletes its inputs](#2-b-3-a-run-never-writes-over-moves-or-deletes-its-inputs)- [2-c. External consumers install from `curated/`, never from `frames/`](#2-c-external-consumers-install-from-curated-never-from-frames)- [3. Curation-view display contract](#3-curation-view-display-contract)- [4. Import-run source rule (`--pngs-dir`)](#4-import-run-source-rule---pngs-dir)@@ -240,6 +241,62 @@ survives it through per-row `revision` salvage (§ `curation.load_curation_reporwith no stamp are dropped as usual, and `migrate-request` prints which rows those are*before* it writes.+## 2-b-3. A run never writes over, moves or deletes its inputs++Every verb that writes beside what it reads checks, before anything is made and with or without+`--force`, that no input is something the run replaces or deletes. There is one judgment for+this, `runio.refuse_overlap`, and every such verb calls it; section 4 covers `unpack-atlas` in+detail. What counts as an input is each path given to read, and each file found in a folder+given and then read (for example a frame in `--frames-dir`, or a link that the best candidate's+copy follows in `--run-dir`). Each input is followed the way the system opens it+(`runio.follow_path`): every link and folder its path looks up counts. What counts as an output+is each file the run writes, each folder it replaces or empties, and its report. A folder the+run only adds files to is not an output. That is why the `--out-dir` of `video-loop` and+`video-stop` is not itself compared: the keyed frames those verbs read usually lie inside it+(`video-frames` writes them to `<out>/keyed/`). An input that is the same file or folder as an+output, lies inside an output, or whose path goes through anything inside an output is refused,+naming both the input and the output. Comparison is by real path and file identity+(`runio.same_folder`, `runio.inside_folder`), so a link, or another spelling on a volume that+ignores case, is the same entry. An input path with a link loop is refused by name. A path that+only passes through an output and comes out of it again with `..` (for example+`out/cycle.source/../keyed`) is not refused.++| Verb | Inputs | What the run replaces or deletes |+| --- | --- | --- |+| `unpack-atlas` | see section 4 | the run dir, whose prior content `--force` replaces; an `--out-dir` inside an input is refused as well |+| `video-loop` | `--frames-dir` and every PNG found in it | `cycle/`, `cycle.source/`, `cycle.refused/`, `follow.source.png`, `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, `<name>.webp`, the report |+| `video-stop` | `--frames-dir` and every PNG found in it; `--loop` and the strip PNG beside it | `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, `<name>.webp`, the report |+| `video-frames` | `--clip`, `--reference` | `raw/` (its frames are replaced), `keyed/`, `keyed.refused/`, the report, `--source-manifest` |+| `correction-loop` | `--run-dir`, and every link the best candidate's copy follows inside it | `--out-dir` and everything in it (the attempts, the candidates, `best-candidate/`, the report) |+| `logo` | `--mood`, `--lettering` | `lettering.png`, `logo.png`, `logo.rejected.png`, `logo.preview.png`, `mood.png` (when the run writes one), the report |+| `video-extend`, `video-edit` | `--video` | `--out` |++Two verbs have an exception. In `logo`, `--mood` may be the folder's own `mood.png` and+`--lettering` may be the folder's own `lettering.png`. That is a picture an earlier run made,+given back to start again from it; the run reads it and writes its own pixels back. Any other+output file given as `--mood` or `--lettering` is refused. In `correction-loop`, an `--out-dir`+inside the run dir (the default, `<run-dir>/correction-loop`, is) is only added to, and the best+candidate's copy of the run dir leaves it out. Before this change the copy copied itself into+itself until the path was too long.++A folder a run writes into and then deletes is a new one of its own, made with `runio.new_stage`+(named `.<name>.<pid>-<random><suffix>`). These are: the frames `video-loop` scales back for a+size hold or the gait fallback (`.gait-fallback-frames.<pid>-<random>`, removed however the run+ends); the PNG frames every animated WebP is built from (`.<name>.webp.<pid>-<random>.frames`+beside the WebP, for `video-loop`, `video-stop`, `video-cycle-align`, `video-sway` and+`video-loop-repair`); the working folder `video-frames` keys into+(`.keyed.<pid>-<random>.work`); and the working folder of `logo` (`.logo-work.<pid>-<random>`).+A folder at one of the old fixed names (`.gait-fallback-frames`, `.webp-frames`, `.keyed.work`,+`.logo-work`), whether it holds an input or belongs to anyone else, is never written into or+removed.++The verbs that check a single output against their inputs call the same two functions,+`runio.same_folder` and `runio.inside_folder`, and have no comparison of their own:+`background-tile`, `inspect-motion`, `scene-inspect`, `scene-render`, `game-pack`, `ui-kit` and+`video-sway-inspect`. `video-sway-inspect` now refuses an `--out-dir` that is the loop directory+spelt in capitals on a volume that ignores case; before, it wrote its boards into the loop+directory.+## 2-c. External consumers install from `curated/`, never from `frames/``frames/` is the extractor's own output. Everything a human does in the curation view —