The design language that makes your AI harness better at design.
JavaScript
use super::manifest::{digest, freeze, relative, string, valid_box};
use serde_json::{json, Value};
use std::{
fs,
io::Write,
path::{Path, PathBuf},
};
pub 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())
}
pub fn write(path: &Path, value: &Value) -> Result<(), String> {
write_bytes(path, &serde_json::to_vec_pretty(value).unwrap())
}
/// Temp file plus rename, so a reader or a crash never sees a partial file.
pub fn write_bytes(path: &Path, bytes: &[u8]) -> Result<(), String> {
static NEXT: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
let parent = path.parent().ok_or("missing parent")?;
fs::create_dir_all(parent).map_err(|e| e.to_string())?;
let n = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
let name = path.file_name().ok_or("missing file name")?.to_string_lossy();
let temp = parent.join(format!(".{name}.tmp-{}-{n}", std::process::id()));
let result = (|| {
let mut f = fs::File::create(&temp)?;
f.write_all(bytes)?;
f.sync_all()?;
fs::rename(&temp, path)
})();
if result.is_err() {
let _ = fs::remove_file(&temp);
}
result.map_err(|e| e.to_string())
}
/// An OS lock on an open handle: the kernel releases it when the holder exits,
/// so there is no stale-lock takeover and dropping never deletes another's lock.
pub struct Lock(#[allow(dead_code)] fs::File);
pub fn lock(dir: &Path) -> Result<Lock, String> {
fs::create_dir_all(dir).map_err(|e| e.to_string())?;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
fs::set_permissions(dir, fs::Permissions::from_mode(0o700)).map_err(|e| e.to_string())?;
}
// One writer across prepare, HTTP submission and restart.
let f = fs::OpenOptions::new().read(true).write(true).create(true).truncate(false)
.open(dir.join("review.lock")).map_err(|e| e.to_string())?;
for _ in 0..20 {
match f.try_lock() {
Ok(()) => return Ok(Lock(f)),
Err(fs::TryLockError::WouldBlock) => std::thread::sleep(std::time::Duration::from_millis(25)),
Err(fs::TryLockError::Error(e)) => return Err(e.to_string()),
}
}
Err("review is busy; retry shortly".into())
}
pub fn session_dir(store: &Path, project: &Path, id: &str) -> PathBuf {
store.join(digest(format!("{}\0{id}", project.display()).as_bytes()))
}
#[cfg(test)]
pub fn prepare(store: &Path, project: &Path, input: &Value) -> Result<PathBuf, String> {
prepare_captured(store, project, input, None)
}
#[cfg(test)]
pub fn prepare_captured(
store: &Path,
project: &Path,
input: &Value,
capturer: Option<&mut dyn super::capture::ComponentCapturer>,
) -> Result<PathBuf, String> {
prepare_bound(store, project, input, capturer, None)
}
pub fn prepare_file(
store: &Path,
project: &Path,
path: &str,
capturer: Option<&mut dyn super::capture::ComponentCapturer>,
) -> Result<PathBuf, String> {
let canonical = project.canonicalize().map_err(|e| e.to_string())?;
let project = canonical.as_path();
if let Some(accepted) = super::lifecycle::final_session(store, project)? {
return Ok(accepted);
}
let path = relative(path)?;
let full = project
.join(&path)
.canonicalize()
.map_err(|e| e.to_string())?;
if !full.starts_with(project) {
return Err("manifest escapes project".into());
}
let bytes = fs::read(&full).map_err(|e| e.to_string())?;
if bytes.len() > 2 * 1024 * 1024 {
return Err("manifest exceeds 2 MiB".into());
}
let input = serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
prepare_bound(
store,
project,
&input,
capturer,
Some((path.to_string_lossy().into_owned(), bytes)),
)
}
fn prepare_bound(
store: &Path,
project: &Path,
input: &Value,
capturer: Option<&mut dyn super::capture::ComponentCapturer>,
binding: Option<(String, Vec<u8>)>,
) -> Result<PathBuf, String> {
let canonical = project.canonicalize().map_err(|e| e.to_string())?;
let project = canonical.as_path();
if let Some(accepted) = super::lifecycle::final_session(store, project)? {
return Ok(accepted);
}
let (mut packet, mut files) = freeze(project, input)?;
let manifest_digest = binding
.as_ref()
.map(|(path, bytes)| json!({"path":path,"sha256":digest(bytes)}));
if let Some((path, bytes)) = binding {
files.insert(path, bytes);
}
let sources: serde_json::Map<String, Value> = files
.iter()
.map(|(p, b)| (p.clone(), json!(digest(b))))
.collect();
fs::create_dir_all(store).map_err(|e| e.to_string())?;
if store
.canonicalize()
.map_err(|e| e.to_string())?
.starts_with(project)
{
return Err("review store must be outside the builder project".into());
}
let dir = session_dir(store, project, string(input, "id")?);
let _guard = lock(&dir)?;
let old = read(&dir.join("current.json")).ok();
let journey = super::lifecycle::journey(project)?;
let capture = if let Some(capturer) = capturer {
let captured = capturer.capture(&mut packet, &files)?;
for (path, bytes) in captured.files {
relative(&path)?;
if !path.starts_with("_review_captures/") || files.contains_key(&path) {
return Err("invalid native capture output path".into());
}
if bytes.len() > 32 * 1024 * 1024
|| files.values().map(Vec::len).sum::<usize>() + bytes.len() > 256 * 1024 * 1024
{
return Err("native captures exceed review byte budget".into());
}
files.insert(path, bytes);
}
if captured.evidence["schema"] != super::capture::schema_for(&packet)
|| captured.evidence["components"].as_array().map(Vec::len)
!= packet["components"].as_array().map(Vec::len)
{
return Err("native capture did not cover every component".into());
}
for c in packet["components"]
.as_array_mut()
.ok_or("missing captured components")?
{
let images: Vec<_> = ["preview", "context", "thumbnail"]
.iter()
.filter_map(|key| c[*key]["url"].as_str())
.map(|url| {
let path = url
.strip_prefix("/files/")
.ok_or("capture URL must be pinned")?;
let bytes = files.get(path).ok_or("capture image missing")?;
Ok(json!({"path":path,"sha256":digest(bytes)}))
})
.collect::<Result<_, &str>>()?;
c["revision"] = json!(digest(
&serde_json::to_vec(&json!({"component":c,"images":images})).unwrap()
));
}
packet.as_object_mut().unwrap().remove("revision");
packet["revision"] = json!(digest(&serde_json::to_vec(&packet).unwrap()));
// Detect source edits during rendering before committing a new review round.
sources_current(&json!({"project":project,"sources":sources}))?;
captured.evidence
} else {
Value::Null
};
let content_revision = if let Some(binding) = manifest_digest {
digest(
&serde_json::to_vec(&json!({"packet":packet["revision"],"manifest":binding})).unwrap(),
)
} else {
string(&packet, "revision")?.to_string()
};
sources_current(&json!({"project":project,"sources":sources}))?;
if old.as_ref().is_some_and(|o| {
o["journey"] == journey && o["contentRevision"]
.as_str()
.unwrap_or_else(|| o["packet"]["revision"].as_str().unwrap_or(""))
== content_revision
}) {
return Ok(dir);
}
let round = old
.as_ref()
.and_then(|o| o["packet"]["round"].as_u64())
.unwrap_or(0)
+ 1;
// Content may return to an earlier version. A review round must never do so:
// otherwise an old submission could authorize this new review accidentally.
let rev = digest(
&serde_json::to_vec(&json!({
"content":content_revision,"round":round,
"previous":old.as_ref().map(|o| &o["packet"]["revision"])
}))
.unwrap(),
);
packet["revision"] = json!(rev);
packet["round"] = json!(round);
// URLs include the frozen revision, so a new round cannot silently replace old preview pixels.
let prefix = format!("/files/{rev}/");
packet["comp"]["url"] = json!(packet["comp"]["url"]
.as_str()
.unwrap()
.replacen("/files/", &prefix, 1));
for c in packet["components"].as_array_mut().unwrap() {
for key in ["preview", "context", "thumbnail"] {
if let Some(url) = c[key]["url"].as_str() {
c[key]["url"] = json!(url.replacen("/files/", &prefix, 1));
}
}
}
let mut decisions = serde_json::Map::new();
let previous = old
.as_ref().filter(|v| v["journey"] == journey)
.map(|v| v["draft"].clone())
.unwrap_or(Value::Null);
for c in packet["components"].as_array().unwrap() {
let id = string(c, "id")?;
let d = &previous["decisions"][id];
if d["revision"] == c["revision"] && d["action"] == "approve" {
decisions.insert(id.into(), d.clone());
}
}
let missing = previous["missing"].as_array().cloned().unwrap_or_default();
let draft = json!({"packetRevision":rev,"decisions":decisions,"missing":missing,"inventoryConfirmed":false});
let mut hashes = serde_json::Map::new();
let blobs = dir.join("blobs");
fs::create_dir_all(&blobs).map_err(|e| e.to_string())?;
for (path, bytes) in files {
let hash = digest(&bytes);
let blob = blobs.join(&hash);
if fs::read(&blob).ok().is_none_or(|b| digest(&b) != hash) {
write_bytes(&blob, &bytes)?;
}
hashes.insert(path, json!(hash));
}
if let Some(old) = &old {
if let Some(old_rev) = old["packet"]["revision"].as_str() {
write(&dir.join(format!("revisions/{old_rev}.json")), old)?;
}
}
let mut state = json!({"schemaVersion":1,"journey":super::lifecycle::journey(project)?,"contentRevision":content_revision,"project":project,"packet":packet,"files":hashes,"sources":sources,"capture":capture,"draft":draft,"receipt":null});
if let Some(previous) = old.as_ref().filter(|v| v["journey"] == journey) {
super::visual_approval::carry(previous, &mut state, &blobs);
// An unsubmitted intermediate capture is not a revocation. Use only the
// latest submitted round, so an older approval cannot override later feedback.
if previous["receipt"].is_null() {
let mut submitted = fs::read_dir(dir.join("revisions")).into_iter().flatten()
.filter_map(Result::ok).filter_map(|entry| read(&entry.path()).ok())
.filter(|s| !s["receipt"].is_null() && s["journey"] == state["journey"])
.collect::<Vec<_>>();
submitted.sort_by_key(|s| s["packet"]["round"].as_u64().unwrap_or(0));
if let Some(previous) = submitted.last() {
super::visual_approval::carry(previous, &mut state, &blobs);
}
}
}
state["history"] = old
.as_ref().filter(|v| v["journey"] == journey)
.map(|previous| super::history::between(previous, &state))
.unwrap_or(Value::Null);
write(&dir.join(format!("revisions/{rev}.json")), &state)?;
write(&dir.join("current.json"), &state)?;
Ok(dir)
}
pub fn sources_current(state: &Value) -> Result<(), String> {
sources_current_in(state, Path::new(string(state, "project")?))
}
/// `sources_current` against an explicit project. A hosted session records the
/// host's snapshot of the project, which the builder's shell may not be able to
/// read and which never changes; the gate checks the builder's own files instead.
/// A file that exists but cannot be read is reported as unreadable, never as changed.
pub fn sources_current_in(state: &Value, project: &Path) -> Result<(), String> {
for (path, hash) in state
.get("sources")
.unwrap_or(&state["files"])
.as_object()
.ok_or("missing pinned files")?
{
let full = project
.join(relative(path)?)
.canonicalize()
.map_err(|e| if e.kind() == std::io::ErrorKind::NotFound { format!("review is stale: {path} disappeared") }
else { format!("reviewed source unreadable: {path}: {e}") })?;
if !full.starts_with(project)
|| digest(&fs::read(&full).map_err(|e| format!("reviewed source unreadable: {path}: {e}"))?) != hash.as_str().unwrap_or("")
{
return Err(format!(
"review is stale: {path} changed; prepare a new round"
));
}
}
Ok(())
}
pub fn submit(dir: &Path, body: &Value) -> Result<Value, String> {
let _guard = lock(dir)?;
let mut state = read(&dir.join("current.json"))?;
if let Some(final_dir) = super::lifecycle::final_session(
dir.parent().ok_or("missing review store")?,
Path::new(string(&state, "project")?),
)? {
if final_dir != dir {
return Err(
"The assembled first viewport is already accepted; component review is closed."
.into(),
);
}
}
if body.as_object().is_none_or(|m| {
m.keys().any(|k| {
![
"schemaVersion",
"requestId",
"packetRevision",
"decisions",
"missing",
"inventoryConfirmed",
"reclassify",
]
.contains(&k.as_str())
})
}) {
return Err("unexpected review fields".into());
}
let packet = &state["packet"];
if body["schemaVersion"] != 1
|| body["requestId"] != packet["id"]
|| body["packetRevision"] != packet["revision"]
{
return Err("review is stale or identifies another request".into());
}
if !state["receipt"].is_null() {
return if state["receipt"]["submission"] == *body {
Ok(state["receipt"].clone())
} else {
Err("this round already has different feedback".into())
};
}
sources_current(&state)?;
let decisions = body["decisions"]
.as_object()
.ok_or("decisions must be an object")?;
let components = packet["components"]
.as_array()
.ok_or("missing components")?;
let v3 = packet["schemaVersion"] == 3;
let mut approved = 0;
let mut revisions = 0;
let mut reclassified = 0;
let target_kind = |d: &Value| matches!(d["kind"].as_str(), Some("plate" | "image" | "texture"));
for (id, d) in decisions {
let c = components
.iter()
.find(|c| c["id"] == *id)
.ok_or("unknown component")?;
if d["revision"] != c["revision"] {
return Err("stale component revision".into());
}
if !d["feedback"].is_string()
|| d["feedback"].as_str().unwrap().len() > 8000
|| !d["split"].is_boolean()
{
return Err("invalid component feedback".into());
}
if d.get("kind").is_some() && d["action"] != "reclassify" {
return Err("only a reclassify decision carries kind".into());
}
match d["action"].as_str() {
Some("approve") if d["split"] == false => approved += 1,
// On an asset, split: true asks for the region to come back as layers (a frame plate
// with a transparent opening, the view, each moving part); feedback is optional.
Some("revise") if !v3 || c["role"] == "asset" => revisions += 1,
// A plan item can need a map change neither medium fixes (artwork spilling over a
// code region). Revise then carries the reviewer's words and must not be empty.
Some("revise") if d["split"] == false && !d["feedback"].as_str().unwrap().trim().is_empty() => revisions += 1,
Some("revise") => return Err(format!("{id} is a plan item; revise on a plan item needs feedback describing the region map change")),
Some("reclassify") if v3 && c["role"] == "plan" && d["split"] == false && target_kind(d) => reclassified += 1,
Some("reclassify") => return Err("reclassify applies to plan items and needs kind plate, image or texture".into()),
_ => return Err("invalid decision action".into()),
}
}
let reclassify = body.get("reclassify").map(|r| r.as_array().cloned().ok_or("reclassify must be an array")).transpose()?.unwrap_or_default();
if !reclassify.is_empty() && !v3 {
return Err("reclassify belongs to the plan and asset review".into());
}
let mut reclassify_ids = std::collections::BTreeSet::new();
for r in &reclassify {
let id = string(r, "id")?;
let listed = packet["codeRegions"].as_array().is_some_and(|code| code.iter().any(|c| c["id"] == id));
if !listed || !reclassify_ids.insert(id) || !target_kind(r)
|| r.as_object().is_some_and(|m| m.keys().any(|k| !["id", "kind", "feedback"].contains(&k.as_str())))
|| r.get("feedback").is_some_and(|f| f.as_str().is_none_or(|f| f.len() > 8000))
{
return Err("invalid reclassification: name a codeRegions id once, with kind plate, image or texture".into());
}
}
if reclassify.len() > 400 {
return Err("too many reclassifications".into());
}
let missing = body["missing"]
.as_array()
.ok_or("missing must be an array")?;
let mut missing_ids = std::collections::BTreeSet::new();
for m in missing {
if !valid_box(&m["box"])
|| string(m, "name")?.trim().is_empty()
|| !m["feedback"].is_string()
|| !missing_ids.insert(string(m, "id")?)
{
return Err("invalid missing component".into());
}
}
if missing.len() > 200 || !body["inventoryConfirmed"].is_boolean() {
return Err("invalid inventory confirmation".into());
}
let has_feedback = revisions > 0 || reclassified > 0 || !reclassify.is_empty() || !missing.is_empty();
if !has_feedback && (approved != components.len() || body["inventoryConfirmed"] != true) {
return Err("approve every component and confirm inventory completeness".into());
}
let receipt = json!({"schemaVersion":1,"reviewer":"local-browser","visualDecision":if has_feedback{"changes-requested"}else{"approved"},"captureVerified":super::capture::verified(&state),"capture":state["capture"],"submission":body});
state["draft"] = json!({"packetRevision":body["packetRevision"],"decisions":decisions,"missing":missing,"inventoryConfirmed":body["inventoryConfirmed"]});
if v3 { state["draft"]["reclassify"] = json!(reclassify); }
state["receipt"] = receipt.clone();
write(&dir.join("current.json"), &state)?;
// current.json is the authoritative atomic commit; a receipt export is not approval authority.
Ok(receipt)
}
/// Update only an unsubmitted draft, retaining packet/source identity and old receipts.
pub fn refresh_approvals(dir: &Path) -> Result<usize, String> {
let _guard = lock(dir)?;
let mut state = read(&dir.join("current.json"))?;
if !state["receipt"].is_null() {
return Ok(0);
}
sources_current(&state)?;
let Some(rev) = state["history"]["packet"]["revision"].as_str() else {
return Ok(0);
};
if rev.len() != 64 || !rev.bytes().all(|b| b.is_ascii_hexdigit()) {
return Err("invalid previous revision".into());
}
let previous = read(&dir.join(format!("revisions/{rev}.json")))?;
if previous["packet"]["revision"] != rev {
return Err("previous revision mismatch".into());
}
let count = super::visual_approval::carry(&previous, &mut state, &dir.join("blobs"));
let history = super::history::between(&previous, &state);
if count > 0 || state["history"] != history {
state["history"] = history;
write(&dir.join("current.json"), &state)?;
}
Ok(count)
}