@rig-c/review 4.9.1 → 4.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/docs/DESIGN.md +5 -5
  2. package/docs/PANELS.md +3 -1
  3. package/docs/REVIEW_PACKAGE.md +143 -30
  4. package/docs/STABILITY.md +110 -3
  5. package/package.json +2 -2
  6. package/src/chest-landmarks.ts +9 -4
  7. package/src/cloth-recipe.ts +27 -7
  8. package/src/compare-html.ts +1 -1
  9. package/src/feedback-export.ts +2 -2
  10. package/src/feedback-validation.ts +11 -6
  11. package/src/frame-clock.ts +20 -4
  12. package/src/job-act.ts +60 -71
  13. package/src/job-api.ts +302 -46
  14. package/src/job-checkpoint-evidence.ts +17 -0
  15. package/src/job-cli.ts +3 -2
  16. package/src/job-contract.ts +107 -7
  17. package/src/job-front.ts +48 -12
  18. package/src/job-host.ts +7 -1
  19. package/src/job-session.ts +136 -26
  20. package/src/job-source.ts +133 -21
  21. package/src/job-store.ts +7 -4
  22. package/src/manifest.ts +59 -7
  23. package/src/open-workspace-state.ts +6 -1
  24. package/src/open.ts +3 -3
  25. package/src/rebuild.ts +42 -10
  26. package/src/session.ts +9 -4
  27. package/src/stage-comment.ts +2 -1
  28. package/web/catalog-en.ts +31 -6
  29. package/web/catalog-ko.ts +79 -54
  30. package/web/chest-editor.ts +236 -31
  31. package/web/cloth-panel.ts +1 -1
  32. package/web/compare.css +2 -2
  33. package/web/environment-world.ts +9 -0
  34. package/web/i18n.ts +1 -3
  35. package/web/inspection-persistence.ts +19 -6
  36. package/web/interview-panel.ts +13 -80
  37. package/web/job-rig-screen.ts +65 -37
  38. package/web/job-session.ts +204 -64
  39. package/web/label-placement.ts +25 -8
  40. package/web/main.ts +350 -114
  41. package/web/part-selection.ts +2 -1
  42. package/web/parts-viewport-provider.ts +21 -8
  43. package/web/rebuild-client.ts +3 -5
  44. package/web/rig-host.ts +5 -4
  45. package/web/rig-overlays.ts +3 -2
  46. package/web/rig-viewport-provider.ts +10 -6
  47. package/web/stage-comments.ts +24 -21
  48. package/web/styles.css +23 -51
  49. package/web/viewport-controller.ts +4 -0
  50. package/web/workspace-layout.ts +4 -4
  51. package/web/workspace-ui.ts +8 -6
package/docs/DESIGN.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  The delivery unit is an existing output folder or an optional curated review package handed from an agent to a person. This reusable app owns inspection, reference comparison, annotations and feedback export. Upstream compiler, splitter and runtime remain their respective tools. The existing producing agent needs no change to open its output here.
6
6
 
