hyper-animator-codex 0.8.0 → 0.8.3

package/skills/hyper-animator-codex/scripts/validate_shot_plan.mjs

@@ -1,10 +1,34 @@
 #!/usr/bin/env node
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import validateSchema, { schemaSha256 } from "./shot_plan_schema_validator.mjs";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const skillRoot = dirname(scriptDir);
+const WORKFLOW_STAGES = new Set(["visual_draft", "audio_integrated", "render_ready"]);
+const AUDIO_MODES = new Set(["generated", "user_local_file", "none", "deferred"]);
+const ENERGY_LEVELS = new Set(["quiet", "balanced", "high", "cinematic"]);
+const MOTION_PRESETS = new Set([
+  "none",
+  "slam-entrance",
+  "whip-transition",
+  "crash-zoom",
+  "push-stack-wipe",
+  "dataviz-landscape-open",
+  "panel-grid-reflow",
+  "brand-resolve",
+]);
+const SHOTCRAFT_MOTION_PRESETS = new Map([
+  ["slam-entrance-moves", "slam-entrance"],
+  ["shot-transitions", "whip-transition"],
+  ["crash-zoom-punch", "crash-zoom"],
+  ["bottom-push-stack-wipe", "push-stack-wipe"],
+  ["dataviz-landscape-open", "dataviz-landscape-open"],
+  ["panel-grid-moves", "panel-grid-reflow"],
+  ["ui-to-brand-morph", "brand-resolve"],
+]);
 
 function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -16,8 +40,8 @@ function validateAudioTrack(track, label, errors) {
     return;
   }
 
