From 194803840f2de7f297097d6b88fe1a1b1b2b447e Mon Sep 17 00:00:00 2001 From: Navneet Chaudhary Date: Sun, 8 Nov 2026 02:19:59 +0530 Subject: [PATCH] fix: bind vector eye review to current rig --- .agents/skills/puppetcontrol/SKILL.md | 2 +- README.md | 2 +- docs/CHARACTER_REVIEW.md | 2 +- docs/IMPLEMENTATION_PLAN.md | 1 + docs/VECTOR_EYELIDS.md | 16 ++ src/character/eyelid-vector-workflow.ts | 9 +- src/character/review-approval.ts | 10 +- src/character/vector-review-evidence.ts | 232 ++++++++++++++++++++++++ src/cli/index.ts | 9 + tests/vector-review-evidence.test.ts | 142 +++++++++++++++ 10 files changed, 418 insertions(+), 7 deletions(-) create mode 100644 src/character/vector-review-evidence.ts create mode 100644 tests/vector-review-evidence.test.ts diff --git a/.agents/skills/puppetcontrol/SKILL.md b/.agents/skills/puppetcontrol/SKILL.md index d28ce10..70c9ad6 100644 --- a/.agents/skills/puppetcontrol/SKILL.md +++ b/.agents/skills/puppetcontrol/SKILL.md @@ -14,7 +14,7 @@ Read repo-root AGENTS.md, docs/TECHNICAL_CONCEPT.md, and docs/CHARACTER_IMPORT.m 5. Stage the proposal using `node dist/cli/index.js character landmarks stage --proposal `. Rev2D validates the isolated candidate and returns a work/overlay.png. **Actually inspect the overlay** before `character landmarks accept --candidate --reviewed`. Accepting replaces avatar.json with a backup and revokes all existing pose approvals. Never auto-pass --reviewed solely because a validator passed. 6. Build using node dist/cli/index.js character build (use --force if prior output exists). Inspect any geometryWarnings, particularly BODY_PIVOT_TOO_LOW and IRIS_LANDMARK_MISSING; these do not replace pixel inspection. Source/landmark/model/texture hashes are recorded in avatar-build.json and scene preflight rejects stale assets. Inspect every returned review/poses.png, turn.png, eyes.png and mouth.png. If incorrect, repair avatar.json and rebuild using --force; this resets the generated manifest and any edited scaffold. 7. To test optional drawn eye/mouth variants on a built actor, request edit masks, locally supply reviewed `variants/.png`, and explicitly import. With reviewed closed+half eye drawings, `character variants import eyes_closed eyes_half --experimental-short-fade --reviewed-art` shortens fade windows but makes poses change faster and may still ghost; it is a visual experiment, never a default or automatic quality fix. The import revokes prior approval and refreshes provenance only after re-rendering review sheets. -8. For a compatible imported avatar whose extracted lash warps look unnatural, optionally run `character eyes vectorize --experimental`. This creates a **new provenance-tracked vector eyelid model**, preserves source drawings, revokes existing approval, and renders real 30 FPS blink evidence. It uses the eye-mask vertices for a continuously deforming line, not alpha-switching; styling still needs human review. See `docs/VECTOR_EYELIDS.md`. +8. For a compatible imported avatar whose extracted lash warps look unnatural, optionally run `character eyes vectorize --experimental`. This creates a **new provenance-tracked vector eyelid model**, preserves source drawings, revokes existing approval, and renders real 30 FPS blink evidence. It uses the eye-mask vertices for a continuously deforming line, not alpha-switching. Derived rigs require fresh SHA-256-bound eyes/full/video evidence before `character approve`; if missing or stale, run `character eyes review ` and inspect the returned real frames. Neither evidence nor software can prove artistic acceptance or user consent. See `docs/VECTOR_EYELIDS.md`. 9. For a deliberately non-blended eye-art experiment, `character variants import eyes_closed eyes_half --experimental-stepped-eyes --reviewed-art` selects only one complete eye appearance outside tiny threshold windows. It can remove ghosted doubled lashes but creates visible pose pops; do not call it seamless or automatically approve. See `docs/EYE_TRANSITIONS.md` and compare actual frames. 10. Before approving a verified imported rig, run `node dist/cli/index.js character qa blink ` to generate an ordered 25-frame actual eyelid transition contact sheet (`blink-eyes.png` and `blink-full.png`); inspect EyeOpen=0.19 and 0.69 and the real eye artwork seams. The QA report flags motion stalls but never passes visual approval. Also run `character qa blink --timed` for a 36-frame synthetic 30 FPS video and review the actual moving result. Different fade policies may produce identical frames when their transition windows fall between sampled timestamps; see `docs/EYE_TIMING.md`. 11. A successful build intentionally leaves character.json with approved:false. A --force rebuild revokes approval *before* writing model/texture files, even if the rebuild later fails. Only after actual visual QA may an agent/user explicitly run `node dist/cli/index.js character approve --reviewed` (the flag is an acknowledgement, not evidence of review) to record neutral-pose approval. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction. diff --git a/README.md b/README.md index ec4cd6a..e4df2eb 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde - Local PNG pixel and ordered-frame QA (full frame or explicit region) reports RGB activity, unexpected transparency, candidate motion jumps and changed-control stalls; these metrics never auto-approve a rig. - Import review can render a 25-frame parameter-sweep contact sheet and a separate **36-frame, 30 FPS synthetic timed-blink MP4** with motion warnings; see [Character Review](docs/CHARACTER_REVIEW.md) and [Time-domain Blink QA](docs/EYE_TIMING.md). The opt-in [stepped-eye experiment](docs/EYE_TRANSITIONS.md) removes sampled opacity ghosting but does not provide a seamless morph. The two modes even produced byte-identical frames in one real-time test. - Imported flat-image actors start with narrower editable head/gaze motion limits; see [Look Motion](docs/LOOK_MOTION.md). -- Optional **experimental continuous vector eyelids** replace warped raster lash outlines with thin mask-following Rev2D mesh strips while keeping the iris clipped. This improves one real Hana sample without approval and requires artistic review; see [Vector Eyelids](docs/VECTOR_EYELIDS.md). +- Optional **experimental continuous vector eyelids** replace warped raster lash outlines with thin mask-following Rev2D mesh strips while keeping the iris clipped. This improves one real Hana sample without automatic approval. A **current-model SHA-256-bound eye/full/video proof** is required before explicit approval; use `character eyes review ` to refresh it. See [Vector Eyelids](docs/VECTOR_EYELIDS.md). - Optional SHA-256 Rhubarb cue bindings can detect when audio or mouth-cue bytes are replaced after alignment; a bound scene fails validation/render instead of silently using stale lip sync. - Agent-readable CLI output, tests and CI. diff --git a/docs/CHARACTER_REVIEW.md b/docs/CHARACTER_REVIEW.md index f4c777f..2f11fce 100644 --- a/docs/CHARACTER_REVIEW.md +++ b/docs/CHARACTER_REVIEW.md @@ -51,7 +51,7 @@ For a genuinely deforming eyelid outline instead of alpha-switching whole-eye pi node dist/cli/index.js character eyes vectorize avatars/portrait --experimental ~~~ -It uses the existing Rev2D eye-white mask to deform upper/lower lashes continuously, keeps the iris clipped, preserves the previous model, writes new fingerprints, and revokes approval. Unlike the sprite transitions it simplifies the painted lashes; visually inspect the resulting video. See [VECTOR_EYELIDS.md](VECTOR_EYELIDS.md). +It uses the existing Rev2D eye-white mask to deform upper/lower lashes continuously, keeps the iris clipped, preserves the previous model, writes new fingerprints, and revokes approval. Unlike the sprite transitions it simplifies the painted lashes; visually inspect the resulting video. **The generated model requires a model-hash-bound eye/full/MP4 review proof before approval.** If evidence is missing, run `character eyes review ` and examine all fresh frames. See [VECTOR_EYELIDS.md](VECTOR_EYELIDS.md). ## 3. Inspect exact blink transition frames diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index b8303ac..47891bf 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -86,6 +86,7 @@ - [x] Test an optional stepped-eye visibility profile that removes sampled double-sprite ghosting at EyeOpen 0.19/0.69 on refined MIT Hana artwork, with a 25-frame A/B render, explicit abrupt-change warnings and local 45-frame end-to-end smoke video. The source remains unapproved; **this trades ghosting for pose popping**, not a seamless morph. - [x] Add a 36-frame, 30 FPS time-domain blink QA export with deterministic synthetic timing, unique Rev2D state caching, and JSON motion warnings. The actual short-fade and stepped 30 FPS frames were SHA-256 identical for this one schedule, showing threshold tuning alone is insufficient. Four mesh/overlay variants failed visual QA and were not integrated. - [x] Build an opt-in, provenance-verified **continuous vector eyelid** rig: replace distorted raster lash warps with curved vertex strips driven by Rev2D's existing eye mask, preserving iris clipping and source art. Inspect real 9-state, 30 FPS blink and head/gaze sweeps; 90-frame end-to-end H.264 export verified. The Hana experiment remains unapproved and artists may prefer their own lash styling. +- [x] Make derived vector rig approvals require a SHA-256-bound current-model full/eye/30 FPS MP4 review package. Reject stale/missing/tampered files and renamed vector geometry; add `character eyes review` recovery without changing approval. Real licensed Hana test regenerated evidence successfully and remained unapproved. - [ ] Produce and visually approve high-quality closed/half eye and mouth artwork; demonstrate seamless real rendered transitions across full blink playback and multiple character styles. The local proof drawing stays unapproved. ## First video milestone — reproducible usable slice (2026-11-07) diff --git a/docs/VECTOR_EYELIDS.md b/docs/VECTOR_EYELIDS.md index c8db2dd..1fbd184 100644 --- a/docs/VECTOR_EYELIDS.md +++ b/docs/VECTOR_EYELIDS.md @@ -27,6 +27,22 @@ The command requires a single-pose, provenance-verified imported Rev2D character It deliberately **revokes previous approval before publishing** the new model. Its unique `*-vector-eyelids-.r2d.json` file is validated and hashed, the manifest is updated to reference it, and the original model and original user artwork are preserved. A successful operation generates a private `outputs/qa/blink-review//blink-timed-30fps.mp4` plus eye/full contact sheets and motion warnings. It returns the exact paths. +### Current-model review evidence is required before approval + +Old `review/poses.png`, `review/turn.png`, `review/eyes.png` and `review/mouth.png` may have been generated **before** vectorization. Their presence alone is insufficient evidence for the new eyelid rig. + +The vectorize operation now writes `review/vector-eyelids-proof.json` only **after** a real timed Rev2D blink and full/eyes contact sheets have rendered. It copies those three artifacts to a unique `review/vector-eyes-/` directory. The proof binds the **exact model SHA-256** from `avatar-build.json` to the SHA-256 hashes of all three review artifacts. `character approve --reviewed` refuses vector geometry without a matching proof, even if its model filename was manually changed. + +If FFmpeg fails, review files are lost or a generated package becomes stale, rerun: + +~~~powershell +node dist/cli/index.js character eyes review avatars/portrait +~~~ + +This regenerates only the review evidence for the current provenance-verified vector rig. It leaves the rig and its existing approval state unchanged; it never auto-approves. Inspect the newly returned full-frame and eye close-ups and the timed video **plus** the older head/turn/mouth sheets for unchanged regions before recording your own `--reviewed` acknowledgement. + +A proof verifies exact bytes and which model produced the review package. It **does not** verify that a person actually looked at the images, that the images are visually acceptable, or that the model is suitable for other character styles. + The current mutation is a local, non-transactional pair of file replacements for the model reference and fingerprint record. An interrupted update can temporarily fail verification, **never implicitly approve** an avatar. Restore the previous verified project copy or explicitly rebuild with `character build ... --force` if that happens. Make a backup of your imported project before experimenting. Do not combine the derived vector rig with subsequent drawn-eye variant imports without rebuilding the avatar first; Rev2D's upstream variant importer targets its original model filename. diff --git a/src/character/eyelid-vector-workflow.ts b/src/character/eyelid-vector-workflow.ts index 0a3ce7e..ce5a2d0 100644 --- a/src/character/eyelid-vector-workflow.ts +++ b/src/character/eyelid-vector-workflow.ts @@ -17,6 +17,7 @@ import { verifyAvatarBuildRecord, writeAvatarBuildRecord, } from "./provenance.js"; import { createBlinkReview } from "./blink-review.js"; +import { publishVectorReviewProof } from "./vector-review-evidence.js"; import { vectorizeImportedEyelids } from "./eyelid-vector.js"; const MAX_MODEL = 20_000_000; @@ -118,10 +119,12 @@ export async function createVectorEyelidRig( let review: Record; try { const rendered = await createBlinkReview(project, { root, timed: true }); + const proof = await publishVectorReviewProof(project, relModel, rendered, root); review = { - video: rendered.timedVideo, - eyes: rendered.eyeSheet, - full: rendered.fullSheet, + video: proof.video, + eyes: proof.eyes, + full: proof.full, + proofFile: proof.proofFile, report: rendered.reportPath, }; } catch (cause) { diff --git a/src/character/review-approval.ts b/src/character/review-approval.ts index 2c2fecd..d9aee9f 100644 --- a/src/character/review-approval.ts +++ b/src/character/review-approval.ts @@ -4,6 +4,7 @@ import { join, resolve } from "node:path"; import { AvatarWorkflowError, checkedPath } from "./avatar.js"; import { checkAvatarPoseCoverage, verifyAvatarBuildRecord } from "./provenance.js"; import { characterSchema, type Character } from "../scene/schemas.js"; +import { requiresVectorReviewProof, verifyVectorReviewProof } from "./vector-review-evidence.js"; const REVIEW_FILES = ["poses.png", "turn.png", "eyes.png", "mouth.png"] as const; const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); @@ -187,7 +188,11 @@ export async function approveImportedAvatar( const { raw, character } = parseManifest(originalContents); requireSupportedImportedAvatar(character); await verifyCurrentBuild(characterPath, character); - const reviewArtifacts = await validateReviewArtifacts(project); + const reviewArtifacts = [ + ...await validateReviewArtifacts(project), + ...(await requiresVectorReviewProof(project, character.render!.modelPath) + ? await verifyVectorReviewProof(project, character.render!.modelPath) : []), + ]; if (character.poseFamilies[0]!.approved) { return { @@ -224,6 +229,9 @@ export async function approveImportedAvatar( // Recheck the exact build and review artifacts immediately before the atomic manifest swap. await verifyCurrentBuild(characterPath, character); await validateReviewArtifacts(project); + if (await requiresVectorReviewProof(project, character.render!.modelPath)) { + await verifyVectorReviewProof(project, character.render!.modelPath); + } await rename(tempPath, characterPath); } finally { await unlink(tempPath).catch(() => undefined); diff --git a/src/character/vector-review-evidence.ts b/src/character/vector-review-evidence.ts new file mode 100644 index 0000000..520a98b --- /dev/null +++ b/src/character/vector-review-evidence.ts @@ -0,0 +1,232 @@ +/** + * Model-bound review evidence for experimentally vectorized eyelids. + * + * Every derived vector rig changes the rendered eyelid geometry. The four + * legacy review/ PNGs can predate that change; their mere existence must NOT + * make the new model approvable. A proof here binds freshly rendered eye/full + * contact sheets and a timed blink MP4 to the exact current model SHA-256. + * + * This proves byte continuity, NOT aesthetic approval or actual human consent. + */ +import { createHash, randomUUID } from "node:crypto"; +import { constants } from "node:fs"; +import { copyFile, lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { z } from "zod"; +import { AvatarWorkflowError, checkedPath } from "./avatar.js"; +import { + AVATAR_BUILD_RECORD, avatarBuildRecordSchema, verifyAvatarBuildRecord, +} from "./provenance.js"; +import { createBlinkReview } from "./blink-review.js"; +import { characterSchema } from "../scene/schemas.js"; + +const HASH = z.string().regex(/^[0-9a-f]{64}$/); +const evidenceFileSchema = z.strictObject({ + path: z.string().min(1).max(240), + sha256: HASH, +}); +const proofSchema = z.strictObject({ + version: z.literal(1), + kind: z.literal("vector-eyelids"), + model: evidenceFileSchema, + artifacts: z.strictObject({ + eyes: evidenceFileSchema, + full: evidenceFileSchema, + video: evidenceFileSchema, + }), +}); +type Proof = z.infer; +export const VECTOR_REVIEW_PROOF = "review/vector-eyelids-proof.json"; + +function error(message: string): never { + throw new AvatarWorkflowError("VECTOR_REVIEW_PROOF_MISSING_OR_STALE", message); +} + +function requireRelativeEvidencePath(path: string, prefix: string): void { + if (!path.startsWith(prefix) || path.includes("\\") || + path.includes(":") || path.startsWith("/") || + path.split("/").some(part => part === ".." || part === "." || part === "")) { + error("Review evidence path is outside the expected review package: " + path); + } +} + +async function checkedBytes(path: string, max: number, kind: "png" | "mp4"): Promise { + const info = await lstat(path); + if (!info.isFile() || info.isSymbolicLink() || info.size < 24 || info.size > max) { + error("Review evidence is missing, a symlink, truncated, or oversized"); + } + const bytes = await readFile(path); + if (kind === "png" && + !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) { + error("Review image is not a PNG"); + } + if (kind === "mp4" && bytes.toString("ascii", 4, 8) !== "ftyp") { + error("Timed eye review does not have an MP4 file header"); + } + return bytes; +} +function sha(bytes: Buffer): string { + return createHash("sha256").update(bytes).digest("hex"); +} + +async function currentModel(project: string, modelPath: string) { + const integrity = await verifyAvatarBuildRecord(join(project, "character.json"), modelPath); + if (!integrity.valid) error("Current avatar build is not verified: " + integrity.message); + const recordPath = await checkedPath(project, join(project, AVATAR_BUILD_RECORD)); + const raw = await readFile(recordPath, "utf8"); + if (Buffer.byteLength(raw, "utf8") > 512_000) error("Build record exceeds proof size limit"); + const record = avatarBuildRecordSchema.parse(JSON.parse(raw) as unknown); + if (record.model.path !== modelPath) error("Build record is not bound to the active model"); + return record.model; +} + +export function isVectorEyelidModelPath(modelPath: string): boolean { + return /-vector-eyelids-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.r2d\.json$/i + .test(modelPath); +} + +/** Inspect actual Rev2D geometry: renaming a vector model cannot skip the review gate. */ +export async function requiresVectorReviewProof(projectDir: string, modelPath: string): Promise { + const project = resolve(projectDir); + const modelFile = await checkedPath(project, join(project, modelPath)); + const info = await lstat(modelFile); + if (!info.isFile() || info.isSymbolicLink() || info.size > 20_000_000 || info.size < 2) { + error("Cannot inspect the current Rev2D model for vector eyelid review requirements"); + } + const raw = JSON.parse(await readFile(modelFile, "utf8")) as { parts?: Array<{ id?: unknown }> }; + const ids = new Set(Array.isArray(raw.parts) ? raw.parts.map(p => p?.id) : []); + const expected = [ + "eyeR_vector_upper", "eyeR_vector_lower", "eyeL_vector_upper", "eyeL_vector_lower", + ]; + const found = expected.filter(id => ids.has(id)).length; + if (found > 0 && found !== expected.length) { + error("Incomplete or manually edited vector eyelid geometry cannot be approved"); + } + return isVectorEyelidModelPath(modelPath) || found === expected.length; +} + +/** Publishing a fresh package does not grant or imply approval. */ +export async function publishVectorReviewProof( + projectDir: string, + modelRelative: string, + rendered: { eyeSheet: string; fullSheet: string; timedVideo?: string | undefined }, + root = process.cwd(), +): Promise<{ proofFile: string; eyes: string; full: string; video: string }> { + const project = await checkedPath(root, resolve(root, projectDir)); + if (!isVectorEyelidModelPath(modelRelative)) { + error("Only an explicitly derived vector eyelid model can publish this review proof"); + } + const model = await currentModel(project, modelRelative); + if (!rendered.timedVideo) error("Timed 30 FPS video is required for vector eyelid approval evidence"); + + const identity = randomUUID(); + const relativeDir = "review/vector-eyes-" + identity; + const dir = await checkedPath(project, join(project, relativeDir)); + await mkdir(dir); // unique, never overwrite an earlier review package + const names = { + eyes: ["blink-eyes.png", rendered.eyeSheet, "png"], + full: ["blink-full.png", rendered.fullSheet, "png"], + video: ["blink-timed-30fps.mp4", rendered.timedVideo, "mp4"], + } as const; + const artifacts = {} as Proof["artifacts"]; + for (const key of ["eyes", "full", "video"] as const) { + const [name, original, kind] = names[key]; + const source = await checkedPath(root, resolve(original)); + const input = await checkedBytes(source, kind === "mp4" ? 50_000_000 : 25_000_000, kind); + const destination = await checkedPath(project, join(dir, name)); + await copyFile(source, destination, constants.COPYFILE_EXCL); + const output = await checkedBytes(destination, kind === "mp4" ? 50_000_000 : 25_000_000, kind); + if (sha(input) !== sha(output)) error("Review bytes changed while copying " + name); + artifacts[key] = { path: relativeDir + "/" + name, sha256: sha(output) }; + } + + const proof: Proof = proofSchema.parse({ + version: 1, kind: "vector-eyelids", + model, artifacts, + }); + const proofFile = await checkedPath(project, join(project, VECTOR_REVIEW_PROOF)); + const temporary = await checkedPath(project, proofFile + ".next-" + randomUUID()); + try { + await writeFile(temporary, JSON.stringify(proof, null, 2) + "\n", { flag: "wx" }); + // Fail if the model or source assets changed during proof capture. + const latest = await currentModel(project, modelRelative); + if (latest.sha256 !== model.sha256) error("Rig changed while generating review proof"); + await rename(temporary, proofFile); + } finally { + await unlink(temporary).catch(() => undefined); + } + return { + proofFile, eyes: join(project, artifacts.eyes.path), + full: join(project, artifacts.full.path), + video: join(project, artifacts.video.path), + }; +} + +/** + * The approval gate invokes this for derived vector models. It deliberately + * rejects stale files instead of trusting old review/eyes.png from Rev2D. + */ +export async function verifyVectorReviewProof( + projectDir: string, + modelRelative: string, +): Promise { + const project = resolve(projectDir); + let proof: Proof; + try { + const file = await checkedPath(project, join(project, VECTOR_REVIEW_PROOF)); + const info = await lstat(file); + if (!info.isFile() || info.isSymbolicLink() || info.size < 2 || info.size > 16_384) { + error("Missing or oversized vector review proof"); + } + proof = proofSchema.parse(JSON.parse(await readFile(file, "utf8")) as unknown); + } catch (cause) { + error("Model-specific vector eyelid review proof is missing or malformed: " + String(cause)); + } + const current = await currentModel(project, modelRelative); + if (proof.model.path !== modelRelative || proof.model.sha256 !== current.sha256) { + error("Review evidence is for a different or older eyelid rig"); + } + const paths: string[] = []; + const packagePath = proof.artifacts.eyes.path; + const match = /^review\/vector-eyes-([0-9a-f-]{36})\/blink-eyes\.png$/.exec(packagePath); + if (!match) error("Invalid vector review package identity"); + const base = "review/vector-eyes-" + match[1] + "/"; + for (const [kind, filename] of [ + ["eyes", "blink-eyes.png"], ["full", "blink-full.png"], + ["video", "blink-timed-30fps.mp4"], + ] as const) { + const reference = proof.artifacts[kind]; + requireRelativeEvidencePath(reference.path, base); + if (reference.path !== base + filename) error("Review package filenames are inconsistent"); + const fullPath = await checkedPath(project, join(project, reference.path)); + const buffer = await checkedBytes(fullPath, kind === "video" ? 50_000_000 : 25_000_000, + kind === "video" ? "mp4" : "png"); + if (sha(buffer) !== reference.sha256) error("Review " + kind + " bytes no longer match the recorded proof"); + paths.push(fullPath); + } + return paths; +} + +/** Safely rerender/rebind the current vector rig after a failed or lost QA run. */ +export async function refreshVectorReviewProof( + projectDir: string, root = process.cwd(), +) { + const project = await checkedPath(root, resolve(root, projectDir)); + const manifest = characterSchema.parse( + JSON.parse(await readFile(join(project, "character.json"), "utf8")) as unknown); + const model = manifest.render?.modelPath; + if (!model || !isVectorEyelidModelPath(model)) { + error("The current imported character does not reference a vector-eyelid derived rig"); + } + await currentModel(project, model); + const rendered = await createBlinkReview(project, { root, timed: true }); + const proof = await publishVectorReviewProof(project, model, rendered, root); + return { + status: "review-evidence-refreshed", + approved: manifest.poseFamilies.some(pose => pose.approved), + approvalUnchanged: true, + model, + ...proof, + note: "Review the current-model video and contact sheets. Evidence is only a hash binding, not proof of human review.", + }; +} diff --git a/src/cli/index.ts b/src/cli/index.ts index aa0433e..c6c433f 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -23,6 +23,7 @@ import { comparePngFiles, parsePixelRegionArgument } from "../character/pixel-qa import { comparePngSequence } from "../character/frame-sequence-qa.js"; import { createBlinkReview } from "../character/blink-review.js"; import { createVectorEyelidRig } from "../character/eyelid-vector-workflow.js"; +import { refreshVectorReviewProof } from "../character/vector-review-evidence.js"; import { DEFAULT_LOOK_LIMITS, IMPORTED_INITIAL_LOOK_LIMITS } from "../scene/look-limits.js"; import { createCueBinding, verifyCueBinding, CueBindingError } from "../audio/cue-provenance.js"; @@ -40,6 +41,7 @@ function usage(): never { " puppetctl character build [--force]\n" + " puppetctl character approve --reviewed\n" + " puppetctl character eyes vectorize --experimental\n" + + " puppetctl character eyes review \n" + " puppetctl character variants request [variant-id ...]\n" + " puppetctl character variants status \n" + " puppetctl character variants import [--experimental-short-fade|--experimental-stepped-eyes] --reviewed-art\n" + @@ -167,6 +169,13 @@ async function run(): Promise { return; } + if (first === "character" && second === "eyes" && third === "review") { + const [project, ...flags] = process.argv.slice(5); + if (!project || project.startsWith("--") || flags.length !== 0) usage(); + print(await refreshVectorReviewProof(project)); + return; + } + if (first === "character" && second === "eyes" && third === "vectorize") { const [project, flag, ...extra] = process.argv.slice(5); if (!project || project.startsWith("--") || flag !== "--experimental" || extra.length) usage(); diff --git a/tests/vector-review-evidence.test.ts b/tests/vector-review-evidence.test.ts new file mode 100644 index 0000000..12e98b1 --- /dev/null +++ b/tests/vector-review-evidence.test.ts @@ -0,0 +1,142 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { dirname, join } from "node:path"; +import { tmpdir } from "node:os"; +import { createImportedCharacter } from "../src/character/avatar.js"; +import { createAvatarBuildRecord, writeAvatarBuildRecord } from "../src/character/provenance.js"; +import { approveImportedAvatar } from "../src/character/review-approval.js"; +import { + isVectorEyelidModelPath, publishVectorReviewProof, + verifyVectorReviewProof, +} from "../src/character/vector-review-evidence.js"; + +const temporary: string[] = []; +const DERIVED = "test-vector-eyelids-11111111-2222-4333-8444-555555555555.r2d.json"; +const PNG_HEADER = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); + +function png() { + const buffer = Buffer.alloc(32); + PNG_HEADER.copy(buffer, 0); + buffer.writeUInt32BE(13, 8); + buffer.write("IHDR", 12); + buffer.writeUInt32BE(512, 16); + buffer.writeUInt32BE(640, 20); + return buffer; +} +function mp4() { + const buffer = Buffer.alloc(48); + buffer.writeUInt32BE(32, 0); + buffer.write("ftyp", 4); + buffer.write("isom", 8); + return buffer; +} +async function fixture() { + const dir = await mkdtemp(join(tmpdir(), "puppetcontrol-vector-proof-")); + temporary.push(dir); + const root = dirname(dir); + const review = join(dir, "review"); + await mkdir(review); + await mkdir(join(dir, "textures")); + await writeFile(join(dir, "source.png"), "source-image"); + await writeFile(join(dir, "avatar.json"), '{"format":"rev2d-avatar","name":"test"}'); + await writeFile(join(dir, "textures", "face.png"), "base-face"); + await writeFile(join(dir, DERIVED), JSON.stringify({ + textures: [{ id: "face", path: "textures/face.png" }], + parts: ["eyeR_vector_upper", "eyeR_vector_lower", "eyeL_vector_upper", "eyeL_vector_lower"] + .map(id => ({ id })), + })); + const parameters = ["AngleX", "AngleY", "EyeBallX", "EyeBallY", "MouthOpen", "MouthForm"] + .map(id => ({ id, min: -1, max: 1, default: 0 })); + const manifest = createImportedCharacter("test", { parameters }); + manifest.render!.modelPath = DERIVED; + manifest.poseFamilies[0]!.modelPath = DERIVED; + await writeFile(join(dir, "character.json"), JSON.stringify(manifest, null, 2) + "\n"); + for (const name of ["poses.png", "turn.png", "eyes.png", "mouth.png"]) { + await writeFile(join(review, name), png()); + } + await writeFile(join(review, "synthetic-timed.mp4"), mp4()); + await writeAvatarBuildRecord(dir, await createAvatarBuildRecord(dir, DERIVED)); + return { + dir, root, review, model: join(dir, DERIVED), + inputs: { + eyeSheet: join(review, "eyes.png"), fullSheet: join(review, "poses.png"), + timedVideo: join(review, "synthetic-timed.mp4"), + }, + }; +} +afterEach(async () => { + await Promise.all(temporary.splice(0).map(dir => rm(dir, { recursive: true, force: true }))); +}); + +describe("vectorized eyelid current-model approval evidence", () => { + it("requires a new model-bound review package even when four legacy PNGs exist", async () => { + const { dir, root } = await fixture(); + expect(isVectorEyelidModelPath(DERIVED)).toBe(true); + expect(isVectorEyelidModelPath("test.r2d.json")).toBe(false); + await expect(approveImportedAvatar(dir, true, root)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + const manifest = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(manifest.poseFamilies[0].approved).toBe(false); + }); + + it("requires review for vector geometry even if the model filename is changed", async () => { + const { dir, root, model } = await fixture(); + const renamed = "renamed-model.r2d.json"; + await writeFile(join(dir, renamed), await readFile(model)); + const characterPath = join(dir, "character.json"); + const manifest = JSON.parse(await readFile(characterPath, "utf8")); + manifest.render.modelPath = renamed; + manifest.poseFamilies[0].modelPath = renamed; + await writeFile(characterPath, JSON.stringify(manifest, null, 2) + "\n"); + await writeAvatarBuildRecord(dir, await createAvatarBuildRecord(dir, renamed)); + await expect(approveImportedAvatar(dir, true, root)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + }); + + it("accepts exact current-model sheet/video hashes but does not grant approval on publishing alone", async () => { + const { dir, root, inputs } = await fixture(); + const result = await publishVectorReviewProof(dir, DERIVED, inputs, root); + expect(result.proofFile).toContain("review"); + expect((await verifyVectorReviewProof(dir, DERIVED))).toHaveLength(3); + const manifestBefore = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(manifestBefore.poseFamilies[0].approved).toBe(false); + const approval = await approveImportedAvatar(dir, true, root); + expect(approval.status).toBe("approved"); + expect(approval.reviewArtifacts).toHaveLength(7); + }); + + it("rejects a modified image after the review proof was produced", async () => { + const { dir, root, inputs } = await fixture(); + const result = await publishVectorReviewProof(dir, DERIVED, inputs, root); + await writeFile(result.eyes, Buffer.concat([await readFile(result.eyes), Buffer.from("tampered")])); + await expect(approveImportedAvatar(dir, true, root)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + }); + + it("rejects a proof after a new model build record replaces the previous model hash", async () => { + const { dir, root, model, inputs } = await fixture(); + await publishVectorReviewProof(dir, DERIVED, inputs, root); + const changed = JSON.parse(await readFile(model, "utf8")); + changed.experiment = "later re-rigging"; + await writeFile(model, JSON.stringify(changed)); + await writeAvatarBuildRecord(dir, await createAvatarBuildRecord(dir, DERIVED)); + await expect(approveImportedAvatar(dir, true, root)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + }); + + it("rejects altered sidecar paths, missing MP4 evidence, and mismatched model identity", async () => { + const { dir, root, inputs } = await fixture(); + const result = await publishVectorReviewProof(dir, DERIVED, inputs, root); + const wrongModel = "test-vector-eyelids-aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa.r2d.json"; + await expect(verifyVectorReviewProof(dir, wrongModel)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + const proof = JSON.parse(await readFile(result.proofFile, "utf8")); + proof.artifacts.eyes.path = "../../outside.png"; + await writeFile(result.proofFile, JSON.stringify(proof)); + await expect(verifyVectorReviewProof(dir, DERIVED)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + await expect(publishVectorReviewProof(dir, DERIVED, + { ...inputs, timedVideo: undefined }, root)) + .rejects.toMatchObject({ code: "VECTOR_REVIEW_PROOF_MISSING_OR_STALE" }); + }); +});