@rig-c/review 4.10.0 → 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.
package/docs/DESIGN.md CHANGED
@@ -168,7 +168,7 @@ 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
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
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.
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
@@ -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.
@@ -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
@@ -1285,10 +1286,10 @@ A post-interview option set with a `rig` context can also show the accepted rig
1285
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
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) |
1288
- | `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
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, optional `optionSets` (`{questionId, setId, optionSet, optionSetFile}` per set) on several-set option-set sources |
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
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 |
@@ -1455,6 +1456,33 @@ require the signed extended contract. Owner-screen integration,
1455
1456
  EN/KO visual verification and later release serving have their own acceptance
1456
1457
  steps.
1457
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
+
1458
1486
  ### Sealed plan step text
1459
1487
 
1460
1488
  Both publication-pinned `api/review` responses append delivery-only `planText`
@@ -1462,15 +1490,24 @@ when the accepted source has a plan. The daemon authenticates `project.json`
1462
1490
  from that publication's retained snapshot against its record seal and existing
1463
1491
  `projectHash`, then projects `does`, `produces`, `bar` and `rests_on`.
1464
1492
 
1465
- The projected envelope has ordered keys `schema`, `record`, `status`, `steps`.
1466
- `schema` is `rig-review/job-plan-text@1`, `record` is `{path:"project.json",sha256}`,
1467
- and `status` is `projected`. Rows follow the accepted plan's exact id/hash order.
1468
- Each row has `id`, `hash`, optional `does`, `produces`, `bar`, `rests_on`, then
1469
- `issues`. Each field supplies exactly one value or an ordered
1470
- `{field,reason:"absent"|"invalid"|"limit"}` issue. Scalar values are strings and
1471
- `rests_on` is an ordered string array. Empty strings/arrays, whitespace, line
1472
- endings, Unicode form, duplicate references and array order are preserved.
1473
- 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.
1474
1511
 
1475
1512
  D1 matches only accepted ids, preserving source order and existing checkpoint
1476
1513
  aliases (`planStepId ?? checkpointId`). D2 retains its existing whole-plan
@@ -1478,7 +1515,8 @@ count/ordered-id admission checks. Hashes are the producer's opaque accepted
1478
1515
  identities. The existing reader retains responsibility for their semantic value.
1479
1516
 
1480
1517
  The unavailable envelope has `schema`, `record` (or null),
1481
- `status:"unavailable"`, `reason`. Named reasons are
1518
+ `status:"unavailable"`, `reason`; `questions` is never present on the
1519
+ unavailable envelope. Named reasons are
1482
1520
  `PLAN_TEXT_RECORD_UNAVAILABLE`, `PLAN_TEXT_RECORD_UNSUPPORTED`,
1483
1521
  `PLAN_TEXT_STEPS_ABSENT`, `PLAN_TEXT_STEPS_INVALID`,
1484
1522
  `PLAN_TEXT_MAPPING_UNAVAILABLE` and `PLAN_TEXT_LIMIT`. The UI shows the named
@@ -1487,7 +1525,8 @@ their missing/invalid field labels. Existing act authority and historical
1487
1525
  metadata omission retain their fallback behavior.
1488
1526
 
1489
1527
  The server retains its 8 MiB project read bound. Display limits are 4,096 plan
1490
- 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
1491
1530
  metadata retains its 2 MiB bound. A small unavailable envelope replaces an
1492
1531
  oversized projection. If that envelope also exceeds the response budget, the
1493
1532
  server returns `JOB_BODY_LIMIT` with `PLAN_TEXT_LIMIT`. Values remain complete
package/docs/STABILITY.md CHANGED
@@ -872,6 +872,16 @@ while `subjects`, `optionSets` and `sourceHash` stay the publication's; an act
872
872
  whose per-act fields disagree refuses `JOB_ACT_INVALID` by name. One set's act
873
873
  bytes are unchanged. No runtime or type export is added. See the [option-set contract](REVIEW_PACKAGE.md#option-sets).
874
874
 
875
+ ## Record plan picture
876
+
877
+ A record-plan publication context and its retained source may carry an optional
878
+ `planPicture: {path, sha256}` ([Review #983](https://github.com/rig-c/review/issues/983)):
879
+ one raster member of `files` that the record screen draws first. It is refused
880
+ on option sets and appended to the record digest only when present, so existing
881
+ sources keep their bytes and `sourceHash`. `PlanContext` and `PlanSource` gain the
882
+ optional field; no runtime export or error code is added. See the
883
+ [plan picture contract](REVIEW_PACKAGE.md#plan-picture).
884
+
875
885
  ## Package manifest `frames` declaration
876
886
 
877
887
  `rig-review/1` manifests accept an optional `frames` field beside `model`: a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "4.10.0",
3
+ "version": "4.11.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -31,15 +31,35 @@ export function clothPatchKind(ops: readonly Pick<PatchOp, 'path'>[]): 'cloth' |
31
31
  return n === 0 ? 'none' : n === ops.length ? 'cloth' : 'mixed';
32
32
  }
33
33
 
34
+ /** The producer package's typed export key for its cloth target list (#954, paired with rig-c/parts#1433). */
35
+ export const CLOTH_TARGETS_EXPORT = './cloth-targets.json';
36
+ /** The first `@rig-c/parts` release exporting `./cloth-targets.json` (rig-c/parts#1433). */
37
+ export const CLOTH_TARGETS_SINCE = '2.51.0';
38
+ /** The schema of `@rig-c/parts`' `./cloth-targets.json` export. */
39
+ export const CLOTH_TARGETS_SCHEMA = 'rig-parts/cloth-targets@1';
40
+ export const CLOTH_TARGETS_INVALID = 'CLOTH_TARGETS_INVALID';
41
+ export const CLOTH_TARGETS_UNAVAILABLE = 'CLOTH_TARGETS_UNAVAILABLE';
42
+ export const clothTargetsUnavailable = (version: string) => `${CLOTH_TARGETS_UNAVAILABLE}: the installed rig-parts ${version || 'unknown'} has no cloth-targets export (needs ${CLOTH_TARGETS_SINCE})`;
43
+
44
+ export class ClothTargetsError extends Error { constructor(detail: string) { super(`${CLOTH_TARGETS_INVALID}: ${detail}`); } }
45
+
46
+ /** The tags the config's own `cloth` block already declares. */
47
+ export function configClothTags(config: unknown): string[] {
48
+ const cloth = isObject(config) ? config.cloth : undefined;
49
+ return isObject(cloth) ? Object.keys(cloth).filter(k => k !== 'note' && !k.endsWith('_note') && !k.startsWith('x-')) : [];
50
+ }
51
+
34
52
  /**
35
- * The tags the installed reader accepts, read from its own source text (`export const CLOTH_TARGETS = [...]`), or null
36
- * when the text does not state them in that form.
53
+ * The tags the installed reader accepts, validated from its `./cloth-targets.json` export (`rig-parts/cloth-targets@1`).
37
54
  */
38
- export function readClothTargets(sourceText: string): string[] | null {
39
- const m = /export const CLOTH_TARGETS\s*=\s*\[([^\]]*)\]/.exec(sourceText);
40
- if (!m) return null;
41
- const tags = [...m[1]!.matchAll(/'([^']+)'|"([^"]+)"/g)].map(x => x[1] ?? x[2]!);
42
- return tags.length ? tags : null;
55
+ export function parseClothTargets(value: unknown): string[] {
56
+ if (!isObject(value) || value.schema !== CLOTH_TARGETS_SCHEMA || Object.keys(value).some(k => k !== 'schema' && k !== 'targets')) {
57
+ throw new ClothTargetsError(`expected {"schema":${JSON.stringify(CLOTH_TARGETS_SCHEMA)},"targets":[…]}`);
58
+ }
59
+ if (!Array.isArray(value.targets) || !value.targets.length) throw new ClothTargetsError('targets must be a non-empty array of strings');
60
+ const tags = value.targets.map(t => { if (typeof t !== 'string' || !t.trim()) throw new ClothTargetsError('targets must contain non-empty strings'); return t; });
61
+ if (new Set(tags).size !== tags.length) throw new ClothTargetsError('targets must be distinct');
62
+ return tags;
43
63
  }
44
64
 
45
65
  /** One recipe field the form edits: its pointer below `/cloth/<tag>` and how it is typed. The producer judges every value. */
package/src/job-api.ts CHANGED
@@ -1,4 +1,4 @@
1
- import {checkpointEvidenceFields} from './job-checkpoint-evidence.ts';
1
+ import {checkpointEvidenceFields, planPictureFields} from './job-checkpoint-evidence.ts';
2
2
  import {previousDraftFields} from './job-previous-draft.ts';
3
3
  import { createHash, timingSafeEqual } from 'node:crypto';
4
4
  import {
@@ -744,6 +744,7 @@ type ParsedRecordPayload =
744
744
  | {
745
745
  readonly kind: 'plan';
746
746
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
747
+ readonly planPicture?: JobFileIdentity;
747
748
  readonly inputs: readonly JobFileIdentity[];
748
749
  readonly files: readonly JobFileIdentity[];
749
750
  readonly plan: JobPlanIdentity;
@@ -761,14 +762,15 @@ function parseRecordClosureAndSubjects(
761
762
  ): ParsedRecordPayload {
762
763
  const { inputs, files } = parseFileClosure(rawInputs, rawFiles, checkedRecord, 'JOB_SOURCE_MISMATCH');
763
764
  if (selection.kind === 'option-set') {
764
- if (rawPlan !== null || 'checkpointEvidence' in evidenceHolder) throw new JobError('JOB_SOURCE_MISMATCH');
765
+ if (rawPlan !== null || 'checkpointEvidence' in evidenceHolder || 'planPicture' in evidenceHolder) throw new JobError('JOB_SOURCE_MISMATCH');
765
766
  const subjects = parseOptionSubjects(rawSubjects, selection, 'JOB_SOURCE_MISMATCH');
766
767
  return { kind: 'option-set', inputs, files, plan: null, subjects };
767
768
  }
768
769
  if (rawPlan === null) throw new JobError('JOB_SOURCE_MISMATCH');
769
770
  const { plan, stepIds } = parsePlanIdentity(rawPlan, 'JOB_SOURCE_MISMATCH');
770
771
  const subjects = parsePlanSubjects(rawSubjects, stepIds, 'JOB_SOURCE_MISMATCH');
771
- return { kind: 'plan', inputs, files, plan, subjects, ...checkpointEvidenceFields(evidenceHolder, plan, subjects, files) };
772
+ return { kind: 'plan', inputs, files, plan, subjects, ...checkpointEvidenceFields(evidenceHolder, plan, subjects, files),
773
+ ...planPictureFields(evidenceHolder, plan, files) };
772
774
  }
773
775
 
774
776
  export function parseRecordPublishedContext(
@@ -794,7 +796,7 @@ export function parseRecordPublishedContext(
794
796
  const selection = parseRecordResult(result);
795
797
  const checkedRecord = record === undefined ? undefined : parseProjectRecord(record, 'JOB_SOURCE_MISMATCH');
796
798
  if (value && typeof value === 'object') previousDraftFields(value, null);
797
- const item = exactObject(value, ['label', 'parts', 'inputs', 'files', 'plan', 'subjects'], 'JOB_SOURCE_MISMATCH', ['checkpointEvidence']);
799
+ const item = exactObject(value, ['label', 'parts', 'inputs', 'files', 'plan', 'subjects'], 'JOB_SOURCE_MISMATCH', ['checkpointEvidence', 'planPicture']);
798
800
  const label = asCode(() => jobText(item.label), 'JOB_SOURCE_MISMATCH');
799
801
  const parts = parseRecordPartsIdentity(item.parts, 'JOB_SOURCE_MISMATCH');
800
802
  const body = parseRecordClosureAndSubjects(
@@ -810,7 +812,8 @@ export function parseRecordPublishedContext(
810
812
  return { label, parts, inputs: body.inputs, files: body.files, plan: null, subjects: body.subjects };
811
813
  }
812
814
  return { label, parts, inputs: body.inputs, files: body.files, plan: body.plan, subjects: body.subjects,
813
- ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}) };
815
+ ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}),
816
+ ...(body.planPicture ? {planPicture: body.planPicture} : {}) };
814
817
  }
815
818
 
816
819
  export function assertEqualRecordContexts(
@@ -838,6 +841,7 @@ export function assertEqualRecordContexts(
838
841
 
839
842
  export interface RecordSourceDigestInput {
840
843
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
844
+ readonly planPicture?: JobFileIdentity;
841
845
  readonly schema?: typeof JOB_RECORD_SOURCE_SCHEMA;
842
846
  readonly sourceHash?: JobSha256;
843
847
  readonly projectHash?: JobSha256;
@@ -871,6 +875,7 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
871
875
  'files',
872
876
  'checkpointEvidence',
873
877
  'optionSets',
878
+ 'planPicture',
874
879
  ]),
875
880
  'JOB_SOURCE_MISMATCH',
876
881
  );
@@ -894,7 +899,7 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
894
899
  const { inputs, files, byPath } = parseFileClosure(item.inputs, item.files, record, 'JOB_SOURCE_MISMATCH');
895
900
 
896
901
  if (selection.kind === 'option-set') {
897
- if ('checkpointEvidence' in item || item.plan !== null || item.optionSet === null || item.optionSetFile === null) {
902
+ if ('checkpointEvidence' in item || 'planPicture' in item || item.plan !== null || item.optionSet === null || item.optionSetFile === null) {
898
903
  throw new JobError('JOB_SOURCE_MISMATCH');
899
904
  }
900
905
  const rawOptionSet = exactObject(item.optionSet, ['id', 'sha256'], 'JOB_SOURCE_MISMATCH');
@@ -944,6 +949,8 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
944
949
  subjects,
945
950
  files,
946
951
  ...checkpointEvidenceFields(item, plan, subjects, files),
952
+ // #983: last, and only when present, so a record without it keeps its source hash.
953
+ ...planPictureFields(item, plan, files),
947
954
  });
948
955
  }
949
956
 
@@ -1047,6 +1054,7 @@ function assembleRecordSource(
1047
1054
  subjects: body.subjects,
1048
1055
  files: body.files,
1049
1056
  ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}),
1057
+ ...(body.planPicture ? {planPicture: body.planPicture} : {}),
1050
1058
  });
1051
1059
  return {
1052
1060
  sourceHash,
@@ -1055,6 +1063,7 @@ function assembleRecordSource(
1055
1063
  inputs: body.inputs,
1056
1064
  files: body.files,
1057
1065
  ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}),
1066
+ ...(body.planPicture ? {planPicture: body.planPicture} : {}),
1058
1067
  subject: 'plan',
1059
1068
  selection: { kind: 'plan' },
1060
1069
  optionSet: null,
@@ -1104,6 +1113,7 @@ export function buildRecordSource(input: {
1104
1113
  plan: context.plan,
1105
1114
  subjects: context.subjects,
1106
1115
  ...(context.checkpointEvidence ? {checkpointEvidence: context.checkpointEvidence} : {}),
1116
+ ...(context.planPicture ? {planPicture: context.planPicture} : {}),
1107
1117
  };
1108
1118
  const sets = selection.kind === 'option-set' ? selection.sets : undefined;
1109
1119
  if ((sets === undefined) !== (input.optionSetFiles === undefined)) throw new JobError('JOB_SOURCE_MISMATCH');
@@ -1131,7 +1141,7 @@ export function parseRecordSource(value: unknown): RecordSource {
1131
1141
  'subjects',
1132
1142
  ],
1133
1143
  'JOB_SOURCE_MISMATCH',
1134
- ['checkpointEvidence', 'optionSets'],
1144
+ ['checkpointEvidence', 'optionSets', 'planPicture'],
1135
1145
  );
1136
1146
  const record = parseProjectRecord(item.record, 'JOB_SOURCE_MISMATCH');
1137
1147
  const projectHash = asCode(() => jobSha(item.projectHash), 'JOB_SOURCE_MISMATCH');
@@ -55,6 +55,23 @@ export function checkpointEvidenceFields(holder: object, plan: JobPlanIdentity |
55
55
  }
56
56
  }
57
57
 
58
+ /** #983: the plan-level picture the owner signs against. Plan records only; one sealed raster, by the
59
+ * package page-image rule (png, jpg, webp). Absence must not materialize the field. */
60
+ export function planPictureFields(holder: object, plan: JobPlanIdentity | null,
61
+ files: readonly JobFileIdentity[]): {planPicture?: JobFileIdentity} {
62
+ if (!('planPicture' in holder)) return {};
63
+ try {
64
+ if (!plan) throw new Error('plan only');
65
+ const raw = exactObject(holder.planPicture, ['path', 'sha256'], 'JOB_SOURCE_MISMATCH');
66
+ const planPicture = {path: jobPath(raw.path), sha256: jobSha(raw.sha256)};
67
+ if (!/\.(png|jpe?g|webp)$/i.test(planPicture.path) ||
68
+ !files.some(seal => seal.path === planPicture.path && seal.sha256 === planPicture.sha256)) throw new Error('closure');
69
+ return {planPicture};
70
+ } catch {
71
+ throw new JobError('JOB_SOURCE_MISMATCH', 'PLAN_PICTURE_INVALID');
72
+ }
73
+ }
74
+
58
75
  /** The sealed document is the sole table body. Preserve columns, rows and scalars. */
59
76
  export function parseCheckpointTable(bytes: Buffer): JobCheckpointTable {
60
77
  try {
@@ -353,6 +353,7 @@ export type JobPlanTextProjection = {
353
353
  readonly record: {readonly path: 'project.json'; readonly sha256: string};
354
354
  readonly status: 'projected';
355
355
  readonly steps: readonly JobPlanTextStep[];
356
+ readonly questions?: Readonly<Record<string, string>>;
356
357
  } | {
357
358
  readonly schema: typeof JOB_PLAN_TEXT_SCHEMA;
358
359
  readonly record: {readonly path: 'project.json'; readonly sha256: string} | null;
@@ -368,7 +369,7 @@ export function parseJobPlanTextProjection(value: unknown): JobPlanTextProjectio
368
369
  Object.keys(input).some(key => !keys.includes(key))) return fail();
369
370
  return input as Record<string, unknown>;
370
371
  };
371
- const envelope = object(value, ['schema', 'record', 'status', 'steps', 'reason']);
372
+ const envelope = object(value, ['schema', 'record', 'status', 'steps', 'questions', 'reason']);
372
373
  if (envelope.schema !== JOB_PLAN_TEXT_SCHEMA || !Object.hasOwn(envelope, 'record') ||
373
374
  new TextEncoder().encode(JSON.stringify(value)).length > 512 * 1024) return fail();
374
375
  if (envelope.record !== null) {
@@ -376,11 +377,17 @@ export function parseJobPlanTextProjection(value: unknown): JobPlanTextProjectio
376
377
  if (record.path !== 'project.json' || typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(record.sha256)) return fail();
377
378
  }
378
379
  if (envelope.status === 'unavailable') {
379
- if (Object.hasOwn(envelope, 'steps') || !(JOB_PLAN_TEXT_UNAVAILABLE as readonly unknown[]).includes(envelope.reason)) return fail();
380
+ if (Object.hasOwn(envelope, 'steps') || Object.hasOwn(envelope, 'questions') ||
381
+ !(JOB_PLAN_TEXT_UNAVAILABLE as readonly unknown[]).includes(envelope.reason)) return fail();
380
382
  return value as JobPlanTextProjection;
381
383
  }
382
384
  if (envelope.status !== 'projected' || envelope.record === null || Object.hasOwn(envelope, 'reason') ||
383
385
  !Array.isArray(envelope.steps) || envelope.steps.length > 4096) return fail();
386
+ if (Object.hasOwn(envelope, 'questions')) {
387
+ const questions = envelope.questions;
388
+ if (!questions || typeof questions !== 'object' || Array.isArray(questions) ||
389
+ Object.entries(questions).some(([id, text]) => !id || id.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) || typeof text !== 'string')) return fail();
390
+ }
384
391
  const ids = new Set<string>();
385
392
  for (const raw of envelope.steps) {
386
393
  const row = object(raw, ['id', 'hash', ...JOB_PLAN_TEXT_FIELDS, 'issues']);
@@ -1164,6 +1171,7 @@ export interface RecordContextBase {
1164
1171
 
1165
1172
  export type OptionContext = RecordContextBase & {
1166
1173
  readonly checkpointEvidence?: never;
1174
+ readonly planPicture?: never;
1167
1175
  readonly plan: null;
1168
1176
  /** One `interview-picks` subject per published set, in set order. */
1169
1177
  readonly subjects: readonly RecordPicksSubject[];
@@ -1171,6 +1179,8 @@ export type OptionContext = RecordContextBase & {
1171
1179
 
1172
1180
  export type PlanContext = RecordContextBase & {
1173
1181
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
1182
+ /** #983: the sealed raster (an entry of `files`) the owner signs the plan against; drawn first. */
1183
+ readonly planPicture?: JobFileIdentity;
1174
1184
  readonly plan: JobPlanIdentity;
1175
1185
  readonly subjects: readonly RecordPlanSubject[];
1176
1186
  };
@@ -1215,6 +1225,7 @@ export interface RecordSourceBase {
1215
1225
 
1216
1226
  export type OptionSource = RecordSourceBase & {
1217
1227
  readonly checkpointEvidence?: never;
1228
+ readonly planPicture?: never;
1218
1229
  readonly subject: 'option-set';
1219
1230
  readonly selection: RecordOptionResult;
1220
1231
  readonly optionSet: { readonly id: string; readonly sha256: JobSha256 };
@@ -1236,6 +1247,8 @@ export interface RecordOptionSetBinding {
1236
1247
 
1237
1248
  export type PlanSource = RecordSourceBase & {
1238
1249
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
1250
+ /** #983: equal to an entry of `files`; bound into `sourceHash` only when present. */
1251
+ readonly planPicture?: JobFileIdentity;
1239
1252
  readonly subject: 'plan';
1240
1253
  readonly selection: RecordPlanResult;
1241
1254
  readonly optionSet: null;
package/src/job-front.ts CHANGED
@@ -28,6 +28,26 @@ const headers = {
28
28
  'Referrer-Policy': 'no-referrer',
29
29
  'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self' blob:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
30
30
  };
31
+ /** #1050 cache policy. Every capability-bearing or computed response keeps `no-store` (`headers`).
32
+ * A sealed snapshot file is served only under its publication's instance route, whose publication id is new on every
33
+ * publish and whose instance key binds the source hash, and the seal refuses any other bytes: one URL, one content.
34
+ * `private` because the loopback server holds one user's work and no shared cache may keep it. */
35
+ const sealedHeaders = (sha256: string) => ({...headers, 'Cache-Control': 'private, max-age=31536000, immutable', ETag: `"${sha256}"`});
36
+ /** The shipped page files keep one URL across review upgrades: revalidate each load (the job liveness gate still runs). */
37
+ const resourceHashes = new WeakMap<object, string>();
38
+ async function shippedResource(request: Request, body: BodyInit, type: string): Promise<Response> {
39
+ // Bun's bundle is a BuildArtifact: Blob-like, not a Blob instance. Its hash is kept for the artifact's life.
40
+ const blob = typeof body === 'object' && 'arrayBuffer' in body && typeof body.arrayBuffer === 'function' ? body as {arrayBuffer(): Promise<ArrayBuffer>} : null;
41
+ let hash = blob ? resourceHashes.get(blob) : undefined;
42
+ if (!hash && (typeof body === 'string' || body instanceof Uint8Array || blob)) {
43
+ hash = jobHash(blob ? new Uint8Array(await blob.arrayBuffer()) : body as string | Uint8Array);
44
+ if (blob) resourceHashes.set(blob, hash);
45
+ }
46
+ const etag = hash ? `"${hash}"` : null;
47
+ const responseHeaders = {...headers, 'Content-Type': type, ...(etag ? {'Cache-Control': 'no-cache', ETag: etag} : {})};
48
+ if (etag && request.headers.get('if-none-match') === etag) return new Response(null, {status: 304, headers: responseHeaders});
49
+ return new Response(request.method === 'HEAD' ? null : body, {headers: responseHeaders});
50
+ }
31
51
  interface CropFailureDiagnostic {
32
52
  field: string;
33
53
  expected: string | number[];
@@ -206,9 +226,7 @@ export function createJobFront(options: {
206
226
  if (!name)
207
227
  return failure('JOB_REQUEST_INVALID', 404);
208
228
  const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'main.js' ? 'text/javascript' : 'text/css';
209
- return new Response(request.method === 'HEAD' ? null : await options.resource(name), {
210
- headers: { ...headers, 'Content-Type': type },
211
- });
229
+ return shippedResource(request, await options.resource(name), type);
212
230
  }
213
231
  return {
214
232
  fetch: fetchJob,
@@ -269,7 +287,9 @@ export function retainedPublicationRoutes(session: JobSession) {
269
287
  const file = await safeFile(retained.snapshotRoot, relativePath);
270
288
  if (literal !== undefined && literal !== file)
271
289
  return failure('JOB_SOURCE_UNRETAINABLE', 404);
272
- return serveReference(request, file, seal.sha256, headers);
290
+ const cached = sealedHeaders(seal.sha256);
291
+ if (request.headers.get('if-none-match') === cached.ETag) return new Response(null, {status: 304, headers: cached});
292
+ return serveReference(request, file, seal.sha256, cached);
273
293
  };
274
294
  const reviewMetadata = (review: ReviewPackage | null) => json({
275
295
  ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
@@ -325,6 +345,11 @@ export function retainedPublicationRoutes(session: JobSession) {
325
345
  return await sealedFile(member.path);
326
346
  }
327
347
  if (isRetainedRecordSource(retained)) {
348
+ // #983: the declared plan picture is an exact sealed member; no other file is reachable here.
349
+ if (path === 'api/plan-picture') {
350
+ const picture = retained.source.subject === 'plan' ? retained.source.planPicture : undefined;
351
+ return picture ? await sealedFile(picture.path) : failure('JOB_SOURCE_UNRETAINABLE', 404);
352
+ }
328
353
  // hasParts is projected only after validating the option's sealed draft closure.
329
354
  const question = retained.questions.find(question => question.hasParts);
330
355
  if (question && (path === 'api/stage-parts' || /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.test(path))) {
package/src/job-source.ts CHANGED
@@ -965,6 +965,12 @@ export function retainedRecordPainting(retained: JobRetainedRecordSource): Pick<
965
965
  return {ref: seal, name: posix.basename(seal.path)};
966
966
  }
967
967
 
968
+ const recordInterviewCollections = (interview: Record<string, unknown>) => [
969
+ [interview.framing, ['interview']],
970
+ [interview.waypoints, ['interview', 'rigging-interview']],
971
+ [asPlainObject(interview.post)?.items, ['post-interview']],
972
+ ] as const;
973
+
968
974
  /** Delivery-only projection through the existing retained record reader. */
969
975
  export function projectRetainedPlanText(retained: JobRetainedSourceV3): JobPlanTextProjection | undefined {
970
976
  const {source, record} = retained;
@@ -1024,7 +1030,20 @@ export function projectRetainedPlanText(retained: JobRetainedSourceV3): JobPlanT
1024
1030
  }
1025
1031
  return {id:step.id, hash:step.hash, ...fields, issues};
1026
1032
  });
1027
- const projection: JobPlanTextProjection = {schema:JOB_PLAN_TEXT_SCHEMA, record:identity, status:'projected', steps};
1033
+ const questions: Record<string, string> = {};
1034
+ const interview = asPlainObject(project.interview);
1035
+ if (interview) {
1036
+ for (const [items] of recordInterviewCollections(interview)) {
1037
+ for (const rawItem of Array.isArray(items) ? items : []) {
1038
+ const item = asPlainObject(rawItem);
1039
+ if (typeof item?.id === 'string' && item.id.length <= 128 && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(item.id) &&
1040
+ typeof item.text === 'string' && !Object.hasOwn(questions, item.id))
1041
+ questions[item.id] = item.text;
1042
+ }
1043
+ }
1044
+ }
1045
+ const projection: JobPlanTextProjection = {schema:JOB_PLAN_TEXT_SCHEMA, record:identity, status:'projected', steps,
1046
+ ...(Object.keys(questions).length ? {questions} : {})};
1028
1047
  return Buffer.byteLength(JSON.stringify(projection)) > 512 * 1024 ? unavailable('PLAN_TEXT_LIMIT') : projection;
1029
1048
  }
1030
1049
 
@@ -1068,11 +1087,7 @@ function decodeRetainedRecordProject(
1068
1087
  if (!interview) throw new JobError('JOB_SOURCE_MISMATCH');
1069
1088
  // #1004: one question per published set, in set order; one set keeps the original single-question result.
1070
1089
  const decodedSets = optionSetRefs(result).map(({ questionId, setId }) => {
1071
- const collections = [
1072
- [interview.framing, ['interview']],
1073
- [interview.waypoints, ['interview', 'rigging-interview']],
1074
- [asPlainObject(interview.post)?.items, ['post-interview']],
1075
- ] as const;
1090
+ const collections = recordInterviewCollections(interview);
1076
1091
  const matches: { readonly pending: unknown; readonly allowedStages: readonly string[] }[] = [];
1077
1092
  for (const [items, allowedStages] of collections) {
1078
1093
  if (items !== undefined && !Array.isArray(items)) throw new JobError('JOB_SOURCE_MISMATCH');
@@ -1725,9 +1740,11 @@ export function assertStoredCheckpointEvidence(retained: JobRetainedSourceV3): v
1725
1740
  if (isRetainedRecordSource(retained)) {
1726
1741
  if ('chestLandmarks' in retained) throw new JobError('JOB_SOURCE_MISMATCH');
1727
1742
  const parsed = parseRecordSource(retained.source);
1728
- if (!hasEvidence && !('checkpointEvidence' in retained.context) && !('previousDraft' in retained.context)) return;
1743
+ if (!hasEvidence && !('planPicture' in retained.source) && !('checkpointEvidence' in retained.context) &&
1744
+ !('planPicture' in retained.context) && !('previousDraft' in retained.context)) return;
1729
1745
  const context = parseRecordPublishedContext(retained.context, retained.result, retained.record);
1730
1746
  if (requestDigest(parsed.checkpointEvidence ?? null) !== requestDigest(context.checkpointEvidence ?? null) ||
1747
+ requestDigest(parsed.planPicture ?? null) !== requestDigest(context.planPicture ?? null) ||
1731
1748
  requestDigest(parsed.subjects) !== requestDigest(retained.subjects) ||
1732
1749
  requestDigest(parsed.files) !== requestDigest(retained.seals)) throw new JobError('JOB_SOURCE_MISMATCH');
1733
1750
  return;