-  if (!["generated", "user_local_file", "none"].includes(track.mode)) {
-    errors.push(`audio.${label}.mode must be generated, user_local_file, or none`);
+  if (!AUDIO_MODES.has(track.mode)) {
+    errors.push(`audio.${label}.mode must be generated, user_local_file, none, or deferred`);
   }
   if (track.mode === "generated" && track.provider !== "minimax_cn") {
     errors.push(`audio.${label}.provider must be minimax_cn when mode is generated`);
@@ -25,8 +49,51 @@ function validateAudioTrack(track, label, errors) {
   if (track.mode === "user_local_file" && (typeof track.path !== "string" || !track.path.trim())) {
     errors.push(`audio.${label}.path is required when mode is user_local_file`);
   }
-  if (track.mode === "none" && track.provider !== undefined) {
-    errors.push(`audio.${label}.provider must be omitted when mode is none`);
+  if ((track.mode === "none" || track.mode === "deferred") && track.provider !== undefined) {
+    errors.push(`audio.${label}.provider must be omitted when mode is ${track.mode}`);
+  }
+  if ((track.mode === "none" || track.mode === "deferred") && track.path !== undefined) {
+    errors.push(`audio.${label}.path must be omitted when mode is ${track.mode}`);
+  }
+}
+
+function validateMotionContract(contract, label, shotcraftRefs, errors) {
+  if (!isObject(contract)) {
+    errors.push(`${label}.motion_contract is required`);
+    return;
+  }
+
+  if (!MOTION_PRESETS.has(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must be one of ${[...MOTION_PRESETS].join(", ")}`);
+  }
+  const expectedPresets = shotcraftRefs
+    .map((reference) => SHOTCRAFT_MOTION_PRESETS.get(reference))
+    .filter(Boolean);
+  if (new Set(expectedPresets).size > 1) {
+    errors.push(`${label}.shotcraft_refs require multiple motion presets; separate them into distinct shots`);
+  }
+  if (expectedPresets.length > 0 && !expectedPresets.includes(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must use ${expectedPresets.join(" or ")} for selected ShotCraft refs`);
+  }
+  if (!ENERGY_LEVELS.has(contract.energy)) {
+    errors.push(`${label}.motion_contract.energy must be quiet, balanced, high, or cinematic`);
+  }
+  for (const field of ["camera", "transition"]) {
+    if (typeof contract[field] !== "string" || !contract[field].trim()) {
+      errors.push(`${label}.motion_contract.${field} is required`);
+    }
+  }
+  if (!Array.isArray(contract.shotcraft_commitments) || contract.shotcraft_commitments.length === 0) {
+    errors.push(`${label}.motion_contract.shotcraft_commitments must contain at least one item`);
+  } else {
+    contract.shotcraft_commitments.forEach((commitment, index) => {
+      if (typeof commitment !== "string" || !commitment.trim()) {
+        errors.push(`${label}.motion_contract.shotcraft_commitments[${index}] must be a non-empty string`);
+      }
+    });
+  }
+  if (!Number.isFinite(contract.readable_rest_seconds) || contract.readable_rest_seconds < 0) {
+    errors.push(`${label}.motion_contract.readable_rest_seconds must be zero or greater`);
   }
 }
 
@@ -34,7 +101,10 @@ function validateShotPlan(plan, catalogs) {
   const errors = [];
 
   if (!isObject(plan)) return ["plan must be a JSON object"];
-  if (plan.schema_version !== "1.0.0") errors.push("schema_version must be 1.0.0");
+  if (plan.schema_version !== "1.1.0") errors.push("schema_version must be 1.1.0");
+  if (!WORKFLOW_STAGES.has(plan.workflow_stage)) {
+    errors.push("workflow_stage must be visual_draft, audio_integrated, or render_ready");
+  }
   if (!["assemble_existing_catalog_items", "generate_new_hyperframes_html"].includes(plan.generation_mode)) {
     errors.push("generation_mode is invalid");
   }
@@ -56,18 +126,26 @@ function validateShotPlan(plan, catalogs) {
   } else {
     validateAudioTrack(plan.audio.narration, "narration", errors);
     validateAudioTrack(plan.audio.bgm, "bgm", errors);
+    if (plan.workflow_stage === "visual_draft" && plan.audio.narration?.mode === "generated") {
+      errors.push("audio.narration must not be generated before visual confirmation");
+    }
+    if (plan.workflow_stage !== "visual_draft" && plan.audio.narration?.mode === "deferred") {
+      errors.push("audio.narration.mode cannot stay deferred after visual confirmation");
+    }
   }
 
   if (!isObject(plan.model_routing)) {
     errors.push("model_routing must be an object");
   } else {
-    if (plan.model_routing.page_animation_authoring !== "gpt-5.6-sol") {
-      errors.push("model_routing.page_animation_authoring must be gpt-5.6-sol");
+    const authoring = plan.model_routing.page_animation_authoring;
+    const planning = plan.model_routing.planning_and_validation;
+    if (!isObject(authoring) || authoring.tier !== "high_quality" || !authoring.actual_model) {
+      errors.push("model_routing.page_animation_authoring must declare high_quality tier and actual_model");
     }
-    if (!plan.model_routing.planning_and_validation) {
-      errors.push("model_routing.planning_and_validation is required");
-    } else if (plan.model_routing.planning_and_validation === "gpt-5.6-sol") {
-      errors.push("model_routing.planning_and_validation must not use gpt-5.6-sol");
+    if (!isObject(planning) || planning.tier !== "fast" || !planning.actual_model) {
+      errors.push("model_routing.planning_and_validation must declare fast tier and actual_model");
+    } else if (authoring?.actual_model === planning.actual_model) {
+      errors.push("model_routing.planning_and_validation must use a different, fast model");
     }
   }
 
@@ -102,6 +180,9 @@ function validateShotPlan(plan, catalogs) {
     if (!Array.isArray(shot.hyperframes_refs)) {
       errors.push(`${label}.hyperframes_refs must be an array`);
     } else {
+      if (shot.hyperframes_refs.length === 0) {
+        errors.push(`${label}.hyperframes_refs must contain at least one HyperFrames reference`);
+      }
       for (const reference of shot.hyperframes_refs) {
         if (!catalogs.hyperframes.has(reference)) {
           errors.push(`${label} has unknown HyperFrames reference: ${reference}`);
@@ -111,17 +192,16 @@ function validateShotPlan(plan, catalogs) {
     if (!Array.isArray(shot.shotcraft_refs)) {
       errors.push(`${label}.shotcraft_refs must be an array`);
     } else {
+      if (shot.shotcraft_refs.length === 0) {
+        errors.push(`${label}.shotcraft_refs must contain at least one ShotCraft reference`);
+      }
       for (const reference of shot.shotcraft_refs) {
         if (!catalogs.shotcraft.has(reference)) {
           errors.push(`${label} has unknown ShotCraft reference: ${reference}`);
         }
       }
     }
-    if (Array.isArray(shot.hyperframes_refs)
-      && Array.isArray(shot.shotcraft_refs)
-      && shot.hyperframes_refs.length + shot.shotcraft_refs.length === 0) {
-      errors.push(`${label} must reference at least one catalog`);
-    }
+    validateMotionContract(shot.motion_contract, label, Array.isArray(shot.shotcraft_refs) ? shot.shotcraft_refs : [], errors);
 
     if (index === 0 && shot.start_seconds !== 0) {
       errors.push("shots must start at 0 seconds");
@@ -158,6 +238,14 @@ async function main() {
       return;
     }
     const plan = JSON.parse(await readFile(path, "utf8"));
+    const schemaText = await readFile(
+      join(skillRoot, "contracts", "shot-plan.schema.json"),
+      "utf8",
+    );
+    const actualSchemaSha256 = createHash("sha256").update(schemaText).digest("hex");
+    if (actualSchemaSha256 !== schemaSha256) {
+      throw new Error("shot-plan schema validator is stale; run npm run build:contracts");
+    }
     const hyperframesCatalog = JSON.parse(await readFile(
       join(skillRoot, "references", "hyperframes-catalog-map.json"),
       "utf8",
@@ -173,7 +261,12 @@ async function main() {
         ...card.styles.map((style) => style.key),
       ])),
     };
-    const errors = validateShotPlan(plan, catalogs);
+    const schemaErrors = validateSchema(plan)
+      ? []
+      : validateSchema.errors.map((error) => (
+        `${error.instancePath || "/"} ${error.message}${error.params?.additionalProperty ? `: ${error.params.additionalProperty}` : ""}`
+      ));
+    const errors = [...schemaErrors, ...validateShotPlan(plan, catalogs)];
     if (errors.length > 0) {
       output({ ok: false, path, errors }, 1);
       return;