Skip to content

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.md
index 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 report
diff --git a/docs/loop-review.md b/docs/loop-review.md
index 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`) after
those 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`: four
loop now. A long kimono, which hides the legs, walked a 38 to 39 frame cycle (one clip also
diff --git a/docs/run-contract.md b/docs/run-contract.md
index 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_repor
with 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 —