@nodaro/shared 3.9.0 → 3.11.0

package/src/pro-3d-render.ts

@@ -35,6 +35,11 @@ import { z } from "zod"
 import { SCENE3D_LIMITS, type Scene3DReference } from "./scene3d.js"
 import { scene3DAnyPlanSchema, type Scene3DPlan } from "./scene3d-v2-plan.js"
 import { scene3DInputAssetsSchema, type Scene3DInputAsset } from "./scene3d-input-assets.js"
+import {
+  SCENE3D_REVIEW_UNAVAILABLE_REASONS,
+  type Scene3DRestoredAssertion,
+  type Scene3DReviewVerdict,
+} from "./scene3d-delivery-notes.js"
 
 /** Canvas/API/MCP node type. */
 export const PRO3D_RENDER_NODE_TYPE = "pro-3d-render"
@@ -265,6 +270,22 @@ export interface Pro3DRenderCapabilities {
 // Result
 // ---------------------------------------------------------------------------
 
+/**
+ * One advisory about a delivered composition.
+ *
+ * `code` is open-ended — an unknown one is shown, never refused — and it is what tells the two
+ * KINDS of advisory apart without knowing anything about the engine that produced them:
+ * `SCENE_AUTHORING_ASSUMPTION` (exported as `SCENE3D_AUTHORING_ASSUMPTION_CODE`) is an authoring
+ * caveat, "the brief did not say, so the run decided", carrying the planner's own assumption
+ * with any normalization the engine applied to it; `SCENE_REVIEW_REFUSED` (exported as
+ * `SCENE3D_REVIEW_REFUSED_CODE`) is one objection the paid visual reviewer raised against a
+ * scene this job DELIVERED anyway; `SCENE_REVIEW_UNAVAILABLE` (exported as
+ * `SCENE3D_REVIEW_UNAVAILABLE_CODE`) says that reviewer gave no usable verdict at all — it was
+ * never reached, or answered with nothing usable — so the scene was
+ * delivered — or, with the advisory policy off, retained — with no verdict on it, and it LEADS
+ * the array because it qualifies every line under it; a `SCENE_QUALITY_*` code is that same
+ * reviewer's finding on a job that FAILED, where the finding is the reason there is no video.
+ */
 export interface Pro3DRenderValidationWarning {
   code: string
   message: string
@@ -294,6 +315,27 @@ export interface Pro3DRenderResultMetadata {
   fps: number
   frames: number
   duration: number
+  /**
+   * The planner's own one-or-two-sentence description of what it authored — on a repaired run,
+   * of the REPAIR it made, which is the pass that was actually published. Optional and
+   * routinely absent: a model that returns no summary is not an error, and a render-only export
+   * authored nothing to describe.
+   */
+  summary?: string
+  /**
+   * The visual reviewer's verdict, present ONLY on a delivery it did not APPROVE — a scene whose
+   * every mandatory assertion passed, published either once the repair budget was spent and the
+   * reviewer still objected (`verdict: "refused"`), or with no verdict at all because the review
+   * never reached its provider or answered with nothing usable (`verdict: "unavailable"`, with
+   * `reason` saying which and `attempts` how many times it was asked). `validation.status` is
+   * `"passed"` on both, so this field's presence — not the
+   * status, and not the warning count — is what tells them from a clean result.
+   *
+   * Use {@link scene3DReviewVerdictOf} rather than reading it by hand, and
+   * {@link scene3DReviewNote} rather than writing the sentence for it: a banner that says "the
+   * reviewer refused this scene" about one NO reviewer saw invents an opinion.
+   */
+  review?: Scene3DReviewVerdict
 }
 
 /**
@@ -331,6 +373,44 @@ export interface Pro3DRenderJobOutput {
   }
   renderer: string
   metadata: Pro3DRenderResultMetadata
+  /**
+   * Repair passes actually RUN — never the number of authoring passes, so a composition
+   * accepted first time reports `0` rather than `1`. Optional and ABSENT (not `0`) on the
+   * render-only lane, which authored nothing and had no repair budget to spend: reporting a
+   * count there would be a claim about a run that never happened.
+   */
+  repairPasses?: number
+  /**
+   * Pre-build planner retries, counted apart from {@link repairPasses} because they spent a
+   * different thing: a recipe the compiler would not ADMIT is re-asked of the planner without
+   * a build, so no repair pass went with it. Optional, and absent on a run that needed none.
+   */
+  admissionRetries?: number
+  /**
+   * Repairs the engine authored ITSELF, by applying the compiler's own structured remedy instead
+   * of asking the planner.
+   *
+   * Counted APART from {@link repairPasses} and never folded into it, the same way
+   * {@link admissionRetries} is: these passes have their own quoted allowance — a `mechanical`
+   * line on the quote, released when unspent — rather than spending one of the caller's repairs.
+   * The identity the pricing keeps is
+   * `buildPasses === authoringPasses + repairPasses + mechanicalPasses`.
+   *
+   * ONE exception, discriminated by the QUOTE and not by this result: a run quoted before that
+   * allowance existed has no `mechanical` quote line, and there the pass charged a repair, making
+   * the count a subset of `repairPasses`. Read the quote you were given rather than inferring the
+   * accounting from the counts.
+   *
+   * Optional, and absent both on a run that needed none and on an engine that does not report it.
+   */
+  mechanicalPasses?: number
+  /**
+   * Mandatory assertions the engine put BACK after a planner answer re-shaped one the feedback
+   * had not named — restored to the last admitted recipe's exact form so the run continues
+   * instead of refusing over a value the engine already held. Each is also an
+   * `ASSERTION_RESTORED` warning. Optional; absent on a run that restored nothing.
+   */
+  restoredAssertions?: Scene3DRestoredAssertion[]
   /** Short, user-safe note about what this revision contains. Never diagnostics. */
   changeSummary?: string
 }
@@ -347,6 +427,55 @@ export interface Pro3DRenderJobOutput {
  * them to satisfy the schema; a runtime that has not produced them yet simply
  * does not parse as complete, which is the honest answer.
  */
+/**
+ * The visual reviewer's verdict on a delivery it did not approve, read tolerantly.
+ *
+ * Every member below is permissive on purpose: this schema is OPTIONAL inside a result that is
+ * otherwise complete, and a delivered scene with a real MP4 must never fail to parse — and so
+ * blank a video the platform already rendered and charged for — over a malformed advisory. An
+ * objection that arrives without frames parses with none; an unknown key is kept.
+ *
+ * That tolerance is exactly what a narrow `verdict` would have thrown away. Declared as
+ * `z.literal("refused")` the schema refused the whole result of an UNREVIEWED delivery — a real,
+ * paid, playable scene — over a discriminant it had never been taught, which is the one failure
+ * mode the rest of this block is written to avoid. `reason` and `attempts` are therefore
+ * permissive in the same direction, and with `.catch` rather than `.default`: a value that is
+ * absent AND one that is malformed both fall back, because the caller's alternative is losing a
+ * delivered MP4 over a count that only ever decides a sentence. `attempts` falls back to `1` —
+ * the review was asked at least once, or there would be no verdict to read — and `reason` to
+ * `"provider"`, the only cause an older engine emits. The causes it KEEPS are
+ * `SCENE3D_REVIEW_UNAVAILABLE_REASONS`, read from the one list `scene3DReviewVerdictOf` and
+ * `scene3DReviewNote` also read, never re-spelled here. `verdict` is the one member that stays strict: it is
+ * the discriminant, and guessing it is how a scene nobody reviewed gets reported as refused.
+ */
+const pro3DRenderReviewFindingsShape = {
+  objections: z.array(
+    z
+      .object({
+        category: z.string(),
+        what: z.string(),
+        correction: z.string().optional(),
+        frames: z.array(z.number().int().min(0)).default([]),
+      })
+      .passthrough(),
+  ),
+  observed: z.string().optional(),
+}
+
+export const pro3DRenderReviewVerdictSchema = z.union([
+  z
+    .object({ verdict: z.literal("refused"), ...pro3DRenderReviewFindingsShape })
+    .passthrough(),
+  z
+    .object({
+      verdict: z.literal("unavailable"),
+      reason: z.enum(SCENE3D_REVIEW_UNAVAILABLE_REASONS).catch("provider"),
+      attempts: z.number().int().min(1).catch(1),
+      ...pro3DRenderReviewFindingsShape,
+    })
+    .passthrough(),
+])
+
 export const pro3DRenderShotStillSchema = z
   .object({
     shotIndex: z.number().int().min(0),
@@ -387,8 +516,38 @@ export const pro3DRenderJobOutputSchema = z
         fps: z.number().positive(),
         frames: z.number().int().positive(),
         duration: z.number().positive(),
+        summary: z.string().optional(),
+        /**
+         * Degrades to absent rather than refusing the RESULT, which is the whole lesson of the
+         * verdict this round added. A narrow `verdict` here did not merely mis-read an unreviewed
+         * delivery — it failed `isPro3DRenderJobOutput` for the entire job, blanking a real,
+         * paid, playable MP4 over an advisory field. A verdict a future engine invents must cost
+         * at most itself; the `SCENE_REVIEW_*` entry in `validation.warnings[]` still arrives
+         * either way, because that array has no code enum.
+         */
+        review: pro3DRenderReviewVerdictSchema.optional().catch(undefined),
       })
       .passthrough(),
+    repairPasses: z.number().int().min(0).optional(),
+    admissionRetries: z.number().int().min(0).optional(),
+    mechanicalPasses: z.number().int().min(0).optional(),
+    // Tolerant like the review verdict above, and for the same reason: this rides a result that
+    // already has a real MP4, so a malformed entry must never blank a video the platform rendered
+    // and charged for. The identity fields are required because an entry without them names
+    // nothing; `value` is unknown because a restored assertion holds whatever it holds.
+    restoredAssertions: z
+      .array(
+        z
+          .object({
+            op: z.string(),
+            path: z.string(),
+            value: z.unknown().optional(),
+            assertionId: z.string(),
+            reason: z.string(),
+          })
+          .passthrough(),
+      )
+      .optional(),
     changeSummary: z.string().optional(),
   })
   .passthrough()