7
- The person uses the existing inspection workspace. The header **Setup · Animate · Compare** is the sole mode switch; the resizable bottom panel shows the current mode's blocks plus **Comments (n)**, with the act bar at the right of that row (#741). Parts packages use this same screen (#745). Header Compare retains its existing A/B comparison with a reference, enabled when a second build is supplied; its View, Rig, Playback and Feedback sections remain unchanged. Card D is **PARKED**, not planned. Setup already offers Difference as the fourth view item for parts (#745) and rig (#752). Setup covers setup geometry, source art, pivot/joint placement, meshes, weights and draw order; Animate covers angle coverage, frame intervals, reference video/poses, contact/deformation, audio inspection and the inspection environment (wind, gravity and impulses through the published player's `environment`/`moved`; its state is feedback context, never a model or motion edit) and the physics tuning panel (#103: constraint values edited as config patch ops and applied through the producer, never written into the model by review), and the readings block (#108: the compiler's own `rigc render` readings of the drawn animation, run on the inspected build and on the latest scratch build, shown as timeline ticks and worst-frame lines), the Environment block's *Use for readings* (#112: the controls exported as a `rigc-environment/1` schedule that readings, Apply's check and *Check under this world* — the installed producer's `rig-parts check --environment` — read, so the bars and readings are taken under the wind the person watched; the schedule is feedback context and is never authored into the rig), and the requirements block (#113: the scene's declared requirements written as a `spine-parts-requirements/1` file and measured by the installed producer's `rig-parts check --requirements`, one worst-frame line each). Time/angle controls navigate inspection. Timeline edits are six typed keyed operations on a scratch copy of `motion.animations_from`, built by the installed producer; review never writes source motion. Implemented modeling instruments send bounded changes through the installed producer into scratch, including setup-space mesh deltas.
7
+ The person uses the existing inspection workspace. The header **Setup · Animate · Compare** is the sole mode switch (#741); the resizable bottom panel shows the current mode's blocks, the top **Comment · C** button opens the bottom Comments panel and pin capture without a bottom Comments tab (#835), and live-job act controls sit in the shared act row (`#workspace-act-row`) directly beneath the top bar (#845; standalone package inspection keeps the act bar in the bottom heading). Parts packages use this same screen (#745). Header Compare retains its existing A/B comparison with a reference, enabled when a second build is supplied; its View, Rig, Playback and Feedback sections remain unchanged. Card D is **PARKED**, not planned. Setup already offers Difference as the fourth view item for parts (#745) and rig (#752). Setup covers setup geometry, source art, pivot/joint placement, meshes, weights and draw order; Animate covers angle coverage, frame intervals, reference video/poses, contact/deformation, audio inspection and the inspection environment (wind, gravity and impulses through the published player's `environment`/`moved`; its state is feedback context, never a model or motion edit) and the physics tuning panel (#103: constraint values edited as config patch ops and applied through the producer, never written into the model by review), and the readings block (#108: the compiler's own `rigc render` readings of the drawn animation, run on the inspected build and on the latest scratch build, shown as timeline ticks and worst-frame lines), the Environment block's *Use for readings* (#112: the controls exported as a `rigc-environment/1` schedule that readings, Apply's check and *Check under this world* — the installed producer's `rig-parts check --environment` — read, so the bars and readings are taken under the wind the person watched; the schedule is feedback context and is never authored into the rig), and the requirements block (#113: the scene's declared requirements written as a `spine-parts-requirements/1` file and measured by the installed producer's `rig-parts check --requirements`, one worst-frame line each). Time/angle controls navigate inspection. Timeline edits are six typed keyed operations on a scratch copy of `motion.animations_from`, built by the installed producer; review never writes source motion. Implemented modeling instruments send bounded changes through the installed producer into scratch, including setup-space mesh deltas.
8
8
 
9
9
  ## Core UI rules (owner, 2026-11-11)
10
10
 
@@ -168,10 +168,10 @@ The single review page is one inspection workspace: a left column, the stage, th
168
168
  - **Weights.** In Setup, after the Mesh panel: `#weights` (#107), a watch layer. **Show weights** (`#weights-show`, `aria-pressed`) draws the selected slot's setup-pose mesh on `#rig-overlay` with each vertex coloured by the picked bone's stored weight (`#weights-bone`, influencing bones first) on the ramp tokens `--rv-weight-0` / `--rv-weight-half` / `--rv-weight-1`, or by its dominant bone (`#weights-mode` Max influence, `--rv-weight-bone-1…6`); `#weights-legend` and the hover readout `#weights-hover` sit under it. Weights are read from the compiled model document (`src/weights.ts` over the shared reader `src/setup-mesh.ts`); positions, triangles and hull come directly from published Play 1.14.0's `readSetupMesh` (`web/setup-pose.ts`, shared with Edit Mesh), including selected setup-slider deform. A never-played `RigPlayer` reads only public setup identity; its active skin selection stays distinct from the supplying table, and null identities are never guessed. A package without the document refuses `WEIGHTS_MODEL_UNAVAILABLE`. No edit, Apply or record; the Mesh edit preview wins when both are on.
169
169
  - **Bones.** In Setup, after Weights: `#bones-panel` (#109). **Edit bones on stage** (`#bones-edit`) draws the handoff config's bone anchors — `at`, chain `points`, `tip` — on `#rig-overlay` through the crop → world mapping (tokens `--rv-bone-line`, `-origin`, `-point`, `-tip`, `-pending`, `-selected`, `-ink`, `-label-bg`; the stage stays dark in both schemes, so both blocks carry the same values). A drag moves an anchor by whole rig px; each move is a `replace` op at its JSON Pointer naming the bone (`src/bone-anchors.ts`, `web/bones-panel.ts`). Check (`POST /api/bones-check`, `src/bones-check.ts`) runs `propose --from-config` and `compare` on a scratch copy of the patched config and shows their lines as printed; a LINT line blocks nothing. Apply is the generic patch runner's whole-rig `rig` op behind the reproduced baseline. Adding, removing or re-parenting bones is out of scope.
170
170
  - **Rig fields.** In Setup, after Bones: `#rig-fields` (#110). The producer config's small fields as patch ops at their own pointers (`src/rig-fields.ts`, `web/rig-fields-panel.ts`): a rigid part's bone (`/regions/<part>`, a select), a lash's blink still row (`/motion/blink/still/<part>`, a dashed line across the part dragged in whole rig px), a stop's inward / outward bounds (`/stops/<i>`, two filled arcs at the pivot around a dashed rest aim, their ends dragged in whole degrees), an inherit mode per bone (`/bones/<i>/inherit`, a chain's `link_inherit`) and `turn`'s pivot and per-part depth (`/turn/pivot`, `/turn/depths/<part>`, sliders). Stage handles live in `#rig-fields-stage` over the rig viewport (tokens `--rv-field-still`, `-inward`, `-inward-line`, `-outward`, `-outward-line`, `-rest`, `-handle-bg`, `-ink`; the stage stays dark, so both blocks carry the same values). The turn dial holds the drawn build's `turn` bone at x through play's `adjust`, composed with the idle preview, and shows `#rig-fields-dial-label` (*preview — Apply decides*); it is never recorded. Apply is the generic runner's whole-rig `rig` op behind the reproduced baseline; the readout quotes `BLINK_NO_HOLE` and `FEET_STAY_LEVEL` before and after, and **Angle range** runs one #108 reading. Adding a stop and `turn.deform` are out of scope.
171
- - **Cloth.** In Setup, after Cuts: `#cloth-panel` (#111). One form per cloth tag the installed reader accepts (`bottomwear`, `back hair`, `front hair` — its own `CLOTH_TARGETS`), holding the recipe's fields as the config states them; each change is a patch op at `/cloth/<tag>/…` (`src/cloth-recipe.ts`, `web/cloth-panel.ts`). **Show links** draws, in rig px of the setup pose, every chain the tag's parts are meshed on from the config's `points` and `tip`, and after an Apply the chains of the config the producer wrote (one label per set). Apply runs `rig-parts propose --cloth --write-config` on the declared parts, painting and keypoints, then builds the written config (`build` when the config declares `limbs`, else `rig --config`) and reloads it under the stage's Environment. Review never merges the producer's draft: it reads only the written config, lists where it differs from its input and refuses one that differs outside the drafted sections. Hand-editing the drafted constraints is the physics block's, after the draft.
171
+ - **Cloth.** In Setup, after Cuts: `#cloth-panel` (#111). One form per cloth tag the installed reader accepts (`bottomwear`, `back hair`, `front hair`, `handwear-r`, `handwear-l` — resolved from its `package.json` `exports["./cloth-targets.json"]`, schema `rig-parts/cloth-targets@1`, since `@rig-c/parts` 2.51.0, refused as `CLOTH_TARGETS_INVALID` when malformed or outside the package; when that export key is absent on an older producer, it falls back to the tags the config already declares with `read: false` and refuses adding a new tag as `CLOTH_TARGETS_UNAVAILABLE: the installed rig-parts <version> has no cloth-targets export (needs 2.51.0)`), holding the recipe's fields as the config states them; each change is a patch op at `/cloth/<tag>/…` (`src/cloth-recipe.ts`, `web/cloth-panel.ts`). **Show links** draws, in rig px of the setup pose, every chain the tag's parts are meshed on from the config's `points` and `tip`, and after an Apply the chains of the config the producer wrote (one label per set). Apply runs `rig-parts propose --cloth --write-config` on the declared parts, painting and keypoints, then builds the written config (`build` when the config declares `limbs`, else `rig --config`) and reloads it under the stage's Environment. Review never merges the producer's draft: it reads only the written config, lists where it differs from its input and refuses one that differs outside the drafted sections. Hand-editing the drafted constraints is the physics block's, after the draft.
172
172
  - **Mesh edit.** In Setup only, the view bar's **Edit mesh** toggle (`#mesh-edit`, `aria-pressed`) opens `#mesh-editor-bar`: sub-modes Modify / Create / Delete / Edges (keys `V` / `C` / `X` / `E`, one pressed), Undo, Redo, Reset, Download JSON and **Apply · Rebuild** (#135: `rig-parts remesh --delta` through the shared runner, the revision loaded in place, the producer's refusal verbatim; while a delta revision is on the stage Reset returns to the inspected build). A package without the compiled model document refuses `MESH_EDIT_MODEL_UNAVAILABLE` and does not open; whole rig refuses `MESH_EDIT_SELECT_SLOT`; a non-mesh or linked-mesh slot `MESH_EDIT_NO_MESH <slot>`. It edits in setup space (#100): the attachment's stored provenance in the model document (`src/setup-mesh.ts`) and geometry from Play's public `readSetupMesh` (`web/setup-pose.ts`, shared with Weights) and drawn over the paused stage with the stage camera. It records a typed delta (`src/mesh-edit.ts`, `basis: "setup"`, the shape `rig-parts remesh --delta` reads) and previews it over the original triangulation on the overlay; Delete removes only constraint edges the delta added (the triangulation is the producer's); it is not a mesher and never retriangulates, writes the package or runs a producer. The chest editor and mesh edit are exclusive: turning one on turns the other off.
173
- - **Inspector.** The shared bottom panel sits directly under the main view, with saved height and a resizable separator. Header mode selects its content; its tab row remains reachable when content is collapsed. Setup has Part · Modeling · Chest · Mesh · Weights · Bones · Fields · Cuts · Cloth; Animate has Transport · Sound · Environment · Physics · Idle tracks · Readings · Requirements · Retarget · Report and the existing timeline. Each mode appends the same **Comments (n)** tab, and the act bar stays at the right of that row (#741). Parts use Part and Comments; rig-only blocks are disabled with a missing-rig reason. `mountRigInspector`, `bindInspectorBlocks` and `mountBottomPanel` reuse the existing blocks, preserve their state and keep one Comments button/panel across modes. Block navigation does not apply or submit.
174
- - **Review dialog.** This label is historical for rig feedback: `mountRigInspector` moves its existing source context, comments, frame range, category, typed target, correction request, provenance, strip downloads and warnings into **Comments (n)** and removes `#review-dialog`. The decision, submit and save state live in the act bar. Record publications separately reuse existing checkpoint, signoff, reopen and interview forms in a native dialog over this same screen (#754), including an explicitly empty workspace when no picture is supplied. That hosting has shipped; remaining interview-modal work B (#722), record-modal memo-to-Comments work C (#715), and legacy job-window owner-surface removal (#756) have not.
173
+ - **Inspector.** The shared bottom panel sits directly under the main view, with saved height and a resizable separator. Header mode selects its content; its tab row remains reachable when content is collapsed (#741). Setup has Part · Modeling · Chest · Mesh · Weights · Bones · Fields · Cuts · Cloth; Animate has Transport · Sound · Environment · Physics · Idle tracks · Readings · Requirements · Retarget · Report and the existing timeline. The bottom tab row has no visible **Comments (n)** tab (#835): the top **Comment · C** button and `C` shortcut reveal the bottom Comments panel and start pin capture when supported, while live-job act controls sit in `#workspace-act-row` beneath the top bar (#845; standalone package inspection keeps the act bar in the bottom heading). Parts use Part and the Comments panel; rig-only blocks are disabled with a missing-rig reason. `mountRigInspector`, `bindInspectorBlocks` and `mountBottomPanel` reuse the existing blocks, preserve their state and keep one programmatic Comments selection/panel across modes. Block navigation does not apply or submit.
174
+ - **Review dialog.** This label is historical for rig feedback: `mountRigInspector` moves its existing source context, comments, frame range, category, typed target, correction request, provenance, strip downloads and warnings into the bottom Comments panel (opened from the top **Comment · C** entry rather than a bottom **Comments (n)** tab, #835) and removes `#review-dialog`. The decision, submit and save state live in the act bar — in `#workspace-act-row` directly beneath the top bar on live jobs (#845), or in the bottom heading on standalone package screens. Record publications separately reuse existing checkpoint, signoff, reopen and interview forms in a native dialog over this same screen (#754), including an explicitly empty workspace when no picture is supplied. That hosting has shipped; remaining interview-modal work B (#722), record-modal memo-to-Comments work C (#715), and legacy job-window owner-surface removal (#756) have not.
175
175
  - **Footer.** Message (truncated, full text as tooltip) on the left; player, effective layout, renderer, layers, idle, remote control and draft state in the middle; the numeric view region (behind **View region**) and the source hash on the right. The View region body is a `position:fixed` popover above the 40px footer, right-aligned, its width and height clamped to the viewport and its content scrolling inside, so the footer's clipping never hides it and opening it never scrolls the page.
176
176
 
177
177
  ### Status ownership
@@ -315,7 +315,7 @@ beside the act bar. Selecting a mode never applies, approves or submits.
315
315
 
316
316
  The standing Review window hosts published subjects on the existing inspection
317
317
  screen. Rig and parts use its shared viewport and bottom panel. Record
318
- checkpoint, signoff, reopen and interview asks use existing forms in a dialog
318
+ checkpoint, signoff and interview asks use existing forms in a dialog
319
319
  (#754). A record without a picture keeps that absence explicit; it does not
320
320
  manufacture a model or package. Remaining B (#722), C (#715), F (#734) and #756
321
321
  work is tracked in [the screen specification](https://github.com/rig-c/review/blob/main/docs/SCREENS.md#4-migration-order).
package/docs/PANELS.md CHANGED
@@ -179,7 +179,9 @@ repeating gust (equal to the panel's wind at every frame time; between frames
179
179
  rigc holds the frame's value, and the panel states how far that can be from the
180
180
  live wind) — and sends it with readings and with Apply, whose check then runs
181
181
  `rig-parts check --environment`. The wind clock restarts with the clip, so what
182
- you watch is the world the readings and bars are taken in. **Export schedule**
182
+ you watch is the world the readings and bars are taken in.
183
+ A paused seek shows physics replayed from 0 to T under the wind at schedule(T), held constant over the replay, not the varying wind of a real run (#935).
184
+ **Export schedule**
183
185
  downloads the same bytes; **Check under this world** runs `rig-parts check
184
186
  --environment` on the build on the stage (needs `@rig-c/parts` 1.48.0) and shows
185
187
  its `ANIMATIONS_DO_NOT_FOLD` and `TEXTURE_STRETCH` lines beside the same build's
@@ -37,9 +37,9 @@ The illustrative `look` animation in `axes` must also be declared in `animations
37
37
 
38
38
  ## Files and references
39
39
 
40
- Every path is a literal relative path, including `model`, optional `direction`, `scene` and `sets`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
40
+ Every path is a literal relative path, including `model`, optional `frames`, `direction`, `scene` and `sets`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
41
41
 
42
- `model` is optional and must point to `rigc-compiled/3` under a filename ending `.model.json`, produced by an upstream gated rigc build. Review uses the public `@rig-c/play` loader and player; Spine JSON/skel is not its input. Its pages are resolved relative to the model document. Missing model means unavailable playback, never a mock playback success. The optional `sets` path declares an attachment-set sidecar for single-package playback. Without that declaration, attachment presets are unavailable. See [Direction inspection](#direction-inspection).
42
+ `model` is optional and must point to `rigc-compiled/3` under a filename ending `.model.json`, produced by an upstream gated rigc build. Review uses the public `@rig-c/play` loader and player; Spine JSON/skel is not its input. Its pages are resolved relative to the model document. Missing model means unavailable playback, never a mock playback success. The optional `frames` path declares a producer `rigc-frames/1` record inside the package, read, validated and hashed only when present, added to `files`, and exposed on the loaded package as `frames: {path, sha256, sets: [{animation, fps, written, stride, duration}]} | null` (`null` when omitted, leaving older manifests unchanged); a missing declared file, unreadable JSON, non-`rigc-frames/1` `spec`, malformed set field (`sets[].animation`, `fps`, `written`, `stride`, `duration`) or duplicate animation set refuses by name (`FRAMES_MISSING`, `FRAMES_JSON`, `FRAMES_SPEC`, `FRAMES_FIELD`, `FRAMES_DUPLICATE_ANIMATION`), never falling back silently. With a compiled model, each set must be the producer's schedule for the model animation it names, as measured from `@rig-c/core` 3.8.0 `rigc render`: an animation of duration `D` samples to `round(D * fps) + 1` frames, frame `i` at `i / fps`, and `duration` is the last sample's time, not the clip length (a 0.8 s clip at 12 fps gives 11 frames and `duration` 0.8333). So `written` must equal `floor(round(D * fps) / stride) + 1` and `duration` must lie within `1e-9` s of `round(D * fps) / fps`, or the package refuses by name, naming the animation and both figures (`FRAMES_ANIMATION_UNKNOWN`, `FRAMES_COUNT_MISMATCH`, `FRAMES_DURATION_MISMATCH`); an accepted set is that animation's comment frame clock, `written` frames with frame `i` at `i * stride / fps`, unless the report's clock names the animation ([Stability: frames declaration](STABILITY.md#package-manifest-frames-declaration)). The optional `sets` path declares an attachment-set sidecar for single-package playback. Without that declaration, attachment presets are unavailable. See [Direction inspection](#direction-inspection).
43
43
 
44
44
  Reference `type` is `image`, `video`, or `pose`. `width` and `height` optionally state image pixel dimensions. The primary animated pose input is the canonical `rig-pose-sequence/1` format documented by `@rig-c/pose`, consumed directly:
45
45
 
@@ -96,7 +96,7 @@ Audio clips contain `id`, local `path` and optional `label`. Cues require `id`,
96
96
 
97
97
  New feedback requires safe integer frame indices and actual target membership. Unknown names are refused by name, such as `feedback.target.name: slot "no_such_slot" not in model`. Missing model metadata produces a named validation-unavailable refusal for bone/slot feedback. Rig feedback names the exact package id. Scan joints and point expressions are not guessed into model targets.
98
98
 
99
- For a matching report/actual model animation with an explicit bounded clock, `frameEnd` cannot exceed the last declared sample at or before that model clip's end. A clip with no declared sample inside its duration has no valid feedback frames. A different animation cannot borrow the report clock; its frame bound stays unknown. Source-only explicit report clocks remain usable without inventing model animation identity. No duration/frame-count ratio or video FPS supplies a limit; unknown clocks permit manual safe integer intervals.
99
+ For a matching report/actual model animation with an explicit bounded clock, `frameEnd` cannot exceed the last declared sample at or before that model clip's end. A clip with no declared sample inside its duration has no valid feedback frames. A different animation cannot borrow the report clock; its frame bound stays unknown unless the declared `frames` record has a set for it, which bounds it the same way. Source-only explicit report clocks remain usable without inventing model animation identity. No duration/frame-count ratio or video FPS supplies a limit; unknown clocks permit manual safe integer intervals.
100
100
 
101
101
  The server derives `context.interval:{frameStart,frameEnd,inclusive:true}` from the chosen top-level annotation. Contradictory supplied interval data is refused; optional inspection `time` and `frame` remain separate and do not replace it. Compare uses the selected side's catalog and the CLI's exact animation; a row cannot borrow another side's names or bypass the animation binding.
102
102
 
@@ -191,7 +191,7 @@ Every edit card states its edit as one config patch; review applies it to a scra
191
191
  - **Baseline reach (#148).** When the baseline does not reproduce, `baseline.reach` (`src/baseline-reach.ts`) reads both rig directories and states what each producer op will still take, from the producer's own holds: `{schema:"rig-review-baseline-reach/1", notWriterText[], images[], retuneHeld, remeshRefused[], meshParts[], bonesDiffer, ops:{retune, delta, version}, text}`. `notWriterText`: the inspected `rig.json`, `motion.json` and `mesh_report.json` that are not `JSON.stringify(value, null, 1)` and a closing newline (the writer, parts `rigJsonText`) — remesh and its mesh edit refuse `rig.json` / `mesh_report.json` (`REMESH_INPUT_WRITTEN`), retune `rig.json` / `motion.json` (`RETUNE_INPUT_WRITTEN`). `images`: the images the config draws differently. `retuneHeld`: retune's first held difference in its own order (stops, bones, slots, skeleton, images, invariants but `detached`, each image, motion.json outside `animations.idle`), or null when a physics or idle edit Applies. `remeshRefused`: the meshed parts (`skins.default.<part>.<part>` of type `mesh`) whose attachment, image or report row (or an `auto` row's motion) the config does not reproduce — remesh from a config entry refuses them `REMESH_BASELINE_MISMATCH` and re-fits the rest; `bonesDiffer` refuses every part. A mesh edit (`remesh --delta`) builds no config entry, so the baseline does not hold it. `ops` is the installed producer's: below 1.44.0 a physics or idle edit is whole-rig. `text` is appended to the baseline line (`baseline: not reproduced — <first differing path> · <text>`) and to `EDIT_BASELINE_MISMATCH: <path> — <text>`. It is review's reading of the producer's rules; the producer's line on Apply stays the judgment. For family/roa as committed: `out/rig/rig.json, out/rig/mesh_report.json are not the text rig writes for their values (reformatted, or written by another tool), and an op that splices a revision as text refuses such a file — use the files as rig wrote them, or re-serialise them in a copy of the package exactly as rig writes them (JSON with one space of indent and a closing newline) and open the copy; whole-rig edits refuse (EDIT_BASELINE_MISMATCH); physics and idle edits (retune) refuse out/rig/rig.json (RETUNE_INPUT_WRITTEN), and past that the config draws out/rig/images/topwear.png differently and retune holds every image (RETUNE_REQUEST_HELD); remesh and a mesh edit refuse out/rig/rig.json, out/rig/mesh_report.json (REMESH_INPUT_WRITTEN); past that, remesh: bottomwear, topwear, hair_back, hair_front are refused (REMESH_BASELINE_MISMATCH: …); handwear_r, neck, earring can be re-fit`.
192
192
  - **Producer refusal hint (#148).** When the producer refuses with a line review can explain — `REMESH_INPUT_WRITTEN` / `RETUNE_INPUT_WRITTEN` (a file that is not the writer's text) or `RETUNE_REQUEST_HELD: images/<name>` (an image the config draws differently) — the job keeps `producerLine` as printed and adds `hint` (absent otherwise), also pushed to `lines` as `review: <hint>`; the status line reads `<producer line> · review: <hint>`. For `RETUNE_INPUT_WRITTEN` on `rig.json`: `rig.json in the inspected rig is not the text rig writes for its value (reformatted, or written by another tool); retune splices a revision as text, so it refuses the file — use the files as rig wrote them, or re-serialise them in a copy of the package exactly as rig writes them (JSON with one space of indent and a closing newline) and open the copy`.
193
193
  - **Build (#115).** A `rig` patch with any op at or under `/assemble` or `/limbs` — or under `/bones` on a config that declares `limbs`, whose joints are their bones' origins — runs `rig-parts build` (op `build`): those sections are read by the producer's assemble stage, which `rig --config --parts` never runs (rig-parts AUTHORING §3, the `assemble.cuts`, `assemble.patches` and `limbs` rows). It needs the handoff's painting and full run (`--source <png> --full <dir> [--head <dir>]`, or the review.json block); without them it refuses before anything runs: `MODELING_INPUT_UNAVAILABLE: source painting and See-through runs — rig-parts build reassembles the parts from the painting (--source) and the runs (--full, --head) before the rig, and the handoff declares none; declare them with …`. It is a whole-rig op behind the reproduced baseline (`EDIT_BASELINE_MISMATCH`). The files assemble reads by the config's own naming (each cut's `under`, each limb segment's `cap`, each alternate's `source`, `full`, `head` and `skeleton`) are resolved against the handoff config's directory, must stay inside the package root (`BUILD_INPUT_OUTSIDE_ROOT`, `BUILD_INPUT_MISSING`) and are hashed into the build id — a named directory outside the declared runs by its contents (every regular file under it, at most 8 levels deep and 4096 files, each held inside the package root, in path order; over the bound refuses `BUILD_INPUT_TOO_LARGE`), a declared run through the handoff record (#185); a patch may not name a new one (`EDIT_PATCH_PATH_HELD` — it may keep, move or drop one the config names). `config.json` is the patched config with those paths and the two above made absolute, then `rig-parts build --config config.json --source <handoff source> --full <handoff full> [--head <handoff head>] --out out --seam-pairs [args]`; the rig spec is `out/rig`, and the shared tail diffs and compiles it (no second check: build's own check ran on the parts it assembled). A stage that refuses leaves no scratch, and its FAIL lines come back verbatim (the stage prefix `[assemble]`, `[rig]`, `[check]` stripped); a build that stopped at check with bars not met is kept, check's FAIL lines beside it. The job adds `assembled: {inputs:{source, full, head, named:[{field, path, sha256|null}]}, refusals[], checkFails[], lines[] (the cut:, limb cut:, limb cap: and uncovered-hole lines), seam[], seamPairs[] (the base set's `seam pair` lines), recomposite:{line, before, after, errorMap:{url, sha256}|null}, parts:{changed[], unchanged, partsJson:{count, paths}}|null}` (`before` is the handoff's `parts.json` recomposite block, `after` the scratch one; `errorMap` serves `out/recomposite_error_rig.png` read-only at `/rebuild/<id>/recomposite/recomposite_error_rig.png`), and `wallMs.op` is the build's own wall clock (assemble → rig → check).
194
- - **Cloth (#111).** A `rig` patch whose ops all lie under `/cloth` (the Setup · Cloth block: one recipe per tag the installed reader accepts — read from its own `CLOTH_TARGETS` — with the reader's fields) runs op `cloth`; a patch mixing `/cloth` ops with others is refused before anything runs (`CLOTH_PATCH_MIXED`). Refused before anything runs: `CLOTH_KEYPOINTS_UNDECLARED` when the handoff declares no `--keypoints` (without them the draft moves the body bones the config states — Decision 1), `MODELING_PRODUCER_TOO_OLD <found> 1.49.1` (the first `@rig-c/parts` whose `--write-config` splices `bones`, `constraints` and `motion.tracks` entry by entry, parts#552), `MODELING_INPUT_UNAVAILABLE: source painting …` without `--source`, and, as a whole-rig op, `EDIT_BASELINE_MISMATCH`. `cloth.json` is the patched config written as `rig` writes its scratch config, with the assemble-read paths made absolute as for `build`; then `rig-parts propose --parts <handoff parts> --source <handoff source> --keypoints <handoff keypoints> --out propose --cloth cloth.json --write-config config.json` (no `--wrist-snap` or `--grid-rule`: the handoff states neither). Its refusals come back verbatim, every FAIL line in `cloth.refusals` — the reader's `CONFIG_CLOTH_*`, `PROPOSE_CLOTH_DRAFTED` (a recipe that drafts nothing), `PROPOSE_CLOTH_PART`, and the write's `PROPOSE_WRITE_CONFIG_FRESH`, `PROPOSE_WRITE_CONFIG_CONFLICT` (an entry the recipe re-drafts or removes that equals neither the draft with the recipe nor the draft without it, rig-parts AUTHORING *The config written*) and `PROPOSE_WRITE_CONFIG_SPLICE`. Review reads only the written `config.json`, never the producer's draft file: it lists every JSON Pointer at which the written config differs from `cloth.json` and refuses to build one that differs outside the sections propose splices (`bones`, `constraints`, `meshes`, `regions`, `limbs`, `motion/tracks`, `turn`, `proposed_rig_scale`): `CLOTH_WRITTEN_OUTSIDE_DRAFTED`. The written config is then built (Decision 2) as `rig-parts build --config config.json …` exactly as a `build` patch when the config declares `limbs` (the job adds `assembled`), else `rig-parts rig --config config.json --parts <handoff parts> --out rig`, and goes through the shared tail. The id adds `cloth`, the keypoint file's hash and (for the build route) the build inputs' hash. The job adds `cloth: {route:"build"|"rig", inputs:{source, keypoints:{path, sha256}}, refusals[], line (propose's `wrote config.json: …` line), written:{count, paths[≤200], outside[≤200], sections[]}|null, links[] (per tag: its parts and the written config's chains, the link preview), wallMs:{propose, build}}`. `GET /api/rebuild` adds `cloth: {targets, targetsRead, recipes, tags[] (per tag: its parts by See-through tag or by the recipe's `part`/`parts`, and the chains their `meshes.<part>.segments` name with `points` and `tip`), keypoints, route, reason}`.
194
+ - **Cloth (#111).** A `rig` patch whose ops all lie under `/cloth` (the Setup · Cloth block: one recipe per tag the installed reader accepts — resolved from its `package.json` `exports["./cloth-targets.json"]`, schema `rig-parts/cloth-targets@1`, since `@rig-c/parts` 2.51.0, refused as `CLOTH_TARGETS_INVALID` when malformed or outside the package; when that export key is absent on an older producer, it falls back to the tags the config already declares with `read: false` and refuses adding a new tag as `CLOTH_TARGETS_UNAVAILABLE: the installed rig-parts <version> has no cloth-targets export (needs 2.51.0)` — with the reader's fields) runs op `cloth`; a patch mixing `/cloth` ops with others is refused before anything runs (`CLOTH_PATCH_MIXED`). Refused before anything runs: `CLOTH_KEYPOINTS_UNDECLARED` when the handoff declares no `--keypoints` (without them the draft moves the body bones the config states — Decision 1), `MODELING_PRODUCER_TOO_OLD <found> 1.49.1` (the first `@rig-c/parts` whose `--write-config` splices `bones`, `constraints` and `motion.tracks` entry by entry, parts#552), `MODELING_INPUT_UNAVAILABLE: source painting …` without `--source`, and, as a whole-rig op, `EDIT_BASELINE_MISMATCH`. `cloth.json` is the patched config written as `rig` writes its scratch config, with the assemble-read paths made absolute as for `build`; then `rig-parts propose --parts <handoff parts> --source <handoff source> --keypoints <handoff keypoints> --out propose --cloth cloth.json --write-config config.json` (no `--wrist-snap` or `--grid-rule`: the handoff states neither). Its refusals come back verbatim, every FAIL line in `cloth.refusals` — the reader's `CONFIG_CLOTH_*`, `PROPOSE_CLOTH_DRAFTED` (a recipe that drafts nothing), `PROPOSE_CLOTH_PART`, and the write's `PROPOSE_WRITE_CONFIG_FRESH`, `PROPOSE_WRITE_CONFIG_CONFLICT` (an entry the recipe re-drafts or removes that equals neither the draft with the recipe nor the draft without it, rig-parts AUTHORING *The config written*) and `PROPOSE_WRITE_CONFIG_SPLICE`. Review reads only the written `config.json`, never the producer's draft file: it lists every JSON Pointer at which the written config differs from `cloth.json` and refuses to build one that differs outside the sections propose splices (`bones`, `constraints`, `meshes`, `regions`, `limbs`, `motion/tracks`, `turn`, `proposed_rig_scale`): `CLOTH_WRITTEN_OUTSIDE_DRAFTED`. The written config is then built (Decision 2) as `rig-parts build --config config.json …` exactly as a `build` patch when the config declares `limbs` (the job adds `assembled`), else `rig-parts rig --config config.json --parts <handoff parts> --out rig`, and goes through the shared tail. The id adds `cloth`, the keypoint file's hash and (for the build route) the build inputs' hash. The job adds `cloth: {route:"build"|"rig", inputs:{source, keypoints:{path, sha256}}, refusals[], line (propose's `wrote config.json: …` line), written:{count, paths[≤200], outside[≤200], sections[]}|null, links[] (per tag: its parts and the written config's chains, the link preview), wallMs:{propose, build}}`. `GET /api/rebuild` adds `cloth: {targets, targetsRead, targetsReason, recipes, tags[] (per tag: its parts by See-through tag or by the recipe's `part`/`parts`, and the chains their `meshes.<part>.segments` name with `points` and `tip`), keypoints, route, reason}`.
195
195
  - **Run.** Scratch is `<state>/rebuild/<package source hash>/<id>/`, `id = sha256([rig-review-rebuild/1, "patch", source hash, config SHA-256, the patch's canonical bytes, producer@version, compiler@version])` — no clock; the same patch again reuses its build. `rig`: `config.json` there is the patched config written as the producer's own scratch configs are (2-space JSON, every `configFileReferences` path made absolute when it names an existing entry beside the handoff config), then `rig-parts rig --config config.json --parts <handoff parts> --out rig [args]`, or for a retune-routed patch `rig-parts retune --rig <handoff rig> --config config.json --parts <handoff parts> --out rig [args]` (the same config; retune reads the inspected rig and writes only `rig/`, with `retune.json`). `remesh`: `mesh.json` is the patched `meshes.<part>` entry and `rig-parts remesh --rig <handoff rig> --config <handoff config> --parts <handoff parts> --part <part> --mesh mesh.json --out rig [args]` (remesh reads the config as written). Then `rigc build --rig rig/rig.json --motion rig/motion.json --out build --profile rig-play --pack --page-edges … --pack-shape …` (the args' values, else `free` / `polygon`; for remesh, its `remesh.json` request; for retune, its `retune.json` request) and `rig-parts check --rig rig --out check --parts <handoff parts>` with the same pack flags. A producer or compiler refusal is the first named line verbatim and leaves no scratch; a check `FAIL` is check's judgment, kept beside the build.
196
196
  - **A retune's check (#139).** A retune-routed Apply does not run `rig-parts check` a second time: retune already gated and checked the revision it wrote (`checkStage` over that revision, the same `--parts` and pack flags review passes), and from `@rig-c/parts` 1.49.0 (`RETUNE_CHECK_SINCE`, parts#541) `retune.json`'s `check.revision` carries `line` — check's own last line, byte for byte — and `status` — every block's status as that tree's `check.json` records it, in the file's order. Review first binds it to the files: every `revision` hash row's file under `rig/` must hash to its row, none missing, and `rig/` holds no file but those rows and `retune.json`; otherwise the Apply is refused `RETUNE_CHECK_STALE: <file> sha256 <in retune.json> … <on disk>; retune's check is not this revision's, so no build is recorded` (`absent` on the side without the file) and leaves no scratch. Bound, the side becomes the same check summary a separate check gives (below): `pass` ← `pass`; `exitCode` ← 0 when it passes, else 1 (check's own exit); `line` ← `line`; `bars` ← every upper-case `status` entry (`gate`, `loop` and `seam` are read off figures and are not check.json bars); `gate` ← `status.gate` is `PASS`; plus `source:"retune"`. The job's `wallMs.check` is `null` and its lines say `review: check not run again — retune.json carries retune's check of this revision, bound to it by N revision hash row(s): <line>`. Check still runs on the revision, as before, when `retune.json` carries no `line` / `status` (an older producer; the line says so — not a refusal) or when the Apply checks under an exported world (#112; retune's check read the default one). Whole-rig `rig`, `build` and cloth keep running check.
197
197
  - **A remesh's check (#174).** A `remesh` patch Apply (#106) reads `rig-parts remesh`'s own check of its revision the same way, with one binding shared with retune: `remesh.json`'s `check.revision` (`line` and `status` since `@rig-c/parts` 1.49.0, `REMESH_CHECK_SINCE`; the same parts#541 change) is bound by its `revision` hash rows to the files under `rig/` (none missing, none but those rows and `remesh.json`), else the Apply is refused `REMESH_CHECK_STALE: <file> sha256 <in remesh.json> … <on disk>; remesh's check is not this revision's, so no build is recorded` and leaves no scratch. remesh checked the revision with its request's `page_edges` / `pack_shape` — the flags review's own check reads from `remesh.json` — and the handoff `--parts`; a patch passes no `--requirements`. Bound, the summary is the same mapping as retune's with `source:"remesh"`; `wallMs.check` is `null` and the line says `review: check not run again — remesh.json carries remesh's check of this revision, bound to it by N revision hash row(s): <line>`. An older `remesh.json` or an Apply under an exported world runs check, and the line says why. The designation remesh (#99) and Edit Mesh's `remesh --delta` (#135) run no review check at all (remesh's own gate holds check there), so they are unchanged.
@@ -286,7 +286,7 @@ Edit Mesh's **Download JSON** (#80, setup space since #100) saves two files; nei
286
286
 
287
287
  `mesh-edit.binding.json` (`rig-review-mesh-edit-binding/1`) binds the delta: `file {name, sha256}`, the package source hash, the model and motion SHA-256, `attachment {slot, skin, name, sha256}` (the same `hash`), `exportedAt`, the viewer and runtime versions, `mapping` (the crop mapping's basis) and an evidence note. Apply · Rebuild (#135) sends the same document as `{part, delta, configHash}` (bounded to 64 KiB, same-origin); the server writes it with the download's bytes and runs `rig-parts remesh --delta mesh-edit.json --part <part>` over the handoff rig (`@rig-c/parts` 1.43.0 or later, else `MODELING_PRODUCER_TOO_OLD <found> 1.43.0`). The producer computes `source.hash` from its own rigc build of the input and refuses a mismatch (`REMESH_DELTA_SOURCE`), a non-setup basis (`REMESH_DELTA_BASIS`) and an op that does not replay (`REMESH_DELTA_OP`); each line is shown verbatim. A built revision's `context.applied` is `rig-review-applied/3`: `{schema, buildId, part, delta, deltaSha256, configHash, producer, compiler, line, op: "remesh", files, mesh?, modelHash}`. `deltaSha256` is the SHA-256 of the bytes written, which equal the download's `mesh-edit.json`.
288
288
 
289
- The live-job handoff uses [Mesh edits on Request changes (act@8)](#mesh-edits-on-request-changes-act8). Standalone `--delta` and its download format remain available for legacy callers.
289
+ The live-job handoff uses [Mesh edits on Request changes (act@8)](#mesh-edits-on-request-changes-act8) and [Chest landmarks on Request changes (act@9)](#chest-landmarks-on-request-changes-act9). Standalone `--delta` and its download format remain available for legacy callers.
290
290
 
291
291
  ## Historical feedback retrieval
292
292
 
@@ -1122,7 +1122,7 @@ or establish official Create writer acceptance.
1122
1122
 
1123
1123
  ### Publication, producer-held freeze and generation CAS
1124
1124
 
1125
- - **Mutating requests and CAS.** Agent mutations (`publish`, `ask`, `close` in `JobMutation`) require `expectedGeneration` (a nonnegative safe integer) and `idempotencyKey` alongside `schema` (`rig-review/job-api@2`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`. When `handleJobApi` (`POST /jobs/<jobId>/api`) catches a thrown refusal, the failure envelope `generation: number` reports `session.lastObservedGeneration`, which is the last durable generation this session observed successfully in storage and is carried in memory without rereading failing storage inside `catch`. That value reports the last observed session generation while preserving the original named refusal code and message (such as `JOB_STORAGE_FAILED` when SQLite files are removed or replaced) and keeping the numeric `generation: number` response type unchanged. A failed session constructor exposes no API ports when its initial storage read fails. Success responses continue to report current `session.status().generation`.
1125
+ - **Mutating requests and CAS.** Agent mutations (`publish`, `ask`, `close` in `JobMutation`) require `expectedGeneration` (a nonnegative safe integer) and `idempotencyKey` alongside `schema` (`rig-review/job-api@2`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`. A repeated `idempotencyKey` with the same payload returns the stored result only while that result is still true ([Review #1022](https://github.com/rig-c/review/issues/1022)): a replayed `publish` whose publication is no longer the head refuses `JOB_ACT_SOURCE_STALE`, and a replayed `ask` whose ask is no longer pending and has no finalized act refuses `JOB_ASK_SUPERSEDED` (`JOB_CLOSED` once the job is closed). Each refusal message names the replayed identity and the current head (`publication <id> is superseded; head <id>`, `ask <id> is superseded; head <id>`). A replay of a still-head publication, a still-pending ask or an ask whose act was finalized returns its stored result unchanged, and a `close` replay is unchanged. When `handleJobApi` (`POST /jobs/<jobId>/api`) catches a thrown refusal, the failure envelope `generation: number` reports `session.lastObservedGeneration`, which is the last durable generation this session observed successfully in storage and is carried in memory without rereading failing storage inside `catch`. That value reports the last observed session generation while preserving the original named refusal code and message (such as `JOB_STORAGE_FAILED` when SQLite files are removed or replaced) and keeping the numeric `generation: number` response type unchanged. A failed session constructor exposes no API ports when its initial storage read fails. Success responses continue to report current `session.status().generation`.
1126
1126
  - **Explicit producer-held freeze.** `JobPublishRequest` designates a root-relative `result` (`path` and nullable `selector`, never a command) and requires `freeze` with `kind` set to `'producer-held'`, `holdId` and `record` (`JobFileIdentity` for the exact record used for selection, or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved or incomplete record (`JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local CAS. The freeze assertion is a caller obligation on the publishing producer or agent, not a lock Review can impose on independent writers.
1127
1127
  - **Managed-state privacy boundary.** Managed state stays behind the host ports. The canonical work root and configured managed-state directory must be disjoint. A root equal to, inside or containing that state directory refuses `JOB_SOURCE_UNRETAINABLE` before job admission, including directory aliases resolved through symlink ancestors. Existing root identity failures, including a directly symlinked source root, retain `JOB_ROOT_REPLACED`. Trusted publication handles follow the origin job's lifetime, and publishing callers must maintain their producer-held freeze.
1128
1128
  - **Explicit close lifecycle.** Review offers no watched-root or automatic-close guarantee. Only an explicit `close` request (`JobCloseRequest` with `reason`) ends an active job (`status` transitions from `'active'` to `'closed'`, and subsequent mutations or fetches refuse with `JOB_CLOSED`).
@@ -1134,6 +1134,7 @@ or establish official Create writer acceptance.
1134
1134
  - **Daemon-derived source binding.** The original model branch of `JobSourceBinding` requires non-null `sourceHash` (`JobSha256`) and `package` (`id` and `revision`), and requires explicit values or explicit `null` for its typed nullable fields (`projectHash`, `selector` as `draft` / `rig` / `post`, `model`, `direction`, `optionSet`, `appliedResult`, `plan`, `parts`). Original input paths are literal project-relative or package-relative provenance only, and no public field names a Review state directory or stored document. The daemon derives `JobSourceBinding` from validated retained bytes and the actual displayed publication. Clients never provide trusted source hashes or transfer prior approval onto a new binding.
1135
1135
  - **Display receipt and UI submission.** `JobDisplayPublication` pins same-origin `routes` (`entry`, `apiBase`, `assetsBase`) to that specific `publicationId` and `instanceKey` without a mutable current alias. All metadata, images, runtime assets, routes and pending form dependencies prepare before the visible swap; paint and the single `displayedNonce` acknowledgment precede retirement of the previous view, and failed preparation or acknowledgment restores the prior view and draft. After `ackDisplayed` validates `JobDisplayAcknowledgment` (`publicationId`, `pageId`, `sourceHash`), it returns `JobDisplayReceipt` containing the page-scoped `displayedNonce` secret (never returned by the agent or consumer API). `JobUISubmission` supplies `publicationId`, `askId`, `pageId`, `displayedNonce`, `expectedGeneration`, `submissionId`, `kind` and `value` (`JobUIActValues`). Neither `authority` nor `source` is accepted from the browser. The daemon derives both from the validated nonce and displayed publication (`JOB_DISPLAY_MISMATCH`, `JOB_ACT_SOURCE_STALE`). Retrying the same `submissionId` returns the same immutable `JobAct`, while a changed payload refuses.
1136
1136
  - **Pinned package input recheck.** Each applicable pinned package request rechecks the full package byte binding against the publication, with no stale-response window. A removed or changed bound member, a symlink swap outside the valid package path, or a member recreated with different bytes refuses on the very next applicable request with HTTP 409 `JOB_SOURCE_MISMATCH`. Restoring identical bytes at a valid path resumes successful reads, including when the regular file was recreated.
1137
+ - **Cache policy ([Review #1050](https://github.com/rig-c/review/issues/1050)).** Publication JSON, `api/*` JSON, the event stream, acts and every refusal stay `Cache-Control: no-store`. A sealed snapshot file under a publication's instance route is `private, max-age=31536000, immutable` with its seal SHA-256 as `ETag`: each publish mints a new `publicationId`, so one URL names one content, and the no-store `api/review` read that starts every page load still runs the full package recheck above. The shipped `index.html`, `main.js` and `styles.css` keep one URL across Review installs, so they are `no-cache` with a content `ETag` and revalidate through the job liveness check on every load. In one page load each resource is requested once: `/api/review` once per preparation, and the compiled model once for Play, the part catalog and the physics document together.
1137
1138
  - **Old drafts retained and flagged without rebinding.** When a new publication updates or replaces the displayed source, older local drafts remain retained in storage under their original source binding and are flagged without rebinding or transferring onto the new publication.
1138
1139
 
1139
1140
  ### Act kinds, plan identity and parts identity
@@ -1142,7 +1143,7 @@ or establish official Create writer acceptance.
1142
1143
  - **`interview-picks`.** `JobActValues['interview-picks']` carries `questionId`, ordered `selections` (`itemId`, `optionId`, nullable `otherText`) and `note`, with non-null `source.optionSet` (`id` and `sha256`).
1143
1144
  - **`checkpoint`.** `JobActValues['checkpoint']` carries `checkpointId`, `planStepId`, `outcome` restricted to `'pass'` or `'fail'` and required `words` as a `string`. `pending` stays in the UI draft only and never produces a finalized act. Only `'pass'` is eligible for Create's checkpoint sign-off writer, whereas `'fail'` is feedback or a named consumer refusal and never an approval write. `words` is preserved verbatim including empty or whitespace-only strings, matching Create's writer without adding a UI gate. In `JobSubject`, `checkpointId` defaults to the Create plan step ID and optional `planStepId` is required when the displayed Review checkpoint ID differs, matching [Create #184](https://github.com/rig-c/create/issues/184) without alias inference or browser trust. The browser supplies `checkpointId`, `outcome` and `words` only (`JobUIActValues['checkpoint']`), the daemon copies resolved `planStepId` from the validated ask and requires `source.plan`, and Create derives execution stage from its authoritative step phase and order without Review stamping a stage.
1144
1145
  - **`parts-verdict`.** `JobActValues['parts-verdict']` is `PartsVerdictValue` (`verdict` as `'approved'` or `'changes-requested'`, `issues` as `readonly PartsIssue[]` under `rig-review-parts-comment/2` — empty on `'approved'` and non-empty on `'changes-requested'`, bound to `source.sourceHash`, retained `partIds`, and `source.parts.images` hashes — and `words`), emitted in new finalized `rig-review/act@5` acts (`JobPartsVerdictAct`) and requiring non-null `source.projectHash`, a `draft` selector and `source.parts`. Historical `rig-review/act@2` `parts-verdict` acts remain in the `JobAct` union via `JobLegacyAct` with `value: JobLegacyPartsVerdictValue` (`verdict` as `'pending'`, `'approved'` or `'changes-requested'`, `parts` with `partId`, `part` outcome and note, `mesh` outcome and note with `JobPartOutcome` as `'pending'`, `'clean'` or `'flagged'`, and `words`).
1145
- - **`review-verdict`.** The original model branch carries `stage` (`'rig-review'` or `'direction-review'`), `verdict` and `words`, requiring a `rig` or `post` selector and non-null `source.model` with runtime stage, selector and direction consistency checks.
1146
+ - **`review-verdict`.** The original model branch carries `stage` (`'rig-review'` or `'direction-review'`), `verdict` and `words`, requiring non-null `source.model` with runtime stage, selector and direction consistency checks. A declared `rig-review` ask can also bind a `draft` selector with `source.projectHash` and null `source.direction`. It uses the existing rig screen and still capture, and its finalized act preserves the retained draft publication's source hash, model and selector. A compiled rig's Request changes can carry [chest landmarks (act@9)](#chest-landmarks-on-request-changes-act9).
1146
1147
  - **`signoff`.** `JobActValues['signoff']` carries `stage` (validated by Create's writer), `decision` restricted to `'approved'` only (changes requested are a verdict, never a signoff) and required `words` preserved verbatim including empty or whitespace-only strings. A verdict, a signoff and a Create stage transition are three separate writes, and `JobAct` grants no transition authority. Every stage in `JOB_PLAN_BOUND_SIGNOFF_STAGES` (`'plan-approved'`, `'rigging-interview'`, `'post-interview'`) requires non-null `source.plan` with exact displayed step IDs and hashes before act creation, while other stages keep `source.plan` nullable where appropriate.
1147
1148
  - **Create-published step IDs and hashes.** `JobPlanIdentity` holds `steps` (`id` and `hash`) published by [Create #184](https://github.com/rig-c/create/issues/184) for the displayed plan. Review retains these values without importing or recomputing Create's internal `stepHash`. Create validates them through its existing `steps` and `step_hashes` writer logic, with no separate plan revision hash or additional revision gate in this contract.
1148
1149
  - **C4 manifest-referenced parts PNG identity.** C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
@@ -1173,8 +1174,8 @@ verdict. It verifies each retained Parts `assemble` recomposite against its
1173
1174
  bound hash and seals the original bytes. It omits the declaration when no
1174
1175
  qualifying draft, retained composite or bound hash is available. Review
1175
1176
  validates the declared ID with `jobId` and the revision as lowercase SHA-256.
1176
- The labelled select in the secondary toolbar shows the previous ID and the
1177
- first 12 revision characters. When that operand is selected, its title shows
1177
+ The labelled select in the secondary toolbar shows the previous ID.
1178
+ When that operand is selected, its title shows
1178
1179
  the ID and full revision. Resolution of the accepted draft stays with the
1179
1180
  publisher. [Publisher confirmation](https://github.com/rig-c/review/issues/914#issuecomment-7001422013)
1180
1181
 
@@ -1268,7 +1269,7 @@ The manifest and complete retained image rows enter the composite source hash. L
1268
1269
  - **Sibling binding ownership.** `JOB_CONSUMER_AUTH_MODE` is `'writer-owned-sibling-fetch-capability'` (`JobConsumerGrant` with `jobId`, `operation` set to `'fetch-act'`, `actKinds` and `lifetime` set to `'until-explicit-close'`). [Create #184](https://github.com/rig-c/create/issues/184) owns creation and path of a private writer-owned sibling binding outside `project.json` whose versioned record carries only the semantic job locator (Create's production reader/writer readback integration remains pending [Create #184](https://github.com/rig-c/create/issues/184)). The binding is never tracked in version control, never present in unstaged project output and never shipped in templates, public examples or fixtures.
1269
1270
  - **Agent isolation and capability lifecycle.** The consumer writer reads its own sibling binding directly. Agents never construct, parse or carry Review session, picks, verdict, applied-record or sibling-binding files. Actual separate-UID isolation remains required for Review's distinct state unreadability test (`JOB_AGENT_ISOLATION_HOLE`), and no same-user forger-resistance claim is made. The random per-job bearer capability grants finalized act fetch (`fetch-act`) only, via exact loopback routes and `Authorization`. Neither `next` nor `status` returns it, and human metadata alone never authenticates a fetch. The capability dies at explicit `close`, old project history cannot restore it, each new job incarnation receives a new grant, invalid grants refuse with `JOB_CAPABILITY_REQUIRED` or `JOB_AUTHORITY_REFUSED` and closed-job fetches refuse with `JOB_CLOSED`. No self-service grant API exists.
1270
1271
  - **Consumer deduplication and in-process mesh consumption.** Verdict, signoff and stage transition remain separate consumer writes. For these writes, consumers deduplicate `actId` before checking the current source, then validate each new source and atomically commit the result with its replay identity. Replaying an applied `actId` returns the existing record. A new stale act refuses before mutation. The typed mesh relay uses per-edit identity as defined in [Mesh edits on Request changes (act@8)](#mesh-edits-on-request-changes-act8).
1271
- - **Error codes.** `JOB_ERROR_CODES` enumerates the closed refusal set (`JOB_REQUEST_INVALID`, `JOB_BODY_LIMIT`, `JOB_LOOPBACK_REQUIRED`, `JOB_SAME_ORIGIN_REQUIRED`, `JOB_CAPABILITY_REQUIRED`, `JOB_AUTHORITY_REFUSED`, `JOB_UNKNOWN`, `JOB_CLOSED`, `JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`, `JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`, `JOB_PUBLICATION_UNKNOWN`, `JOB_SNAPSHOT_RECLAIMED`, `JOB_ASK_INVALID`, `JOB_ASK_SUPERSEDED`, `JOB_ACT_UNKNOWN`, `JOB_ACT_INVALID`, `JOB_ACT_KIND_DISABLED`, `JOB_ACT_SOURCE_STALE`, `JOB_DISPLAY_MISMATCH`, `JOB_CURSOR_INVALID`, `JOB_STORAGE_FAILED`, `JOB_AGENT_ISOLATION_HOLE`), each returning bounded safe detail with no arbitrary worker text or private paths.
1272
+ - **Error codes.** `JOB_ERROR_CODES` enumerates the closed refusal set (`JOB_REQUEST_INVALID`, `JOB_BODY_LIMIT`, `JOB_LOOPBACK_REQUIRED`, `JOB_SAME_ORIGIN_REQUIRED`, `JOB_CAPABILITY_REQUIRED`, `JOB_AUTHORITY_REFUSED`, `JOB_UNKNOWN`, `JOB_CLOSED`, `JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`, `JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`, `JOB_PUBLICATION_UNKNOWN`, `JOB_SNAPSHOT_RECLAIMED`, `JOB_ASK_INVALID`, `JOB_ASK_SUPERSEDED`, `JOB_ACT_UNKNOWN`, `JOB_ACT_INVALID`, `JOB_ACT_KIND_DISABLED`, `JOB_ACT_SOURCE_STALE`, `JOB_DISPLAY_MISMATCH`, `JOB_CURSOR_INVALID`, `JOB_STORAGE_FAILED`, `JOB_AGENT_ISOLATION_HOLE`, `JOB_OPTION_SET_DUPLICATE`), each returning bounded safe detail with no arbitrary worker text or private paths.
1272
1273
 
1273
1274
  ### Model-free record mode and source seam
1274
1275
 
@@ -1282,21 +1283,37 @@ A post-interview option set with a `rig` context can also show the accepted rig
1282
1283
 
1283
1284
  | Surface | Exact keys or closed values |
1284
1285
  | --- | --- |
1285
- | `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
1286
+ | `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` or `{kind, questionId, setId, sets}` (`option-set`, `sets` 2–64 `{questionId, setId}` with `sets[0]` equal to the first set), `{kind}` (`plan`) |
1286
1287
  | `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
1287
- | `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`, `direction-review`, `interview`), `{kind: 'reopen', stage}` |
1288
- | `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
1288
+ | `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`, `direction-review`, `interview`), `{kind: 'reopen', stage}` (read only: old records parse, Review neither asks nor renders it) |
1289
+ | `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` and `planPicture` on plans |
1289
1290
  | `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
1290
- | `RecordSource` | Required `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
1291
- | `rig-review-job-record-source/1` | Required `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']`, optional `checkpointEvidence` on plans |
1291
+ | `RecordSource` | Required `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']`, optional `checkpointEvidence` and `planPicture` on plans, optional `optionSets` (`{questionId, setId, optionSet, optionSetFile}` per set) on several-set option-set sources |
1292
+ | `rig-review-job-record-source/1` | Required `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']`, optional `checkpointEvidence` then `planPicture` on plans |
1292
1293
  | `rig-review-job-record-instance/1` | `['schema', 'fingerprint', 'sourceHash']` |
1293
- | `JobCapabilitiesV3` | `{recordPublication: true, recordActSchema: 'rig-review/act@4', askBatch: true}` |
1294
+ | `JobCapabilitiesV3` | `{recordPublication: true, recordActSchema: 'rig-review/act@4', askBatch: true, progress: true}` |
1294
1295
  | `AskBatchRequestV3` | `{schema, jobId, requestId, verb: 'ask-batch', expectedGeneration, idempotencyKey, publicationId, subjects}`, `subjects` 1–64 |
1295
1296
  | `AskBatchValueV3` | `{asks}`, where `asks[i]` answers `subjects[i]` |
1297
+ | `JobProgressRequestV3` | `{schema, jobId, requestId, verb: 'progress', seq, phase, text?, step?}` |
1298
+ | `JobProgressValueV3` | `{status, seq, at}`, where `status` is `'accepted'` or `'ignored'` |
1299
+ | `JobProgressV3` | `{seq, phase, text?, step?, at, generation}` |
1300
+ | `JobProgressLineV3` | `{type: 'progress', jobId, progress, now}`, where `progress` is `JobProgressV3` or `null` |
1301
+
1302
+ <a id="option-sets"></a>
1303
+
1304
+ An `option-set` publication carries 1 to 64 sets ([Review #1004](https://github.com/rig-c/review/issues/1004)). One set keeps the single encoding: `{kind, questionId, setId}`, no `sets`, no `optionSets`, and source bytes and `sourceHash` identical to the one-set source before #1004. Several sets name the first set in `questionId` and `setId` and list every set in order in `sets`. The reader's context declares exactly one `interview-picks` subject per set, in the same order; any other subject list refuses with the existing code. The retained source's singular `selection`, `optionSet` and `optionSetFile` name the first set, `selection.sets` repeats `sets`, and `optionSets` carries each set's own option-set identity and file. Each ask binds its own set: `ask` or `ask-batch` takes any declared set's subject, and a set the publication does not carry refuses `JOB_ASK_INVALID`. The asks of one publication are pending at the same time and none supersedes another; publishing a new head still supersedes every pending ask of the old one, and the [Review #1022](https://github.com/rig-c/review/issues/1022) replay rule is unchanged. Each answer finalizes one `interview-picks` act (`rig-review/act@4`) for its own set and leaves the other asks pending. At K ≥ 2 an act's `source` names that act's own set: `selection` is `{kind: 'option-set', questionId, setId, sets}` with this act's `questionId` and `setId` and `sets` unchanged, `optionSet` is `{id: <this setId>, sha256: <this set's sha256>}` and `optionSetFile` is this set's file binding. `subjects`, `optionSets` and `sourceHash` stay the publication's. To re-derive `sourceHash` from an act, put set 0 back into the singular fields (`selection.questionId`/`setId` from `sets[0]`, `optionSet` and `optionSetFile` from `optionSets[0]`) and digest that publication source. An act whose per-act fields disagree refuses `JOB_ACT_INVALID` by name: a `selection` set the publication does not carry (`act set <q>/<s> is not published`), an `optionSet` that is not that set's (`act optionSet does not name set <q>/<s>`), an `optionSetFile` that is not that set's file (`act optionSetFile is not the file of set <q>/<s>`), or a `value.questionId` other than `selection.questionId` (`value.questionId <q> is not the act set <q>/<s>`). A K ≥ 2 act in the publication encoding (singular fields on set 0) for any other set therefore refuses. One set's act is unchanged. Two subjects for one set refuse `JOB_OPTION_SET_DUPLICATE` (`two subjects for set <questionId>/<setId>`), a set named twice in `sets` refuses `JOB_OPTION_SET_DUPLICATE` (`set <questionId>/<setId> is named twice`), and a `sets` of one entry or with a first entry other than the first set refuses `JOB_REQUEST_INVALID`; none of them reads the publisher or moves the generation. On the owner page the sets share one question list with one "Submit review (n/K)" at its top, where n counts the sets that are answered or fully picked. Submit sends each picked, unsubmitted set through its own form, one act each; the other sets stay pending and on the page.
1296
1305
 
1297
1306
  <a id="ask-batch"></a>
1298
1307
 
1299
- `ask-batch` asks several subjects of the head record publication in one request ([Review #963](https://github.com/rig-c/review/issues/963)). Each subject is parsed exactly like the single `ask` subject, and a repeated subject refuses the batch. A package head refuses `JOB_REQUEST_INVALID`, a non-head publication refuses `JOB_ACT_SOURCE_STALE`, and zero or more than 64 subjects refuse `JOB_REQUEST_INVALID`. The existing 256 KiB body limit still applies. Review binds every subject, runs `verifyJobRecordSourceFresh` once for the batch (one `inventory` and one `retained` reader call) and validates each subject against that one fresh source. One immediate transaction then re-checks the head, the work root and the retained snapshot once and creates every ask. Each ask writes its own `pending` event and moves the generation by 1, so a batch of N moves it by N. The batch is all or none: any refusal creates no ask, no event and no generation change. A subject's refusal keeps its existing code and prefixes the message with `subjects[<i>]: `. A freshness refusal carries no index. One idempotency key replays the whole batch without reading the publisher again. Single `ask` and finalize are unchanged. A Create detects support through `capabilities.askBatch` in `next`, never by sending `ask-batch` and reading the refusal: an older Review answers the unknown verb with `JOB_REQUEST_INVALID`. In `JobCapabilitiesV3`, `recordPublication`, `recordActSchema` and `askBatch` describe the host rather than the current head: `ask-batch` applies only to a record-retained head publication and a package head refuses `JOB_REQUEST_INVALID`, so a consumer checks the publication's mode as well as the flag.
1308
+ `ask-batch` asks several subjects of the head record publication in one request ([Review #963](https://github.com/rig-c/review/issues/963)). Each subject is parsed exactly like the single `ask` subject, and a repeated subject refuses the batch. A package head refuses `JOB_REQUEST_INVALID`, a non-head publication refuses `JOB_ACT_SOURCE_STALE`, and zero or more than 64 subjects refuse `JOB_REQUEST_INVALID`. The existing 256 KiB body limit still applies. Review binds every subject, runs `verifyJobRecordSourceFresh` once for the batch (one `inventory` and one `retained` reader call) and validates each subject against that one fresh source. One immediate transaction then re-checks the head, the work root and the retained snapshot once and creates every ask. Each ask writes its own `pending` event and moves the generation by 1, so a batch of N moves it by N. The batch is all or none: any refusal creates no ask, no event and no generation change. A subject's refusal keeps its existing code and prefixes the message with `subjects[<i>]: `. A freshness refusal carries no index. One idempotency key replays the whole batch without reading the publisher again. The replay follows the same rule as a single `ask`: if any ask of the stored batch is no longer pending and has no finalized act, the replay refuses `JOB_ASK_SUPERSEDED` with the message prefixed by that ask's `subjects[<i>]: `. Single `ask` and finalize are unchanged. A Create detects support through `capabilities.askBatch` in `next`, never by sending `ask-batch` and reading the refusal: an older Review answers the unknown verb with `JOB_REQUEST_INVALID`. In `JobCapabilitiesV3`, `recordPublication`, `recordActSchema` and `askBatch` describe the host rather than the current head: `ask-batch` applies only to a record-retained head publication and a package head refuses `JOB_REQUEST_INVALID`, so a consumer checks the publication's mode as well as the flag.
1309
+
1310
+ <a id="job-progress"></a>
1311
+
1312
+ **Progress between publications.** A `rig-review/job-api@3` agent checks `capabilities.progress === true` in `next`, then sends `progress` through the existing agent-authenticated `POST /jobs/<jobId>/api`. Support applies before the first publication and with either publication kind on a V3 host. The closed request allows `seq` as a positive safe integer, `phase` as one of `ingest`, `build`, `measure`, `publish` or `other`, optional single-line `text` of at most 120 characters, and optional `step: {i, n}` with safe integers satisfying `1 ≤ i ≤ n ≤ 1000`. Text is agent-authored and displayed verbatim. The raw JSON body limit is 1,024 bytes for progress. Invalid shapes and this verb's bounds refuse `JOB_REQUEST_INVALID`, and a closed job refuses `JOB_CLOSED`. The shared transport still enforces its global body limit before parsing a verb.
1313
+
1314
+ The normal V3 reply envelope contains `value: {status, seq, at}`. Review supplies the ISO receipt time `at` and stores the latest progress with the current job generation. Sequences increase across the job's lifetime. A request with a sequence at or below the last accepted sequence returns `ignored` with that sequence and receipt time, including after a clear or restart. An accepted request replaces the slot without an event, generation increment or replay entry. A committed `publish`, `ask`, `ask-batch` or `close` clears the visible slot. A retry of a committed mutation leaves subsequent progress in place.
1315
+
1316
+ The V3 owner page's existing `GET /jobs/<jobId>/events` NDJSON stream emits a cursorless `JobProgressLineV3` with the current slot on connect. `progress` is `null` when the slot is empty, and `now` is ISO host time. While connected, progress writes are coalesced per job to at most one update per second, with the latest value delivered after the interval even if writes stop. Connect snapshots and clears associated with semantic events are delivered independently of that cadence. The trusted `subscribeJob` port, semantic `next` cursors and CLI continue to use only durable job events.
1300
1317
 
1301
1318
  The read-only official reader returns the six-key `RecordPublishedContext` with producer-sealed `parts`. `prepareJobRecordSource` runs `phase: 'inventory'` on the immutable source root (re-verifying `project.json` identity before and after each reader phase and before mapping generic reader failures so mid-read record movement reports `JOB_RECORD_MOVED` / `JOB_SOURCE_MISMATCH` rather than `JOB_RECORD_INCOMPLETE`) and retains the sorted, duplicate-free `inventory.files` closure into an owned snapshot (`project.json` within 8 MiB, at most 4,096 regular non-symlink files, 64 MiB per file and 256 MiB total bytes). It then calls `phase: 'retained'` on the snapshot root with `parts: inventory.parts` forwarded unchanged and requires `assertEqualRecordContexts(inventory, retainedContext)`. Before ask or finalize, `verifyJobRecordSourceFresh` re-runs `phase: 'inventory'`, rejects any `inventory.parts` drift against the originally sealed `retained.context.parts` (`JOB_SOURCE_MISMATCH` on ask and `JOB_ACT_SOURCE_STALE` on finalize) before invoking `phase: 'retained'`, and forwards the sealed `retained.context.parts` unchanged when equal; synchronous `store.update` commit re-verifies source and retained snapshot integrity before persisting. Missing reader or contract tokens (`CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`, `CREATE_PLAN_PUBLICATION_CONTRACT_UNAVAILABLE`) refuse with `JOB_SOURCE_UNRETAINABLE`, while named producer tokens (`JOB_RECORD_CLOSURE_INCOMPLETE`, `JOB_RECORD_PARTS_MISMATCH`, `JOB_RECORD_PARTS_LOCK_MISSING`) map to `JOB_RECORD_INCOMPLETE` on publish or ask and `JOB_ACT_SOURCE_STALE` on finalize.
1302
1319
 
@@ -1439,6 +1456,33 @@ require the signed extended contract. Owner-screen integration,
1439
1456
  EN/KO visual verification and later release serving have their own acceptance
1440
1457
  steps.
1441
1458
 
1459
+ <a id="plan-picture"></a>
1460
+
1461
+ ### Optional plan picture
1462
+
1463
+ A record-plan `PlanContext` may declare `planPicture: {path, sha256}`
1464
+ ([Review #983](https://github.com/rig-c/review/issues/983)): the picture the owner
1465
+ signs the plan against, such as the latest post render or take the record binds.
1466
+ It has exactly the keys `path` and `sha256`, and must equal an entry already in
1467
+ `files`. The path must name a raster image Review draws, by the package page-image
1468
+ rule: `.png`, `.jpg`, `.jpeg` or `.webp`. Option-set publications refuse it. Any
1469
+ violation refuses `JOB_SOURCE_MISMATCH` with detail `PLAN_PICTURE_INVALID`.
1470
+
1471
+ The retained `RecordSource` carries the same `planPicture`. The
1472
+ `rig-review-job-record-source/1` digest preimage appends it after `files` and any
1473
+ `checkpointEvidence`, so the picture binds `sourceHash` and instance identity. An
1474
+ absent declaration emits and hashes nothing: existing records parse and hash
1475
+ exactly as before. The publication-pinned route `api/plan-picture` streams that
1476
+ one sealed member through the existing sealed reference route, and is 404 for
1477
+ records without it. The owner page checks the bytes against the declared SHA-256
1478
+ before drawing.
1479
+
1480
+ On the record screen a declared `planPicture` ranks first: it is drawn in the main
1481
+ view's reference viewport, and Review neither walks to an earlier picture
1482
+ publication nor draws bound parts. Without it the picture choice is unchanged: the
1483
+ record's own rig, then an earlier picture publication, then bound parts, then a
1484
+ scene-context option set.
1485
+
1442
1486
  ### Sealed plan step text
1443
1487
 
1444
1488
  Both publication-pinned `api/review` responses append delivery-only `planText`
@@ -1446,15 +1490,24 @@ when the accepted source has a plan. The daemon authenticates `project.json`
1446
1490
  from that publication's retained snapshot against its record seal and existing
1447
1491
  `projectHash`, then projects `does`, `produces`, `bar` and `rests_on`.
1448
1492
 
1449
- The projected envelope has ordered keys `schema`, `record`, `status`, `steps`.
1450
- `schema` is `rig-review/job-plan-text@1`, `record` is `{path:"project.json",sha256}`,
1451
- and `status` is `projected`. Rows follow the accepted plan's exact id/hash order.
1452
- Each row has `id`, `hash`, optional `does`, `produces`, `bar`, `rests_on`, then
1453
- `issues`. Each field supplies exactly one value or an ordered
1454
- `{field,reason:"absent"|"invalid"|"limit"}` issue. Scalar values are strings and
1455
- `rests_on` is an ordered string array. Empty strings/arrays, whitespace, line
1456
- endings, Unicode form, duplicate references and array order are preserved.
1457
- Producer extras stay outside this display projection.
1493
+ The projected envelope has ordered keys `schema`, `record`, `status`, `steps`,
1494
+ and the additive optional key `questions` (present when at least one qualifying
1495
+ interview item exists). `schema` remains `rig-review/job-plan-text@1`, `record`
1496
+ is `{path:"project.json",sha256}`, and `status` is `projected`. Rows follow the
1497
+ accepted plan's exact id/hash order. Each row has `id`, `hash`, optional `does`,
1498
+ `produces`, `bar`, `rests_on`, then `issues`. Each field supplies exactly one
1499
+ value or an ordered `{field,reason:"absent"|"invalid"|"limit"}` issue. Scalar
1500
+ values are strings and `rests_on` is an ordered string array. Empty
1501
+ strings/arrays, whitespace, line endings, Unicode form, duplicate references and
1502
+ array order are preserved. When present, `questions` is an `id` → `text` string
1503
+ map collected from `interview.framing`, `interview.waypoints` and
1504
+ `interview.post.items` in that order (first entry wins per id), keeping only
1505
+ items whose `text` is a string and whose `id` is a non-empty string up to 128
1506
+ characters matching `/^[A-Za-z0-9][A-Za-z0-9._-]*$/` as the parser enforces. The
1507
+ UI uses `questions` only for `rests_on` entries that match no plan step,
1508
+ displaying the question's `text` with its `id` in `title` while step ids still
1509
+ resolve to their step and unmatched ids stay raw. Producer extras stay outside
1510
+ this display projection.
1458
1511
 
1459
1512
  D1 matches only accepted ids, preserving source order and existing checkpoint
1460
1513
  aliases (`planStepId ?? checkpointId`). D2 retains its existing whole-plan
@@ -1462,7 +1515,8 @@ count/ordered-id admission checks. Hashes are the producer's opaque accepted
1462
1515
  identities. The existing reader retains responsibility for their semantic value.
1463
1516
 
1464
1517
  The unavailable envelope has `schema`, `record` (or null),
1465
- `status:"unavailable"`, `reason`. Named reasons are
1518
+ `status:"unavailable"`, `reason`; `questions` is never present on the
1519
+ unavailable envelope. Named reasons are
1466
1520
  `PLAN_TEXT_RECORD_UNAVAILABLE`, `PLAN_TEXT_RECORD_UNSUPPORTED`,
1467
1521
  `PLAN_TEXT_STEPS_ABSENT`, `PLAN_TEXT_STEPS_INVALID`,
1468
1522
  `PLAN_TEXT_MAPPING_UNAVAILABLE` and `PLAN_TEXT_LIMIT`. The UI shows the named
@@ -1471,7 +1525,8 @@ their missing/invalid field labels. Existing act authority and historical
1471
1525
  metadata omission retain their fallback behavior.
1472
1526
 
1473
1527
  The server retains its 8 MiB project read bound. Display limits are 4,096 plan
1474
- steps, 4,096 `rests_on` entries and 512 KiB UTF-8 for `planText`. Whole owner
1528
+ steps, 4,096 `rests_on` entries and 512 KiB UTF-8 for the entire `planText`
1529
+ envelope (including `questions`). Whole owner
1475
1530
  metadata retains its 2 MiB bound. A small unavailable envelope replaces an
1476
1531
  oversized projection. If that envelope also exceeds the response budget, the
1477
1532
  server returns `JOB_BODY_LIMIT` with `PLAN_TEXT_LIMIT`. Values remain complete
@@ -1582,7 +1637,7 @@ option-set sources are excluded. Source capabilities remain consumer-owned.
1582
1637
  | `parts-verdict` | `verdict, comments` (`approved` or `changes-requested`) |
1583
1638
  | `review-verdict` | `stage, verdict, comments` (existing rig/direction/image stages and verdicts) |
1584
1639
  | `signoff` | `stage, decision, comments` (`approved`) |
1585
- | `reopen` | `stage, comments` (existing declared record plan subject) |
1640
+ | `reopen` | `stage, comments` (read only: old records parse, Review neither asks nor renders it) |
1586
1641
 
1587
1642
  The declared plan/source/selector and ask eligibility checks remain applicable.
1588
1643
  The browser never supplies authoritative checkpoint-to-plan mapping. A Parts
@@ -1685,7 +1740,8 @@ existing pin or restore path already carries:
1685
1740
  | `camera` | numeric camera `{space, center, zoom, viewport, visible}` | StageComment `camera` |
1686
1741
  | `frame` | `{index, basis}` (`producer` or `reference`) | StageComment `frame` (absent when time-only) |
1687
1742
 
1688
- Each key reuses the decoder of the shape it copies. A `reopen` act has no ask
1743
+ Each key reuses the decoder of the shape it copies. A `reopen` act is read only
1744
+ (old records parse, Review neither asks nor renders it) and has no ask
1689
1745
  subject, so its comments cannot carry `context.subject`.
1690
1746
 
1691
1747
  Starting in 4.8.0, the rig verdict writer takes top-level `context` from pinned
@@ -1787,3 +1843,60 @@ crop px and refuses the first op that does not replay by index. The API takes
1787
1843
  the edit and replay provenance without a Create-project argument or access
1788
1844
  to Review or Create storage. A mesh edit
1789
1845
  approves nothing. [HQ sign on Review #952](https://github.com/rig-c/review/issues/952#issuecomment-7001413869), [Parts #1159](https://github.com/rig-c/parts/issues/1159).
1846
+
1847
+ ### Chest landmarks on Request changes (act@9)
1848
+
1849
+ The trusted package `readPublished` adapter can return
1850
+ `JobPublishedContext.chestLandmarks` for a `rig` selector. Review exposes those
1851
+ rows as `publication.chestLandmarks` in the publication receipt and pinned
1852
+ display response. Each `JobPublishedChestLandmark` row has the edit shape below
1853
+ with one additional required field, `source.configHash`, the lowercase SHA-256
1854
+ of the exact producer config bytes. If the package declares a producer handoff,
1855
+ Review uses that config identity. Otherwise the reader declares the config in
1856
+ its existing `files` array. Review hashes the retained file and checks that
1857
+ `meshes[slot].contour.bust` matches the published `bust` spec, including which
1858
+ optional keys are present. Review also checks the attachment hash and stage
1859
+ frame against the retained model. A bad declaration refuses
1860
+ `JOB_SOURCE_MISMATCH` before publication. The seed and config hash enter the
1861
+ publication's `source.sourceHash`; a config-only change gets a new binding.
1862
+ Omit the field when the draft has no published spec. Only a seeded attachment
1863
+ can be edited in a job.
1864
+
1865
+ The UI sends `value.chestLandmarks`, an array of one to four exact
1866
+ `{edit, sha256}` rows. Both arrays sort by the UTF-16 string
1867
+ `skin/slot/attachment` and permit each identity tuple once. Each
1868
+ `JobChestLandmarkValue` edit carries:
1869
+
1870
+ - `slot`, `skin` and `attachment` as nonempty strings of up to 128 characters
1871
+ without control characters. These identify the supplying non-linked mesh in
1872
+ the displayed setup model. The chest carrier's slot is the Parts part name.
1873
+ - `basis: "setup"` and `source: {hash, frame: {width, height}}` using the same
1874
+ attachment hash and model stage binding as act@8.
1875
+ - `bust: {apex_r, apex_l, cleavage?, alpha?, clearance?, spacing?, bone_r?, bone_l?}`.
1876
+ Coordinates are finite `[x, y]` in setup-pose rig pixels, in the whole figure's
1877
+ frame with x right and y down. They lie on the 1/256-px grid inside the
1878
+ inclusive stage bounds. Alpha and spacing are positive finite numbers,
1879
+ clearance is finite, and bone names are 1–128 characters. An omitted
1880
+ cleavage stays omitted.
1881
+
1882
+ Each outer `sha256` hashes the complete canonical `edit` using the same
1883
+ canonical JSON rules as act@8. Review validates the act shape and digest,
1884
+ checks that the attachment was seeded, verifies the model and attachment
1885
+ hashes, and compares the frame with the retained stage. With all three points
1886
+ present, Review runs its clearance pre-check. Shape, frame, ineligible
1887
+ attachment and clearance refusals use `JOB_ACT_INVALID`. A stale model or
1888
+ attachment hash uses `JOB_ACT_SOURCE_STALE`. The request and delivery limits
1889
+ still apply. The producer validates the edit before rebuilding.
1890
+
1891
+ `rig-review/act@9` is a `review-verdict` at `stage: "rig-review"` with
1892
+ `verdict: "changes-requested"` and at least one chest edit. It can also carry
1893
+ `meshEdits` and @7 comment context. Its comments array can be empty. Mesh-only
1894
+ edits use @8, and verdicts without edits keep their existing schemas.
1895
+
1896
+ Consumers use the authorized finalized-act fetch and verify the act's
1897
+ `source.sourceHash`, `source.model.sha256`, the attachment SHA-256 and the
1898
+ frame before relaying landmarks to Parts. The publication carries the verified
1899
+ config hash, and the act binds to that publication through `source.sourceHash`.
1900
+ Parts checks the named slot is a contour part before writing the landmarks
1901
+ file. See [Review compatibility](STABILITY.md#chest-landmark-act-compatibility)
1902
+ and [Parts #1382](https://github.com/rig-c/parts/issues/1382).