AI media harness for planning, generating, and editing locally
TypeScript
use crate::project::reference_tokens::action_reference_ids;
use crate::project::validation::issue::ValidationIssue;
use crate::project::*;
use std::collections::BTreeSet;
/** Agent-only semantic checks. The project validator intentionally permits
* blank references and free-form action text because the editor must be able
* to save unfinished user work. An agent claiming to have planned a scene has
* a stronger contract: references it creates are complete, citations compile,
* and spoken lines use the Speech fields the UI exposes. Failures flow through
* the normal correction loop, so the model gets three chances to repair them. */
pub(crate) fn validate_agent_scene_conventions(
before: &ProjectConfig,
next: &ProjectConfig,
) -> Result<(), String> {
validate_scene_policy(before, next).map_err(|issue| issue.message)
}
pub(super) fn validate_scene_policy(
before: &ProjectConfig,
next: &ProjectConfig,
) -> Result<(), ValidationIssue> {
let new_reference_ids = next
.references
.iter()
.filter(|reference| {
!before
.references
.iter()
.any(|existing| existing.id == reference.id)
})
.map(|reference| reference.id.as_str())
.collect::<BTreeSet<_>>();
for reference in next
.references
.iter()
.filter(|reference| new_reference_ids.contains(reference.id.as_str()))
{
if reference.kind != "text" {
return Err(ValidationIssue::new("reference.kind", Some(reference.id.clone()), "kind", format!(
"Agent-created reference '{}' must be a text reference. Do not invent a file-backed reference or file path.",
reference.id
)));
}
let definition = reference
.content
.as_deref()
.filter(|value| !value.trim().is_empty())
.unwrap_or(reference.description.as_str());
if definition.trim().is_empty() {
return Err(ValidationIssue::new("reference.description", Some(reference.id.clone()), "description", format!(
"Agent-created reference '{}' needs a complete visual description before it is used in shots.",
reference.id
)));
}
if reference.intended_use.is_empty() {
return Err(ValidationIssue::new("reference.usage", Some(reference.id.clone()), "intendedUse", format!(
"Agent-created reference '{}' needs an intendedUse such as character, animal, location, or product.",
reference.id
)));
}
}
let mut cited_new_references = BTreeSet::new();
let mut changed_scene = false;
for job in &next.generation_jobs {
let before_job = before
.generation_jobs
.iter()
.find(|existing| existing.id == job.id);
let changed = before_job.is_none_or(|existing| existing != job);
if !changed {
continue;
}
let Some(shots) = &job.shots else {
continue;
};
changed_scene = true;
let model = crate::generation::models::for_scene(job.provider_id.as_deref());
let duration = job.duration_seconds.unwrap_or_else(|| {
model
.unwrap_or_else(crate::generation::models::default_model)
.defaults
.duration_seconds
});
if shots.first().is_none_or(|shot| shot.start_seconds != 0.0) {
return Err(ValidationIssue::new(
"scene.first_shot",
Some(job.id.clone()),
"shots",
format!(
"Scene '{}' must have a first shot that starts at 0 seconds.",
job.id
),
));
}
for pair in shots.windows(2) {
if pair[1].start_seconds <= pair[0].start_seconds {
return Err(ValidationIssue::new(
"shot.order",
Some(pair[1].id.clone()),
"startSeconds",
format!(
"Shot '{}' in scene '{}' must start after the preceding shot.",
pair[1].id, job.id
),
));
}
}
if let Some(shot) = shots
.iter()
.skip(1)
.find(|shot| shot.start_seconds >= duration)
{
return Err(ValidationIssue::new(
"shot.range",
Some(shot.id.clone()),
"startSeconds",
format!(
"Shot '{}' in scene '{}' must start before the scene ends at {duration} seconds.",
shot.id, job.id
),
));
}
let earliest_shot_id = shots
.iter()
.min_by(|left, right| left.start_seconds.total_cmp(&right.start_seconds))
.map(|shot| shot.id.as_str())
.unwrap_or_default();
for shot in shots {
let before_shot = before_job
.and_then(|existing| existing.shots.as_ref())
.and_then(|existing| existing.iter().find(|candidate| candidate.id == shot.id));
if let Some(model) = model {
(model.validate_shot_settings)(before_shot, shot, earliest_shot_id).map_err(
|message| {
ValidationIssue::new(
"shot.settings",
Some(shot.id.clone()),
"settings",
message,
)
},
)?;
}
if action_contains_dialogue(&shot.action) {
return Err(ValidationIssue::new("shot.dialogue", Some(shot.id.clone()), "action", format!(
"Shot '{}' in scene '{}' contains dialogue in action. Keep action visual-only and move the exact spoken words into shot.speech with shot.speechLanguage.",
shot.id, job.id
)));
}
if shot
.speech
.as_deref()
.is_some_and(|speech| !speech.trim().is_empty())
&& shot.speech_language.is_none()
{
return Err(ValidationIssue::new("shot.language", Some(shot.id.clone()), "speechLanguage", format!(
"Shot '{}' in scene '{}' has speech but no speechLanguage. Keep the spoken line in shot.speech and set its language.",
shot.id, job.id
)));
}
for reference_id in action_reference_ids(&shot.action).map_err(|message| {
ValidationIssue::new("shot.citation", Some(shot.id.clone()), "action", message)
})? {
let reference = next
.references
.iter()
.find(|reference| reference.id == reference_id)
.ok_or_else(|| {
ValidationIssue::new("shot.unknown_reference", Some(shot.id.clone()), "action", format!(
"Shot '{}' cites unknown reference '{}'. Create the reference first or remove the citation.",
shot.id, reference_id
))
})?;
if !job.reference_ids.iter().any(|id| id == reference_id) {
return Err(ValidationIssue::new("shot.binding", Some(shot.id.clone()), "referenceIds", format!(
"Shot '{}' cites reference '{}', but scene '{}' does not include it in referenceIds.",
shot.id, reference_id, job.id
)));
}
if reference.kind == "text"
&& reference.images.is_empty()
&& reference.description.trim().is_empty()
&& reference
.content
.as_deref()
.is_none_or(|content| content.trim().is_empty())
{
return Err(ValidationIssue::new("reference.description", Some(reference.id.clone()), "description", format!(
"Shot '{}' cites text reference '{}', but that reference has no visual description.",
shot.id, reference_id
)));
}
if new_reference_ids.contains(reference_id) {
cited_new_references.insert(reference_id);
}
}
}
}
if changed_scene {
for reference in next.references.iter().filter(|reference| {
new_reference_ids.contains(reference.id.as_str())
&& reference.intended_use.iter().any(|usage| {
matches!(
usage.as_str(),
"character" | "animal" | "clothing" | "accessory" | "location" | "product"
)
})
}) {
if !cited_new_references.contains(reference.id.as_str()) {
return Err(ValidationIssue::new("reference.uncited", Some(reference.id.clone()), "action", format!(
"Agent-created {} reference '{}' is not used by any changed shot. Cite it in shot.action as '@[ref:{}]' and include it in the scene's referenceIds.",
reference.intended_use[0], reference.id, reference.id
)));
}
}
}
Ok(())
}
fn action_contains_dialogue(action: &str) -> bool {
let lower = action.to_lowercase();
if [
"<d>",
"</d>",
"dialogue:",
"dialog:",
"speech:",
"voice-over:",
"voiceover:",
"narration:",
]
.iter()
.any(|marker| lower.contains(marker))
{
return true;
}
let quoted = action.contains('"') || action.contains('“') || action.contains('”');
quoted
&& [
" says",
" asks",
" replies",
" shouts",
" whispers",
" narrates",
]
.iter()
.any(|cue| lower.contains(cue))
}