Skip to content

The design language that makes your AI harness better at design.

JavaScript
12.6 KB
Raw Blame
//! A human-approved assembled capture is bound by what it looks like, not by the
//! bytes that drew it: build-phase compares it with the current capture, so later
//! shared-CSS edits keep it while the first viewport still matches. It is evidence
//! for the first viewport's scores, never a
//! replacement for native integrity, missing-region, or overall fidelity gates.
use crate::entry_capture::{CaptureClock, CdpEntryRenderer};
use impeccable_comp_verbs::asset_capture::capture_sha256;
use impeccable_comp_verbs::entry_capture::{
    ApprovedReference, CapturedEntry, EntryEvidence, EntryRenderer, EntryRequest,
};
use serde_json::{json, Value};
use std::{
    fs,
    path::{Path, PathBuf},
};

pub struct ReviewedEntryRenderer {
    pub session: Option<PathBuf>,
}
struct ReviewedEntry {
    source: Box<dyn CapturedEntry>,
    evidence: EntryEvidence,
    approved: Option<ApprovedReference>,
    session: Option<PathBuf>,
    request: EntryRequest,
}
fn read(path: &Path) -> Result<Value, String> {
    serde_json::from_slice(&fs::read(path).map_err(|e| e.to_string())?).map_err(|e| e.to_string())
}
fn file(root: &Path, path: &str) -> Result<Vec<u8>, String> {
    let mut full = root.to_path_buf();
    for c in Path::new(path).components() {
        let std::path::Component::Normal(c) = c else {
            return Err("invalid reviewed path".into());
        };
        full.push(c);
        if fs::symlink_metadata(&full)
            .map_err(|e| e.to_string())?
            .file_type()
            .is_symlink()
        {
            return Err("symlink in reviewed source".into());
        }
    }
    fs::read(full).map_err(|e| e.to_string())
}
/// Read only private native session state. The host selects the session; neither
/// a model-written receipt nor a saved build-phase report is an authority.
fn reference(session: &Path, r: &EntryRequest) -> Result<ApprovedReference, String> {
    let root = r.root.canonicalize().map_err(|e| e.to_string())?;
    if session
        .canonicalize()
        .map_err(|e| e.to_string())?
        .starts_with(&root)
    {
        return Err("review session must be outside the project".into());
    }
    let state = read(&session.join("current.json"))?;
    let packet = &state["packet"];
    let receipt = &state["receipt"];
    if packet["stage"] != "hero"
        || receipt["visualDecision"] != "approved"
        || receipt["captureVerified"] != true
        || receipt["capture"] != state["capture"]
        || state["capture"]["schema"] != "native-component-previews-v1"
        || receipt["submission"]["packetRevision"] != packet["revision"]
        || receipt["submission"]["requestId"] != packet["id"]
    {
        return Err("assembled review is not approved".into());
    }
    let components = packet["components"]
        .as_array()
        .filter(|c| c.len() == 1)
        .ok_or("expected one assembled page")?;
    let component = &components[0];
    if component["box"] != json!({"x":0,"y":0,"w":1,"h":1})
        || component["preview"]["sourceKind"] != "page"
    {
        return Err("review did not cover the assembled viewport".into());
    }
    let capture = &state["capture"]["components"][0]["views"]["preview"];
    if capture["kind"] != "assembled-page"
        || capture["entry"] != r.artifact
        || capture["viewport"]["dpr"] != 1
        || capture["viewport"]["width"] != packet["comp"]["width"]
        || capture["viewport"]["height"] != packet["comp"]["height"]
    {
        return Err("reviewed viewport or entry differs".into());
    }
    let sources = state["sources"]
        .as_object()
        .ok_or("missing review sources")?;
    if !sources.contains_key(&r.artifact) || !sources.contains_key(&r.reference) {
        return Err("review must bind entry and original comp".into());
    }
    // Only the reference is bound by bytes: the comp the user judged against must be
    // the comp the gates measure. Page sources may change; build-phase holds the
    // approval to the pixels of the current first viewport instead.
    if sources[&r.reference].as_str() != Some(&capture_sha256(&file(&root, &r.reference)?)) {
        return Err(format!("reviewed comp changed: {}", r.reference));
    }
    let comp_url = packet["comp"]["url"]
        .as_str()
        .ok_or("missing reviewed comp")?;
    if comp_url
        != format!(
            "/files/{}/{}",
            packet["revision"].as_str().ok_or("missing revision")?,
            r.reference
        )
    {
        return Err("reviewed reference differs".into());
    }
    let hash = capture["screenshotSha256"]
        .as_str()
        .filter(|h| h.len() == 64 && h.bytes().all(|c| c.is_ascii_hexdigit()))
        .ok_or("missing reviewed screenshot digest")?;
    let preview = component["preview"]["url"]
        .as_str()
        .ok_or("missing preview")?;
    let relative = preview
        .strip_prefix(&format!("/files/{}/", packet["revision"].as_str().unwrap()))
        .ok_or("preview revision differs")?;
    if state["files"][relative] != hash {
        return Err("reviewed preview digest differs".into());
    }
    let png = fs::read(session.join("blobs").join(hash)).map_err(|e| e.to_string())?;
    if capture_sha256(&png) != hash {
        return Err("reviewed screenshot changed".into());
    }
    let mut proof = json!({"schema":"human-assembled-reference-v1","requestId":packet["id"],"packetRevision":packet["revision"],"sha256":hash,"scope":"First viewport accepted in an assembled-page review; valid while the current capture matches this screenshot; material gates retained"});
    // The instant the approved screenshot's clock was pinned to (reviews captured
    // before pinning carry none); gate captures render at the same instant.
    if let Some(clock) = capture["clock"]["pinnedEpochMs"].as_f64().filter(|c| c.is_finite()) {
        proof["pinnedClockMs"] = json!(clock.floor() as i64);
    }
    Ok(ApprovedReference { png, proof })
}
impl EntryRenderer for ReviewedEntryRenderer {
    fn capture_entry(&self, r: &EntryRequest) -> Result<Box<dyn CapturedEntry>, String> {
        let candidate = self
            .session
            .as_ref()
            .map(|s| reference(s, r));
        // A code-only page must not load or inline the screenshot the user approved.
        let approved_png: Vec<&[u8]> = candidate.iter().filter_map(|c| c.as_ref().ok()).map(|a| a.png.as_slice()).collect();
        let clock = candidate.iter().filter_map(|c| c.as_ref().ok()).find_map(|a| a.proof["pinnedClockMs"].as_f64())
            .map(|epoch_ms| CaptureClock { epoch_ms, from_review: true }).unwrap_or_else(CaptureClock::now);
        let source = CdpEntryRenderer.capture_at(r, &approved_png, clock)?;
        let mut report = source.evidence().report.clone();
        if let Some(Err(reason)) = &candidate {
            report["humanTextReview"] = json!({"status":"not-current","reason":reason});
        }
        let approved = candidate.and_then(Result::ok);
        if let Some(a) = &approved {
            report["humanTextReview"] = a.proof.clone();
        }
        // Frames are produced once by the native adapter; copy bytes for the transport.
        let frames = source
            .evidence()
            .frames
            .iter()
            .map(|f| impeccable_comp_verbs::entry_capture::FrameEvidence {
                name: f.name.clone(),
                png: f.png.clone(),
                regions: f
                    .regions
                    .iter()
                    .map(|r| impeccable_comp_verbs::asset_capture::AssetCapture {
                        receipt: r.receipt.clone(),
                        images: vec![],
                    })
                    .collect(),
            })
            .collect();
        Ok(Box::new(ReviewedEntry {
            source,
            evidence: EntryEvidence { report, frames },
            approved,
            session: self.session.clone(),
            request: EntryRequest {
                root: r.root.clone(),
                artifact: r.artifact.clone(),
                spec: r.spec.clone(),
                reference: r.reference.clone(),
                stage: r.stage,
            },
        }))
    }
}
impl CapturedEntry for ReviewedEntry {
    fn evidence(&self) -> &EntryEvidence {
        &self.evidence
    }
    fn approved_reference(&self) -> Option<&ApprovedReference> {
        self.approved.as_ref()
    }
    fn verify_current(&self) -> Result<(), String> {
        self.source.verify_current()?;
        if let Some(a) = &self.approved {
            let current = reference(self.session.as_ref().unwrap(), &self.request)?;
            if current.png != a.png || current.proof != a.proof {
                return Err("human review changed during capture".into());
            }
        }
        Ok(())
    }
}
impl ReviewedEntryRenderer {
    pub fn local(root: &Path, home: Option<&Path>) -> Self {
        let session = (|| {
            let manifest = read(&root.join(".impeccable/review/hero.json")).ok()?;
            let project = root.canonicalize().ok()?;
            let id = manifest["id"].as_str()?;
            // Same project/id key as the shared component-review store.
            let key = capture_sha256(format!("{}\0{}", project.display(), id).as_bytes());
            Some(home?.join(".impeccable/component-reviews").join(key))
        })();
        Self { session }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn approval_is_bound_to_the_reviewed_screenshot_and_comp_not_page_bytes() {
        let dir = std::env::temp_dir().join(format!("review-reference-{}", std::process::id()));
        let root = dir.join("project");
        let session = dir.join("session");
        let _ = fs::remove_dir_all(&dir);
        fs::create_dir_all(&root).unwrap();
        fs::create_dir_all(session.join("blobs")).unwrap();
        fs::write(root.join("index.html"), b"page").unwrap();
        fs::write(root.join("comp.png"), b"comp").unwrap();
        let page = capture_sha256(b"page");
        let comp = capture_sha256(b"comp");
        let png = capture_sha256(b"png");
        fs::write(session.join("blobs").join(&png), b"png").unwrap();
        let capture = json!({"schema":"native-component-previews-v1","components":[{"views":{"preview":{"kind":"assembled-page","entry":"index.html","viewport":{"width":1536,"height":1024,"dpr":1},"screenshotSha256":png}}}]});
        let state = json!({"sources":{"index.html":page,"comp.png":comp},"files":{"preview.png":png},"capture":capture,"packet":{"stage":"hero","id":"hero","revision":"rev","comp":{"width":1536,"height":1024,"url":"/files/rev/comp.png"},"components":[{"box":{"x":0,"y":0,"w":1,"h":1},"preview":{"sourceKind":"page","url":"/files/rev/preview.png"}}]},"receipt":{"visualDecision":"approved","captureVerified":true,"capture":capture,"submission":{"requestId":"hero","packetRevision":"rev"}}});
        let save = |s: &Value| {
            fs::write(session.join("current.json"), serde_json::to_vec(s).unwrap()).unwrap()
        };
        save(&state);
        let request = EntryRequest {
            root: root.clone(),
            artifact: "index.html".into(),
            spec: "spec.json".into(),
            reference: "comp.png".into(),
            stage: impeccable_comp_verbs::entry_capture::EntryStage::Responsive,
        };
        assert_eq!(
            reference(&session, &request).unwrap().png,
            b"png"
        );
        for (pointer, value) in [
            ("/receipt/visualDecision", json!("changes-requested")),
            ("/receipt/submission/packetRevision", json!("old")),
            ("/packet/stage", json!("components")),
            ("/packet/components/0/box/w", json!(0.5)),
            ("/packet/comp/url", json!("/files/rev/other.png")),
            (
                "/capture/components/0/views/preview/viewport/width",
                json!(1440),
            ),
        ] {
            let mut broken = state.clone();
            *broken.pointer_mut(pointer).unwrap() = value;
            save(&broken);
            assert!(
                reference(&session, &request).is_err(),
                "{pointer}"
            );
        }
        save(&state);
        // Page edits keep the approval: build-phase compares pixels, not bytes.
        fs::write(root.join("index.html"), b"changed").unwrap();
        fs::write(root.join("late.css"), b"new").unwrap();
        assert_eq!(reference(&session, &request).unwrap().png, b"png");
        // A different comp does not.
        fs::write(root.join("comp.png"), b"other comp").unwrap();
        assert!(reference(&session, &request).is_err());
        fs::write(root.join("comp.png"), b"comp").unwrap();
        fs::write(session.join("blobs").join(&png), b"replaced").unwrap();
        assert!(reference(&session, &request).is_err());
        let _ = fs::remove_dir_all(dir);
    }
}