The design language that makes your AI harness better at design.
JavaScript
Fix stale non-PNG raster reads
Paul Bakaus5229754a7319
diff --git a/crates/comp-verbs/src/approved_comp.rs b/crates/comp-verbs/src/approved_comp.rsindex a68d5a10c..d2386cdcd 100644--- a/crates/comp-verbs/src/approved_comp.rs+++ b/crates/comp-verbs/src/approved_comp.rs@@ -58,8 +58,7 @@ pub fn same_file(io: &Io, a: &str, b: &str) -> bool {}/// The comp as comp-spec, the record and every check see it: decoded from the-/// file's own bytes, never from the sibling PNG cache `load_raster` keeps for a-/// WebP or JPEG source (an edit to the source never refreshes it).+/// file's own bytes, never from a converted copy of a WebP or JPEG source.pub fn decode_comp(bytes: &[u8]) -> Option<Image> {png_io::decode_source(bytes).ok()}diff --git a/crates/comp-verbs/src/comp_spec.rs b/crates/comp-verbs/src/comp_spec.rsindex 0960a73d3..e6e392d71 100644--- a/crates/comp-verbs/src/comp_spec.rs+++ b/crates/comp-verbs/src/comp_spec.rs@@ -1226,9 +1226,8 @@ pub fn run(argv: &[String], io: &mut Io) -> i32 {io.err("usage: comp-spec.mjs --comp <png> (--grid | --regions <json> | --auto) [--spec out.json]\n comp-spec.mjs --print | --crop <id> [--out file] [--scale n] | --plate-prompt <id>\n");return 1;};- // Decode the comp's own bytes first: load_raster may read a stale sibling- // PNG cache for a WebP or JPEG source, and the spec must measure (and- // identify) the pixels the approved-comp record identifies.+ // Decode the comp's own bytes first so the spec measures (and identifies)+ // the same pixels as the approved-comp record.let own = std::fs::read(resolve(io, comp_path)).ok().and_then(|b| crate::approved_comp::decode_comp(&b));let comp = match own.map(Ok).unwrap_or_else(|| png_io::load_raster(&resolve(io, comp_path)).map(|(d, _)| d.image)) {Ok(img) => img,diff --git a/crates/comp/src/png_io.rs b/crates/comp/src/png_io.rsindex 0978401da..b6f67219e 100644--- a/crates/comp/src/png_io.rs+++ b/crates/comp/src/png_io.rs@@ -122,42 +122,20 @@ pub fn encode_png(img: &Image, text: &[(String, String)]) -> Result<Vec<u8>, Str}/// JS: loadRaster(file). PNG natively; WebP/JPEG/GIF through the `image` crate-/// (replacing the JS dwebp/sips/magick/convert shell-outs). Like the JS, a-/// converted source is cached as a sibling `<name>.png`; the returned path is-/// the PNG actually decoded. AVIF is deferred to step 2.+/// (replacing the JS dwebp/sips/magick/convert shell-outs). Non-PNG sources are+/// decoded from their own bytes on every call so an edited source can never be+/// shadowed by an older conversion. AVIF is deferred to step 2.pub fn load_raster(file: &std::path::Path) -> Result<(Decoded, std::path::PathBuf), String> {let buf = std::fs::read(file).map_err(|e| format!("png: {file:?}: {e}"))?;if is_png(&buf) {return Ok((decode_png(&buf)?, file.to_path_buf()));}- let cache = {- let mut s = file.as_os_str().to_os_string();- s.push(".png");- std::path::PathBuf::from(s)- };- if cache.exists() {- if let Ok(b) = std::fs::read(&cache) {- if is_png(&b) {- if let Ok(d) = decode_png(&b) {- return Ok((d, cache));- }- }- }- }- // Decode the source with the `image` crate and materialize the PNG cache.- let dyn_img = image::load_from_memory(&buf)+ let image = decode_source(&buf).map_err(|e| format!("png: {file:?} is not a PNG and could not be decoded: {e}"))?;- let rgba = dyn_img.to_rgba8();- let (w, h) = (rgba.width() as usize, rgba.height() as usize);- let img = Image { width: w, height: h, data: rgba.into_raw() };- let bytes = encode_png(&img, &[])?;- let _ = std::fs::write(&cache, &bytes);- Ok((Decoded { image: img, text: HashMap::new() }, cache))+ Ok((Decoded { image, text: HashMap::new() }, file.to_path_buf()))}-/// Decode an image from its own bytes, any format `load_raster` reads, without-/// consulting or writing the sibling PNG cache (which an edit to a WebP or-/// JPEG source never refreshes).+/// Decode an image from its own bytes, using any format `load_raster` reads.pub fn decode_source(bytes: &[u8]) -> Result<Image, String> {if is_png(bytes) {return Ok(decode_png(bytes)?.image);@@ -167,8 +145,8 @@ pub fn decode_source(bytes: &[u8]) -> Result<Image, String> {Ok(Image { width, height, data: rgba.into_raw() })}-/// Decode a static review image from its pinned bytes, without consulting or-/// writing sibling conversion caches. Keep the original file as review evidence.+/// Decode a static review image from its pinned bytes. Keep the original file+/// as review evidence.pub fn decode_review_image(bytes: &[u8]) -> Result<(Image, &'static str), String> {if is_png(bytes) {if bytes.len() < 24 { return Err("truncated PNG".into()); }@@ -197,6 +175,15 @@ pub fn decode_review_image(bytes: &[u8]) -> Result<(Image, &'static str), String#[cfg(test)]mod review_image_tests {use super::*;++ fn lossless_webp(pixel: [u8; 4]) -> Vec<u8> {+ let mut bytes = Vec::new();+ image::codecs::webp::WebPEncoder::new_lossless(&mut bytes)+ .encode(&pixel, 1, 1, image::ExtendedColorType::Rgba8)+ .unwrap();+ bytes+ }+#[test]fn review_webp_and_jpeg_decode_original_bytes_and_keep_alpha() {let pixels = [25, 90, 65, 120, 200, 40, 35, 255];@@ -210,4 +197,35 @@ mod review_image_tests {assert_eq!(format, "JPEG"); assert_eq!(decoded.data[3], 255);assert!(decode_review_image(b"not an image").is_err());}++ #[test]+ fn load_raster_reads_an_edited_non_png_source() {+ let unique = format!(+ "impeccable-load-raster-{}-{}",+ std::process::id(),+ std::time::SystemTime::now()+ .duration_since(std::time::UNIX_EPOCH)+ .unwrap()+ .as_nanos()+ );+ let dir = std::env::temp_dir().join(unique);+ std::fs::create_dir_all(&dir).unwrap();+ let source = dir.join("comp.webp");++ std::fs::write(&source, lossless_webp([20, 40, 60, 255])).unwrap();+ let first = load_raster(&source).unwrap().0.image;+ let mut cache_name = source.as_os_str().to_os_string();+ cache_name.push(".png");+ std::fs::write(+ std::path::PathBuf::from(cache_name),+ encode_png(&first, &[]).unwrap(),+ )+ .unwrap();+ std::fs::write(&source, lossless_webp([200, 180, 160, 255])).unwrap();+ let second = load_raster(&source).unwrap().0.image;++ assert_eq!(first.data, [20, 40, 60, 255]);+ assert_eq!(second.data, [200, 180, 160, 255]);+ std::fs::remove_dir_all(dir).unwrap();+ }}diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 85f0d64d6..2d840d348 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -475,7 +475,7 @@ Ported from the former `skill/scripts/{comp-spec,comp-diff,font-match,build-phas`build-phase check-plate <region-id> --candidate <png> [--json]` runs the normal plate gate on a separate candidate, retaining the full spec for reference exclusions. Exit 0 means pass, 2 means gate failure, 1 means invalid input. It does not write files (apart from the approved-comp copy a build that predates it gets on its first check), select an asset, record an approval, or advance build state. JSON includes `ok`, `region`, `candidate`, `reasons`, `plates`, and `stateChanged: false`.- **The approved comp is a fixed reference (engine addition).** When a comp is approved (`build-phase start --comp <png>`, the comps gate closing on the approved sidecar, or, for a build that has neither, the first `comp-spec --regions` on the comp `state.json` names), the engine copies its bytes to `.impeccable/build/approved-comp.<ext>` and writes `.impeccable/build/approved-comp.json` (`comp`, `pixelSha256`, `fileSha256`, `copy`, `at`). `pixelSha256` is the identity `comp-spec` writes as `compSha256` (SHA-256 of width, height and decoded RGBA, so a metadata-only rewrite such as `embed-prompt` is not an edit); it is decoded from the file's own bytes, never a sibling PNG cache, and `comp-spec` now measures and hashes that same decode of the comp's own bytes (`png_io::decode_source`: PNG, WebP, JPEG or GIF from the file's own bytes, never the sibling PNG cache `load_raster` keeps; the record and every check use the same decode, so a comp comp-spec can measure is never locked out and a stale cache never stands in for an edited source). Before anything measures against the comp, every entry point compares the comp's current pixels with that record (or, for a build that predates the record, with the spec's `compSha256`; the build's own spec then keeps the copy when they agree and no record exists, a spec at another path never does): the spec, plates, hero, sections, motion and responsive gates (so `advance`, `record hero`, `check-plate`, and the hero, responsive and plate revalidations), `finish --disposition ship`, `comp-spec --crop`, `comp-spec --comp <build comp> --regions` while a build state names that comp, `font-match --measure` / `--rank`, and `comp-diff` (against the spec's `compSha256` and the record when its `--spec` measures the `--comp` it was given, otherwise against the record kept for that `--comp`, if any). A missing or undecodable comp with a recorded identity is refused the same way, the hash clause reading `is missing or not a decodable image: expected pixel sha256 <approved>`. The build's own spec (`.impeccable/build/spec.json`, which every build-phase check reads, and `comp-spec --crop` / `font-match` / `comp-diff` when they are given that path) must measure the recorded comp: one that measures another file (a composite saved under a new name and re-specced) is refused with `.impeccable/build/spec.json measures <comp>, but the approved comp is <approved>.`, the fixed-reference sentence, and the instruction to re-run `comp-spec --regions` on the approved comp or start a new build on a newly approved file. A spec at another path is checked only against its own comp's record and `compSha256`, so independent crops stay possible, and the first-check keep never replaces a record kept for another comp. For a build that predates the record, `comp-spec --regions` compares the comp with the `compSha256` of the spec it is about to replace and refuses on a mismatch instead of adopting the edited pixels. When the copy or record cannot be written, approval refuses: `start --comp` exits 1 (`build-phase: start refused: cannot keep the approved comp: writing <path> failed (...)`), the comps gate stays open with that reason (also when the approved comp is not a decodable PNG, WebP or JPEG, and also under a quoted `--force`, which keeps the copy before closing; a quoted `--force` never waives this reason, and `advance` adds `--force refused: a quoted downgrade can relax the comp round, but never close it on an approved comp the engine cannot keep as the fixed reference; fix the reason above and advance again`), and `comp-spec --regions` exits 2. A mismatch is refused before any measurement (gate reason, or stderr with exit 2 for the verbs) with: `the approved comp <comp> has changed since approval: expected pixel sha256 <approved>, found <current>. The approved comp is the fixed reference every gate measures against; never edit it, composite into it, or regenerate it. Nothing was measured against the changed file. Restore it with <IMPECCABLE> build-phase restore-comp (the engine kept the approved copy at <copy>), then regenerate the plates or change the page code until they match the unchanged comp.` When no intact copy exists the last two sentences read `No intact engine copy exists for this build: restore the approved file from its original source, then regenerate the plates or change the page code until they match the unchanged comp.` A spec whose `compSha256` differs from the record (re-measured on an edited comp) is refused with `.impeccable/build/spec.json was measured on an image that is not the approved comp (spec compSha256 <spec>, approved <approved>): re-measuring an edited comp does not move the reference.` followed by the fixed-reference sentence and the instruction to re-run `comp-spec --regions` on the approved comp. `build-phase start --reset --comp <png>` naming the recorded comp while its pixels differ is refused (exit 2, `build-phase: start refused: ...`), adding that a newly approved comp is saved under a new file name; `start --direction` forgets the record, since its comp round approves a new comp. `build-phase restore-comp` (no state needed) verifies the copy against `pixelSha256`, moves the edited file to `.impeccable/build/edited-comp-<first 12 hex of its pixel hash>.<ext>` (outside `.impeccable/mocks/`, where the comps gate would count it), writes the copy back, and prints `RESTORED <comp> from <copy> (pixel sha256 <hash>). The edited file is kept at <path> as evidence, not as a comp. Re-run the step that refused; plates and page code built against the edited comp now have to match the approved one.` (exit 0; `comp <comp> already holds the approved pixels (sha256 <hash>); nothing restored` when nothing changed). It exits 1 when no record exists and 2 when the copy no longer matches the record. Gates measure against the editable path once it holds the approved pixels again, rather than silently against the copy, because the crop and font tools, `comp-diff` and the finish reviewer all read that path.+ **The approved comp is a fixed reference (engine addition).** When a comp is approved (`build-phase start --comp <png>`, the comps gate closing on the approved sidecar, or, for a build that has neither, the first `comp-spec --regions` on the comp `state.json` names), the engine copies its bytes to `.impeccable/build/approved-comp.<ext>` and writes `.impeccable/build/approved-comp.json` (`comp`, `pixelSha256`, `fileSha256`, `copy`, `at`). `pixelSha256` is the identity `comp-spec` writes as `compSha256` (SHA-256 of width, height and decoded RGBA, so a metadata-only rewrite such as `embed-prompt` is not an edit); it is decoded from the file's own bytes, and `comp-spec` measures and hashes that same decode (`png_io::decode_source`: PNG, WebP, JPEG or GIF from the file's own bytes; `load_raster` also decodes non-PNG sources directly on every read, so a stale conversion can never stand in for an edited source). Before anything measures against the comp, every entry point compares the comp's current pixels with that record (or, for a build that predates the record, with the spec's `compSha256`; the build's own spec then keeps the copy when they agree and no record exists, a spec at another path never does): the spec, plates, hero, sections, motion and responsive gates (so `advance`, `record hero`, `check-plate`, and the hero, responsive and plate revalidations), `finish --disposition ship`, `comp-spec --crop`, `comp-spec --comp <build comp> --regions` while a build state names that comp, `font-match --measure` / `--rank`, and `comp-diff` (against the spec's `compSha256` and the record when its `--spec` measures the `--comp` it was given, otherwise against the record kept for that `--comp`, if any). A missing or undecodable comp with a recorded identity is refused the same way, the hash clause reading `is missing or not a decodable image: expected pixel sha256 <approved>`. The build's own spec (`.impeccable/build/spec.json`, which every build-phase check reads, and `comp-spec --crop` / `font-match` / `comp-diff` when they are given that path) must measure the recorded comp: one that measures another file (a composite saved under a new name and re-specced) is refused with `.impeccable/build/spec.json measures <comp>, but the approved comp is <approved>.`, the fixed-reference sentence, and the instruction to re-run `comp-spec --regions` on the approved comp or start a new build on a newly approved file. A spec at another path is checked only against its own comp's record and `compSha256`, so independent crops stay possible, and the first-check keep never replaces a record kept for another comp. For a build that predates the record, `comp-spec --regions` compares the comp with the `compSha256` of the spec it is about to replace and refuses on a mismatch instead of adopting the edited pixels. When the copy or record cannot be written, approval refuses: `start --comp` exits 1 (`build-phase: start refused: cannot keep the approved comp: writing <path> failed (...)`), the comps gate stays open with that reason (also when the approved comp is not a decodable PNG, WebP or JPEG, and also under a quoted `--force`, which keeps the copy before closing; a quoted `--force` never waives this reason, and `advance` adds `--force refused: a quoted downgrade can relax the comp round, but never close it on an approved comp the engine cannot keep as the fixed reference; fix the reason above and advance again`), and `comp-spec --regions` exits 2. A mismatch is refused before any measurement (gate reason, or stderr with exit 2 for the verbs) with: `the approved comp <comp> has changed since approval: expected pixel sha256 <approved>, found <current>. The approved comp is the fixed reference every gate measures against; never edit it, composite into it, or regenerate it. Nothing was measured against the changed file. Restore it with <IMPECCABLE> build-phase restore-comp (the engine kept the approved copy at <copy>), then regenerate the plates or change the page code until they match the unchanged comp.` When no intact copy exists the last two sentences read `No intact engine copy exists for this build: restore the approved file from its original source, then regenerate the plates or change the page code until they match the unchanged comp.` A spec whose `compSha256` differs from the record (re-measured on an edited comp) is refused with `.impeccable/build/spec.json was measured on an image that is not the approved comp (spec compSha256 <spec>, approved <approved>): re-measuring an edited comp does not move the reference.` followed by the fixed-reference sentence and the instruction to re-run `comp-spec --regions` on the approved comp. `build-phase start --reset --comp <png>` naming the recorded comp while its pixels differ is refused (exit 2, `build-phase: start refused: ...`), adding that a newly approved comp is saved under a new file name; `start --direction` forgets the record, since its comp round approves a new comp. `build-phase restore-comp` (no state needed) verifies the copy against `pixelSha256`, moves the edited file to `.impeccable/build/edited-comp-<first 12 hex of its pixel hash>.<ext>` (outside `.impeccable/mocks/`, where the comps gate would count it), writes the copy back, and prints `RESTORED <comp> from <copy> (pixel sha256 <hash>). The edited file is kept at <path> as evidence, not as a comp. Re-run the step that refused; plates and page code built against the edited comp now have to match the approved one.` (exit 0; `comp <comp> already holds the approved pixels (sha256 <hash>); nothing restored` when nothing changed). It exits 1 when no record exists and 2 when the copy no longer matches the record. Gates measure against the editable path once it holds the approved pixels again, rather than silently against the copy, because the crop and font tools, `comp-diff` and the finish reviewer all read that path.`build-phase finish --disposition ship` binds the finish to the page it checked. Under native capture (`capturePolicy: "native-html-v1"` or `IMPECCABLE_NATIVE_CAPTURE=1`) ship first re-runs the responsive gate with a fresh native capture of the current files (an input that changes while that capture runs fails it, reopens responsive and records `fix`), then records `finish.artifactSha256` and `finish.captureInputs`, the `{path, sha256}` rows of the manifest that capture bound (`.impeccable/review/native/responsive/inputs.json`: the entry, the static files the capture froze, the spec and the comp). When that manifest is missing or unreadable, ship is refused (exit 2, `finish` recorded as `fix` with reason `final native capture manifest unavailable`) rather than recorded with entry-only binding. Under the screenshot policy ship refuses while the frontend files differ from the responsive screenshots and records `finish.artifactInputsSha256`; no `captureInputs` is recorded. `build-phase completion` reports `status: "changed-after-finish"` when the entry or any recorded capture input differs from what finish bound (a deleted file counts as changed, the entry included, so a deleted entry reads `changed-after-finish` rather than `unverified`), and lists the changed paths, entry first, in `changedSinceFinish`. Printed `NEXT` lines: in the review phase, `Spawn the finish reviewer ... --disposition <word>. Make every fix before ship: <recheck>, and any edit after it, a fix for a hook finding included, needs ship recorded again.`; after a ship that still covers the page, `Finish is recorded for the current entry. Any later edit to a file the final check bound (the page, what it loads, the spec, the comp), a fix for a hook finding included, voids it: run <IMPECCABLE> build-phase finish --disposition ship again before you stop; <recheck>.`; after one that no longer does, `A file the final check bound changed after finish (<up to six changed paths>), so the recorded ship no longer covers the build. Repeat final review if the change goes beyond a fix it asked for, then run <IMPECCABLE> build-phase finish --disposition ship again; <recheck>.` `<recheck>` is `ship re-captures the current files natively and must pass the responsive gate again` under native capture and `ship refuses while the frontend files differ from the responsive screenshots, so recapture desktop and mobile and advance responsive first` otherwise.diff --git a/docs/COMP-FIDELITY.md b/docs/COMP-FIDELITY.mdindex efe15523a..491dd3fea 100644--- a/docs/COMP-FIDELITY.md+++ b/docs/COMP-FIDELITY.md@@ -111,7 +111,7 @@ Why the machinery was skipped, in order of blame:1. **The packets carried no state.** The 07 packet was cut on 2026-08-12, before `build-phase.mjs start` existed; the 05 and 11 packets were cut on the branch, but the session generated its comps before running `start`, so `pending.json` was written and `state.json` never was. Every gate reads `state.json`; a resume with none has nothing to follow. Two fixes: `generate-image.mjs` refuses to write a comp under `.impeccable/mocks/` while `pending.json` is set and no state exists (the direction pick must be recorded first), and impeccable-evals `factory-validation` fails a `composition-approved` candidate whose workspace lacks a closed comps phase.2. **Prefix inertia.** A resumed model follows the conversation it is in. When the prefix ends on "translating comp C into HTML now", the mounted skill files are not re-read whatever they say. The procedure has to be on disk at the resume point (state.json + the `NEXT` line), which is what (1) restores.-3. **WebP comps.** gpt-image returned WebP for some cuts; `comp-spec` demanded PNG, so the session rewrote the `.webp` in place with PNG bytes, which broke replay ("a later step rewrites this path beyond the cut"). `loadRaster()` now converts through a sibling `<file>.png` cache and never touches the source.+3. **WebP comps.** gpt-image returned WebP for some cuts; `comp-spec` demanded PNG, so the session rewrote the `.webp` in place with PNG bytes, which broke replay ("a later step rewrites this path beyond the cut"). `loadRaster()` now decodes WebP directly and never touches the source.Read the earlier "exec cut, packet C, ask names the phased build" row and this sweep's four phased samples together: same model, same comp, and the phased build lands 10-15 points above the one-write build every time it actually runs. The open question is not whether the phases help but whether a resumed session enters them; that is a packet property, and it is now validated at cut time.@@ -298,4 +298,4 @@ Abdul ran both handoff checks on the rebased branch (full write-ups in PR #599'sThe decision that followed, made by Paul on return: **above `HERO_MIN`, the numeric readings advise instead of block.** Hard vetoes stay unconditional at any score (a missing region, a contradicted plate or text block, an inline-SVG illustration, a clipped plate, invented ink); ink colours, letter-spacing, line pitch, strip heights, and box positions print as advisories with the pass and belong to the polish pass before responsive. Under this condition every sweep-10 sample closes its hero, which settles 07 without another paid round.-Two ninth-sweep defects are fixed with it: the spec's escape hatches (`codeDrawn`, `container`, `bleed`) now persist into `spec.json` and announce themselves as WARN lines (an overridden refusal used to vanish from the record), and `font-match` probes `os.tmpdir()` before launching a browser and points `TMPDIR` at `.impeccable/tmp` when the sandbox's `/tmp` is unwritable (every ninth-sweep rank had silently fallen back to the catalog and set headlines at twice the comp's cap).\ No newline at end of file+Two ninth-sweep defects are fixed with it: the spec's escape hatches (`codeDrawn`, `container`, `bleed`) now persist into `spec.json` and announce themselves as WARN lines (an overridden refusal used to vanish from the record), and `font-match` probes `os.tmpdir()` before launching a browser and points `TMPDIR` at `.impeccable/tmp` when the sandbox's `/tmp` is unwritable (every ninth-sweep rank had silently fallen back to the catalog and set headlines at twice the comp's cap).