rig-review 2.7.1 → 2.9.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.
@@ -22,7 +22,7 @@ is written), `--painting <png>` (the original painting), `--by <name>` (launch-o
22
22
 
23
23
  ## What it shows
24
24
 
25
- - **Every part on its own**, on a sentinel background (green, magenta, black, white or checker), at native scale with
25
+ - **Every part on its own**, on a checker background by default (green, magenta, black and white are also available), at native scale with
26
26
  Fit and exact **1:1**, cursor-anchored wheel zoom, pinch and drag pan in the shared rig/reference viewport pair. Sampling stays nearest-neighbour. **Alpha only** shows the alpha channel as grey (white is opaque).
27
27
  - **Footprints of parts in front** (parts mode): the alpha of every part later in `parts.json` whose box meets the
28
28
  selected part's box, placed by its rig box and tinted cyan at 50 %. Where the selected part has no pixel under its
@@ -97,11 +97,18 @@ The occlusion-coverage report (rig-c/parts#998) is not read yet; the footprint t
97
97
  Standalone sign-off uses saved files. The active Create and Parts cycle uses finalized acts through the
98
98
  [standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
99
99
 
100
- **Approve all** marks every pending part and available mesh clean, then saves an explicit approved sign-off. It preserves notes and existing clean outcomes; any flagged part or mesh refuses with `PARTS_APPROVE_ALL_FLAGGED` before changes are made. Individual approval remains available. `tests/parts-approve-all.test.ts` exercises the page action and unchanged verdict guard; `tests/parts-approve-all-browser.ts` checks the real save and refusal flows.
100
+ The shared workspace keeps pointed issues in the persistent **Issues** sidebar, including an empty state.
101
+ **Save sign-off** saves the current issue collection. An empty collection approves the inspection, and a
102
+ non-empty collection requests changes. The live job host submits the same issue collection through its
103
+ review dialog. Reviewer wording stays verbatim.
101
104
 
102
- Each item is **pending**, **clean** or **flagged** with a note (a note is optional on clean). **Save sign-off**
103
- writes `parts-review.json` beside `parts.json` (atlas mode: beside the model), or to `--verdict`.
104
- An unnamed save has the following `/2` shape.
105
+ Historically, **Approve all** marked every pending part and available mesh clean and saved an approved
106
+ sign-off. It preserved notes and existing clean outcomes, and refused flagged items with
107
+ `PARTS_APPROVE_ALL_FLAGGED`. Per-part approval and mesh outcomes belong to that historical UI and
108
+ `/1`–`/3` read compatibility. The existing `tests/parts-approve-all.test.ts` and
109
+ `tests/parts-approve-all-browser.ts` now exercise the shared mount and current issue-based save flows.
110
+
111
+ New saves write `schema: "rig-review-parts-verdict/4"` (`status: "approved"` when `issues` is empty, `"changes-requested"` when `issues` is non-empty, `issues: PartsIssue[]`, `updatedAt`, and optional `by`) to `parts-review.json` beside `parts.json` (atlas mode: beside the model), or to `--verdict`. In historical `/1`..`/3` saves, each item was **pending**, **clean** or **flagged** with a note (a note is optional on clean), and an unnamed historical `/2` save had the following shape (preserved on read):
105
112
 
106
113
  ```json
107
114
  {
@@ -126,12 +133,12 @@ An unnamed save has the following `/2` shape.
126
133
  - `source.sha256` is the SHA-256 of the UTF-8 lines `<path>\t<sha256>\n`, one per `source.files` entry, sorted by path
127
134
  bytewise. Review revalidates inspected inputs when reading a saved verdict.
128
135
  - `source.flags` lists the producer files the flags were read from; `parts.<name>.flags` the historical producer-attribution IDs defined above, not the classified sidebar count.
129
- - `status`: `approved` only when every part is clean; `changes-requested` only with at least one part flagged;
130
- otherwise `pending`.
136
+ - Historical `/2` `status` is `approved` when every part is clean, `changes-requested` with at least one
137
+ flagged part, and otherwise `pending`.
131
138
 
132
- Refusals, by name: `PARTS_VERDICT_MISSING_PART`, `PARTS_VERDICT_UNKNOWN_PART`, `PARTS_VERDICT_NOTE_REQUIRED`,
133
- `PARTS_VERDICT_NOT_CLEAN`, `PARTS_VERDICT_NOTHING_FLAGGED`, `PARTS_VERDICT_INVALID`, and `PARTS_VIEW_SOURCE_CHANGED`
134
- when a file changed after the view opened.
139
+ Historical per-part validation refusals include `PARTS_VERDICT_MISSING_PART`, `PARTS_VERDICT_UNKNOWN_PART`, `PARTS_VERDICT_NOTE_REQUIRED`,
140
+ `PARTS_VERDICT_NOT_CLEAN` and `PARTS_VERDICT_NOTHING_FLAGGED`. Current saves retain `PARTS_VERDICT_INVALID`
141
+ for invalid verdicts and `PARTS_VIEW_SOURCE_CHANGED` when an inspected file changes after opening.
135
142
 
136
143
  A verdict destination matching a protected part, producer report, rig/package input, model or atlas image is
137
144
  refused as `PARTS_VERDICT_INPUT_COLLISION`, including normalized paths, symbolic links and filesystem aliases.
@@ -170,17 +177,16 @@ no attribution authority. Opening and reading preserve the saved bytes.
170
177
  | --- | --- |
171
178
  | Legacy `rig-review-parts-verdict/1` or `/2` | `by: null`, including an ignored historical `by` extension |
172
179
  | Named `rig-review-parts-verdict/3` | Required nonblank `by`, preserved verbatim |
173
- | Explicit resave from an unnamed launch | New ordinary `/2` save with `by: null` on read, clearing the earlier name |
180
+ | Pointed-issue `rig-review-parts-verdict/4` | `issues: PartsIssue[]` (`rig-review-parts-comment/2`), optional nonblank `by` (`null` on CLI read when omitted) |
181
+ | Explicit resave from an unnamed launch | New `/4` save (historical `/2` before `/4`) with `by: null` on read, clearing the earlier name |
174
182
 
175
- Named `/3` keeps the existing verdict fields and adds required `by`. A missing, null, non-string or
176
- whitespace-only `/3` name refuses `PARTS_VERDICT_INVALID`. Older executables accepting only `/1` and `/2`
183
+ Named `/3` keeps the existing historical verdict fields and adds required `by`. Pointed-issue `/4` replaces the per-part outcome map with `issues` (`rig-review-parts-comment/2`) and optional `by`; historical `/1`, `/2` and `/3` saves that are `pending` or contain bare flagged part or mesh notes without a matching comment surface in the UI as read-only legacy verdicts (`PARTS_VERDICT_LEGACY_FORMAT`, `flaggedCount`) and preserve their historical `/1`..`/3` schema and `parts` map on `parts <input> --format json`. A missing, null, non-string or
184
+ whitespace-only `/3` (or present `/4`) name refuses `PARTS_VERDICT_INVALID`. Older executables accepting only `/1` and `/2`
177
185
  reject named `/3` with that refusal. This opt-in saved-format compatibility cost is part of the contract.
178
186
 
179
- Ordinary `parts <input> --format json` returns normalized `schema: "rig-review-parts-verdict/2"` with
180
- every existing field, including `mode`, `tool`, `source`, `status`, all per-part outcomes, notes and flags,
181
- available mesh outcomes and notes, `comments` and `updatedAt`. It adds root `by: string | null` and
187
+ Ordinary `parts <input> --format json` returns `schema: "rig-review-parts-verdict/4"` (`mode`, `tool`, `source`, `status`, `issues` with resolved `crop.path` and `nativeCrop.path`, and `updatedAt`) for `/4` saves and for historical `/1`..`/3` saves whose flags are all covered by pointed comments (or that are approved with no issues, where `/1` normalizes to `issues: []`), while historical `/1`..`/3` saves that are `pending` or carry bare flagged part or mesh notes retain their historical `schema` (`"rig-review-parts-verdict/1"`, `"/2"`, or `"/3"`), per-part outcomes, notes and flags, available mesh outcomes and notes, optional `comments`, `issues` and `updatedAt`. Every CLI JSON read adds root `by: string | null` and
182
188
  `savedFileSha256`, a 64-character lowercase hexadecimal SHA-256 of the exact saved bytes, including any
183
- final LF. Legacy reads retain their original byte digest and `/1` normalizes to empty comments.
189
+ final LF, retaining the original byte digest on legacy reads.
184
190
 
185
191
  The core, recorded name and digest derive from one validated saved-file snapshot, with current source
186
192
  and producer-flag checks. `source.sha256`, `source.files` and `source.flags` retain the inspected-input
@@ -230,13 +236,21 @@ Crash-proof exactly-once delivery requires an additional acknowledgment/replay p
230
236
  ## Mesh geometry
231
237
 
232
238
  In parts mode, a `rig.json` beside `parts.json` supplies optional mesh geometry;
233
- `--rig <file>` selects an explicit input instead. The per-part **mesh from
234
- rig.json UVs** toggle starts off. It draws edges and vertices over the sentinel
235
- background, and tints nontransparent art pixels pink when their centres lie
236
- outside every nondegenerate triangle (triangle boundaries count as covered).
237
- The mesh outcome has its own Pending / Clean / Flagged states and note; Flagged
238
- requires a note. Approval requires both part and mesh outcomes to be Clean.
239
- A part without a mesh has no mesh controls or outcome.
239
+ `--rig <file>` selects an explicit input instead. The workspace-wide **mesh from
240
+ rig.json UVs** toggle starts off and retains its setting across part selection, assembled view,
241
+ Overlay and Difference in both standalone and live job hosts. It draws edges and vertices for
242
+ visible mesh-bearing parts. The selected part also tints nontransparent art pixels pink when their
243
+ centres lie outside every nondegenerate triangle (triangle boundaries count as covered).
244
+ Other assembled meshes use reduced-opacity wire lines. The selected part's geometry panel names
245
+ unavailable geometry explicitly. A draft with no mesh geometry retains a **Mesh (none 0/n)** control
246
+ and an unavailable message. A mesh attachment that declares a plain-object `generator` without inline
247
+ `uvs` or `triangles` is accepted without reconstructing geometry. Its part raster renders normally
248
+ without a mesh overlay, the item reports `meshUnavailable: "PARTS_MESH_GENERATED"`, and the **Mesh
249
+ geometry** panel states `PARTS_MESH_GENERATED: No mesh geometry is available for this part.` Non-object
250
+ `generator` values or attachments combining `generator` with `uvs` or `triangles` still refuse by name.
251
+
252
+ Historical per-part mesh outcomes had Pending / Clean / Flagged states and a note. Flagged required a
253
+ note, and approval required clean part and mesh outcomes. These fields remain legacy read data.
240
254
 
241
255
  Image-space positions are `(u × width, v × height)` from each attachment's own
242
256
  UVs and dimensions, never reconstructed through bones or weights. The mesh's raster
@@ -257,8 +271,8 @@ not an exact recovery of the producer's original unrounded positions.
257
271
  Mode, vertex count, triangle count, `art_coverage` and `stray_cleared` are copied
258
272
  from the part's `mesh_report.json` row without recomputing them. Absent fields
259
273
  say **not reported**; faint islands remain in Producer flags. A report count may
260
- differ from the loaded geometry; it is the producer's reading. The verdict's
261
- `parts[name].mesh` contains `{outcome,note}` only for a mesh-bearing part.
274
+ differ from the loaded geometry. These are producer readings. Historical verdicts stored
275
+ `parts[name].mesh` as `{outcome,note}` only for a mesh-bearing part.
262
276
  `rig.json` and the loaded mesh report enter `source.files`, and the mesh report
263
277
  also remains in `source.flags`. Changes invalidate the saved sign-off. No rig
264
278
  means the existing parts view and verdict format remain unchanged.
@@ -289,27 +303,35 @@ The four-stage navigator preserves this entry and its explicit save behavior. Co
289
303
  ## Pointed parts comments
290
304
 
291
305
  **Comment · C (n)** uses the same capture toggle, dragged region, composer and pins as the rig stage.
292
- While capture is on, drag draws only a region; close the toggle to pan. Enter adds the comment;
293
- **Save sign-off** persists the verdict. Select a comment row or pin after reopening to restore its
294
- part, both cameras, background, alpha, footprints, mesh and painting comparison view. There is no frame, animation or slot
295
- placeholder in a parts comment. Atlas inspection remains read only for pointed comments.
296
-
297
- `rig-review-parts-verdict/2` adds `comments[]`; a `/1` file reads with an empty comment array.
298
- Each closed `rig-review-parts-comment/1` carries `id`, original reviewer `summary`, `part`,
299
- `imageHash` (SHA-256 of the original part PNG), `sourceHash` (the verdict source identity),
300
- `imageRegion`, `rigRegion`, `view`, `crop` and `nativeCrop`. `imageRegion` has integer native
301
- pixel edges snapped outward from the drag. `rigRegion` is exact placement plus that region,
306
+ The **Issues** list stays visible in the side panel while C opens or closes capture. While capture is
307
+ on, drag within the rig pane away from existing pins and controls to mark a region. Close capture to
308
+ pan. Enter adds the issue,
309
+ and **Save sign-off** persists the verdict. Escape cancels the composer or capture while the inline
310
+ list stays visible. Rows and pins use the same edit, delete and jump actions.
311
+
312
+ Select an issue row or pin after reopening to restore its item or assembled view, both cameras,
313
+ background, alpha, footprints, mesh and painting comparison. Atlas inspection remains read only for
314
+ pointed comments. Joined compiled Stage 1 refuses issue authoring with
315
+ `PARTS_JOINED_ISSUE_UNSUPPORTED` and directs the reviewer to the standing live job route. Its
316
+ zero-issue approval path remains available.
317
+
318
+ `rig-review-parts-verdict/4` stores `issues[]` of closed `rig-review-parts-comment/2` records (historical `rig-review-parts-verdict/2` and `/3` stored `comments[]` of `rig-review-parts-comment/1`; a historical `/1` verdict file reads with an empty array).
319
+ Each historical closed `rig-review-parts-comment/1` carries `id`, original reviewer `summary`, `part`,
320
+ `imageHash` (SHA-256 of the original part PNG), `sourceHash` (the verdict source identity, or the server-retained publication `sourceHash` when prepared in a live job),
321
+ `imageRegion`, `rigRegion`, `view`, `crop` and `nativeCrop`; `rig-review-parts-comment/2` generalizes `part` + `imageHash` to a non-empty unique `parts: [{name, imageHash}]` array and supports `view.mode: "item"` (requiring integer `imageRegion`, exact `rigRegion = placement(parts[0]) + imageRegion`, and server-cut `nativeCrop`) and `view.mode: "assembled"` (`imageRegion: null`, `nativeCrop: null`, and integer `rigRegion` fully contained within the union bounding box of `parts`). `imageRegion` has integer native
322
+ pixel edges snapped outward from the drag. In item mode, `rigRegion` is exact placement plus that region,
302
323
  including fractional placement; it is never rounded. `view.camera` records native scale,
303
324
  center and viewport extent, plus `cameraSync` and the actual `referenceCamera` (or null), alongside `background`, `alpha`, `footprints` and `mesh`. New comments add optional
304
325
  `view.comparison: {mode:"part"|"overlay", opacity:0..1}`; older comments omit it and restore the
305
326
  ordinary part view. Unknown modes/keys and out-of-range opacity refuse `PARTS_COMPARISON_INVALID`.
306
327
 
307
328
  The viewport `crop` comes from the shared displayed-pixel compositor and includes its mark.
308
- `nativeCrop` is cut on the server from the hash-bound original PNG, preserving all RGBA bytes,
309
- including alpha. Both use the common PNG validator/content-addressed store; paths are selected
310
- by the server. The native crop has no alpha-mask, background or zoom transform. The saved
311
- viewport crop includes its private inline PNG; exported JSON and issue Markdown replace it
312
- with a resolved file path and hash. Both exports name the part and both regions and crops.
329
+ In item mode, `nativeCrop` is cut on the server from the hash-bound original PNG, preserving all
330
+ RGBA bytes, including alpha. It has no alpha-mask, background or zoom transform. Assembled issues
331
+ retain their rig-space region and viewport crop, with `imageRegion` and `nativeCrop` both null.
332
+ Crops use the common PNG validator/content-addressed store and server-selected paths. The saved
333
+ viewport crop includes its private inline PNG. Exported JSON and issue Markdown resolve stored
334
+ crops to file paths and hashes and retain the referenced parts and regions.
313
335
 
314
336
  ```sh
315
337
  npx rig-review parts <out>/rig --painting painting.png
@@ -318,7 +340,7 @@ npx rig-review parts <out>/rig --painting painting.png --format issue
318
340
  ```
319
341
 
320
342
  The optional painting must be a PNG contained in the parts package (including symlink resolution),
321
- with a portable source path. Format, size and hash derive from one buffer read. Its original dimensions
343
+ with a portable source path. In the live job host, a painting loaded from a retained snapshot via `paintingRoot` must instead resolve inside that snapshot root and match its retained seal. Format, size and hash derive from one buffer read. Its original dimensions
322
344
  must satisfy `trunc(width × scale_rig_per_source) = rig_size[0]` and the equivalent height check
323
345
  (`PARTS_PAINTING_SIZE`); missing/invalid declared geometry refuses `PARTS_PAINTING_MAPPING`.
324
346
  The painting stays in `source.files` and the protected input set. Adding it to an older verdict changes
@@ -333,7 +355,7 @@ Both use the existing canvas host/camera/capture. The original source rectangle
333
355
  `(x × originalWidth/rigWidth, y × originalHeight/rigHeight, w × originalWidth/rigWidth,
334
356
  h × originalHeight/rigHeight)`, retaining fractional placement. Browser image interpolation displays
335
357
  this continuous rectangle; it does not reproduce the producer's resampling or claim native pixel equality.
336
- Alpha-only and mesh diagnostics are disabled in Overlay; front footprints remain available.
358
+ Overlay retains the global mesh setting and front footprints. Alpha-only applies to the ordinary part raster.
337
359
  Without a painting the comparison controls are absent and the reference pane names
338
360
  `PARTS_REFERENCE_UNAVAILABLE`. No comparison changes the verdict. These behaviors are guarded by
339
361
  `tests/parts-comparison.test.ts`; `tests/parts-overlay-browser.ts` separately exercises trusted input,
@@ -357,9 +379,13 @@ For real scaled evidence, `scripts/prepare-parts-overlay-demo.ts` fetches hash-v
357
379
  inputs at `ba99e403d4058fc1cfe40699bdcde8aaf00a90c0`, then runs explicitly installed `@rig-c/parts@2.17.0`
358
380
  assemble in a separate fixture directory. It is an evidence script, never an app action.
359
381
 
360
- **Difference remains absent** pending the producer-declared rig-space painting raster and
361
- [the waiting consumer #390](https://github.com/rig-c/review/issues/390). Review adds no producer resampler.
362
- Neither visual comparison nor opening a package supplies an approval.
382
+ The earlier visual-comparison release deferred Difference to
383
+ [consumer #390](https://github.com/rig-c/review/issues/390). The current producer-declared operand and
384
+ metric are documented under [Declared-grid Difference](#declared-grid-difference).
385
+
386
+ Hold **P** to show the original painting at full opacity in item or assembled view. Capture is
387
+ suspended during the hold. Releasing P, leaving the active mount, hiding the document or losing
388
+ window focus restores the inspection view. The hold is temporary inspection state.
363
389
 
364
390
  Parts native zoom ranges from `min(fit, 1)` to 16. Exact native 1 is always reachable for a valid,
365
391
  successfully rendered frame. **Fit** is
@@ -389,30 +415,41 @@ while the existing verdict cannot be revalidated. Real source/flag identity chan
389
415
  separate stale warning. `PARTS_PAINTING_OUTSIDE` and `PARTS_PAINTING_PNG` refuse external or non-PNG
390
416
  painting inputs. `tests/parts-comments.test.ts` covers these read and cross-encoding boundaries;
391
417
  `tests/parts-async-navigation.test.ts` guards reordered painting loads and actionable atlas clicks.
392
- A downstream create consumer must support verdict/2 before a review release can ship.
418
+ The historical verdict/2 rollout required downstream create read support before release.
393
419
 
394
420
  ### Assembled package
395
421
 
396
- **Assembled** toggles the existing rig/reference pair from the selected part to the declared
422
+ **Assembled** switches the existing rig/reference pair from the selected part to the declared
397
423
  `rig_size` canvas. Parts draw back to front in package order at their exact fractional rig-pixel
398
- placements. The checkbox beside each part controls assembly visibility only; the verdict remains
399
- per part. List rows occupy one line, with full part names available to assistive technology and on hover, separate source counts and the outcome badge. The former **Visible / 표시** caption is removed; the checkbox retains its per-part accessible name (`tests/parts-approve-all.test.ts`, with full-list geometry in `tests/parts-approve-all-browser.ts`). A tap selects the frontmost visible part with nonzero native source alpha, including
400
- through transparent holes; drags remain camera gestures. The selected part's alpha edge is a
401
- separate outline, outside the comparison raster. Background, alpha-only, Fit, 1:1 and the shared
402
- camera controls remain available. `tests/parts-assembly.test.ts` guards fractional placement,
403
- order controls, picking, hidden layers, separate outline pixels and per-part verdict invariance.
404
-
405
- With `--painting`, the reference pane and optional Overlay use the same whole-canvas visual
406
- mapping described above. No producer resampler, Difference or assembled verdict is added.
407
- Without painting the reference keeps `PARTS_REFERENCE_UNAVAILABLE`; atlas assembly is disabled
408
- because atlas regions carry no rig placement, and missing `rig_size` is named separately.
409
- Comments remain bound to individual original PNGs: switch out of assembly to capture one;
410
- restoring a saved comment returns to its individual part view. Assembly visibility is temporary
411
- inspection state and is never saved into a verdict or comment. `tests/parts-assembly-browser.ts`
412
- checks real EN/KO assembly/reference pixels against an independent browser draw after a
413
- base-vs-base control, tap/hole/hide selection, pan, camera preservation, background, alpha,
414
- verdict save and missing-input refusals. Existing `tests/parts-comparison.test.ts` and
415
- `tests/parts-comments.test.ts` retain the painting-size and protected-input guards.
424
+ placements. Each part's checkbox controls assembly visibility. A tap selects the frontmost visible
425
+ part with nonzero native alpha, including through transparent holes. Hover outlines that part and
426
+ shows its name. Double-click opens its individual view. Escape returns from an individual part to
427
+ assembly when comment capture or a draft does not own the key. Drags with capture off remain camera
428
+ gestures. Selected, hovered and issue-referenced outlines stay separate from the comparison raster.
429
+ Background, alpha-only, Fit, 1:1 and shared camera controls remain available.
430
+
431
+ The one-line part rows retain full accessible names and source counts. The historical outcome badge
432
+ and **Visible / 표시** caption belong to the earlier per-part sign-off UI. Existing
433
+ `tests/parts-assembly.test.ts` guards placement, ordering, alpha picking, hidden layers and outlines.
434
+
435
+ An assembled issue can span several parts. The composer autoattaches part-name chips by sampling
436
+ frontmost visible nontransparent art within the marked region. Review the chips and add or remove
437
+ visible parts as needed. At least one referenced part is required, and the rig-space region must
438
+ remain inside their combined bounding box. Editing chips or wording validates and prepares the
439
+ candidate through the same source-bound crop pipeline before replacing the existing issue. A rejected
440
+ edit preserves the existing issue. Restoring an issue restores assembled view and highlights its
441
+ referenced parts. Assembly visibility stays temporary and is excluded from saved issues and verdicts.
442
+
443
+ With `--painting`, the reference pane and Overlay use the same whole-canvas visual mapping described
444
+ above. Without painting the reference names `PARTS_REFERENCE_UNAVAILABLE`. Atlas assembly is disabled
445
+ because atlas regions carry no rig placement, and missing `rig_size` is named separately. Difference
446
+ uses the individual part view described below.
447
+
448
+ `tests/parts-assembly-browser.ts` covers EN/KO assembly/reference pixels against an independent browser
449
+ draw, alpha picking, hidden layers, pan and camera preservation. `tests/parts-comments-browser.ts`
450
+ covers assembled seam capture, chip edits, saved-view restoration, crop evidence and source immutability
451
+ in both languages. `tests/parts-mesh-browser.ts` covers the global mesh control and unavailable states.
452
+ The live job host's `tests/job-window-browser.ts` covers the same mount through submission and reconnect.
416
453
 
417
454
  ## Draft mesh correction connection
418
455
 
@@ -31,7 +31,7 @@ The CLI also accepts an existing output directory. It reads a root `review.json`
31
31
  }
32
32
  ```
33
33
 
34
- An optional `producer` block declares the producer handoff: `"producer": {"config": "rig/config.json", "parts": "rig/out", "source": "inputs/painting.png", "full": "inputs/full", "head": "inputs/head"}` (only `config` is required; `source` and `full` go together, `head` only with them; no other key). See *Producer handoff* below.
34
+ An optional `producer` block declares the producer handoff: `"producer": {"config": "rig/config.json", "parts": "rig/out", "source": "inputs/painting.png", "full": "inputs/full", "head": "inputs/head"}`. Only `config` is required, `source` may be declared alone, `full` requires `source`, and `head` requires `full`. See *Producer handoff* below. An optional `panels` block (`{"schema": "rig-review/panels@1", "left": ["parts.list"], "stage": ["parts.canvas"], "toolbar": ["parts.layers"], "side": ["parts.issues", "act.submit"]}`) declares the panel composition across the closed slots `left`, `stage`, `toolbar` and `side` (`stage.length === 1` and `side` ending with `"act.submit"`); malformed `panels` blocks refuse with `JOB_PANELS_INVALID` in `parsePanelComposition` and fall back to `panels: undefined` in `parseManifest`.
35
35
 
36
36
  The illustrative `look` animation in `axes` must also be declared in `animations`. Omit axes when no real angle animation exists. All animation identifiers name actual compiled-model animations; the frontend reports runtime load/lookup errors rather than inventing them. Metadata duration is optional; the player supplies actual duration.
37
37
 
@@ -149,7 +149,7 @@ The active compiled model supplies rig identity. Without one, a known root or un
149
149
  An Apply rebuilds through the installed producer from the files the inspected rig was built from: the producer config, its parts directory (`parts.json`, `parts/`) and the inspected rig directory `<parts>/rig/`. Review finds them in this order, first match wins, never by searching:
150
150
 
151
151
  1. **Declared on the command line**: `rig-review open <dir> --config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]`. `feedback` and `control` take the same flags so retrieval binds the same identity. Paths are resolved from the working directory and canonicalized; the worker and every reload read exactly those files.
152
- 2. **Declared in review.json**: the `producer` block, package-relative literal portable paths (no `..`, no absolute path, no encoding).
152
+ 2. **Declared in review.json**: the `producer` block, package-relative literal portable paths (no `..`, no absolute path, no encoding). Unlike the CLI `--source`/`--full` pair, `producer.source` may be declared without `producer.full`, while `full` still requires `source` and `head` requires `full`.
153
153
  3. **Discovered inside the opened folder**: `config.json`, then `rig/config.json`.
154
154
  4. **Discovered beside an opened `out/`**: `../config.json`. It is outside the opened folder, so the record says `"how": "discovered", "outside": true` and the editor bar says *discovered outside the opened folder*, with its path and SHA-256. This step runs only when the opened folder is named `out`, and only for a regular file there (a symlink is refused).
155
155
 
@@ -611,7 +611,7 @@ Browser players retain play's default DOM mode and default mesh backend. Rigid
611
611
  parts remain DOM images; a WebGL mesh label does not claim full-frame GL drawing.
612
612
  WebGL is requested by the published default, with Canvas2D as the supported mesh
613
613
  fallback. Accurate public actual-flush telemetry requires play 1.11.1 or later;
614
- this checkout consumes pinned 1.23.0. The consumer does not probe GL or inspect
614
+ this checkout consumes pinned 1.24.0. The consumer does not probe GL or inspect
615
615
  private renderer state. The separate Node strip exporter remains Canvas2D.
616
616
 
617
617
  The backend badge is sampled only after successful draw/frame calls. Fresh mesh
@@ -843,8 +843,7 @@ Stage comment capture refuses unrecorded authoring effects, by `COMMENT_UNAPPLIE
843
843
 
844
844
  ### Parts pointed evidence
845
845
 
846
- Pre-rig parts uses `rig-review-parts-verdict/2` and the closed `rig-review-parts-comment/1`;
847
- existing verdict/1 records read with no comments. This identity comes from the existing
846
+ Pre-rig parts saves `rig-review-parts-verdict/4` with pointed `issues` (`rig-review-parts-comment/2`, carrying `parts: [{name, imageHash}]` and item or assembled view geometry) while preserving historical `rig-review-parts-verdict/1`, `rig-review-parts-verdict/2`, `rig-review-parts-verdict/3` and `rig-review-parts-comment/1` records on read (existing verdict/1 records read with no issues, `/2` and `/3` records with only comment-backed flags convert to `/4`, and `/1`..`/3` records with bare flagged part or mesh notes surface as read-only legacy verdicts with `PARTS_VERDICT_LEGACY_FORMAT`). This identity comes from the existing
848
847
  parts verdict source digest and actual original PNG SHA-256, without a fabricated review
849
848
  manifest id, revision or compiled model. The rig's `rig-review-comment/1` schema stays closed.
850
849
  See [the parts contract and validation instruments](PARTS_VIEW.md#pointed-parts-comments).
@@ -1031,11 +1030,25 @@ Pre-cutoff currentness-only exceptions display `INTERVIEW_OPTIONS_SCENE_LEGACY`
1031
1030
  without blocking the legacy interview. Full scene image and registration checks
1032
1031
  remain producer checks.
1033
1032
 
1034
- The temporary [#555 gate](https://github.com/rig-c/review/issues/555) refuses
1035
- standing publication with `JOB_RECORD_INCOMPLETE` for scene answers, legacy
1036
- warnings or historical record issues before publication lookup or snapshot
1037
- writes. Named diagnostic carriage remains an unmet gate pending the signed
1038
- job API@2 contract. An editable current scene can proceed to publication lookup.
1033
+ [Review #555](https://github.com/rig-c/review/issues/555) carries scene
1034
+ interview history and legacy warnings through standing job publications under
1035
+ `JobPublication.interview` (`rig-review/job-interview@1`, `null` for non-Create
1036
+ packages) across `publish`, `next`, `readPublication` and the retained
1037
+ `/jobs/<jobId>/publications/<publicationId>/instances/<instanceKey>/api/interview`
1038
+ route. Every inspected `pending_options` row, choice-bound `answer`/`guide`/`history[i]`
1039
+ row and completed `answer.agent_decision` row is recorded in `interview.records`
1040
+ with its own evaluation timestamp (`evaluatedAt` for inspection rows, `answer.at`
1041
+ for answer rows, `decision.at` for completed decisions, and `at: null` with no
1042
+ currentness evaluation for covers-only decisions) and joined 1:1 by `(record, at)`
1043
+ to `interview.diagnostics` (`INTERVIEW_OPTIONS_STALE` error or
1044
+ `INTERVIEW_OPTIONS_SCENE_LEGACY` warning). Active editable option sets that fail
1045
+ currentness or codec checks still refuse standing publication with
1046
+ `JOB_RECORD_INCOMPLETE` before publication lookup or snapshot writes. Browser
1047
+ and unit probes over `tests/fixtures/scene-interview-551` alter the committed
1048
+ writer archives into explicit synthetic controls
1049
+ (`SYNTHETIC_CONTROL_OVER_WRITER_ARCHIVE`); committed writer archive provenance
1050
+ does not make an altered project a real-user scene (`REAL_USER_SCENE_PENDING`)
1051
+ or establish official Create writer acceptance.
1039
1052
 
1040
1053
  ## Live job contract
1041
1054
 
@@ -1130,7 +1143,7 @@ signatures and the host-owned integration example are in
1130
1143
  - **Five enabled kinds and two reserved disabled kinds.** `JOB_ENABLED_ACT_KINDS` enables `'interview-picks'`, `'checkpoint'`, `'parts-verdict'`, `'review-verdict'` and `'signoff'`. `JOB_RESERVED_ACT_KINDS` reserves `'described-correction'` and `'mesh-edit'`, which have no accepted value shape in this contract and refuse with `JOB_ACT_KIND_DISABLED`. `described-correction` awaits the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist. `mesh-edit` awaits the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze (proposal `6ff03ec9` discusses slot, attachment and skin identity, setup basis, vertex, triangle and hull counts and at most 300 closed `move`, `add`, `remove`, `edge` and `unedge` operations in crop pixels, while the exact attachment bytes behind `source.hash` and the canonical payload digest replacing `delta_sha256` remain unresolved and undefined in C3 as in C2, and UI drafts are never consumer acts).
1131
1144
  - **`interview-picks`.** `JobActValues['interview-picks']` carries `questionId`, ordered `selections` (`itemId`, `optionId`, nullable `otherText`) and `note`, with non-null `source.optionSet` (`id` and `sha256`).
1132
1145
  - **`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.
1133
- - **`parts-verdict`.** `JobActValues['parts-verdict']` carries `verdict` (`'pending'`, `'approved'` or `'changes-requested'`), `parts` (`partId`, `part` outcome and note, `mesh` outcome and note with `JobPartOutcome` as `'pending'`, `'clean'` or `'flagged'`) and `words`, requiring non-null `source.projectHash`, a `draft` selector and `source.parts`.
1146
+ - **`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`).
1134
1147
  - **`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. The HQ-approved #522 image branch uses `'image-review'`, `source.subject = "image-set"`, daemon-derived image identities, digest and duplicate groups, with `model` and `selector` absent. It retains the same human verdict act and supports optional name-bound image notes. [Image-set verdict extension](STABILITY.md#image-set-verdict-extension).
1135
1148
  - **`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.
1136
1149
  - **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.
@@ -1190,23 +1203,25 @@ The manifest and complete retained image rows enter the composite source hash. L
1190
1203
  - **Consumer deduplication and future in-process mesh consumption.** Consumer writers deduplicate `actId` before current-source checks, then validate each new source and atomically commit the writer result plus replay identity. Replaying an applied `actId` returns the existing record, while a new stale act refuses before mutation. Verdict, signoff and stage transition remain three separate consumer writes. Once `mesh-edit` is jointly frozen with [Parts #1159](https://github.com/rig-c/parts/issues/1159), Create will fetch a finalized mesh act and pass its typed value in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159), with Parts reading neither Review nor Create storage and taking no Create-project argument, while standalone `--delta` remains legacy outside this cycle.
1191
1204
  - **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_IMAGE_SET_UNSUPPORTED`, `JOB_IMAGE_SET_INVALID`, `JOB_IMAGE_SET_DUPLICATE_NAME`, `JOB_IMAGE_SET_DUPLICATE_PATH`, `JOB_IMAGE_SET_ROLE_INVALID`, `JOB_IMAGE_SET_PATH_REFUSED`, `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.
1192
1205
 
1193
- ### Preparatory model-free record contract and source seam
1206
+ ### Model-free record mode and source seam
1194
1207
 
1195
- `src/job-contract.ts`, `src/job-api.ts`, `src/job-source.ts` and `src/job-act.ts` define the preparatory implementation-stage contract, validators, snapshot retention and act-preparation seam for Review #561. Create #277 owns the landed public `readRecordPublished` export and `JOB_RECORD_READER_ID` (`rig-create/publication-reader/2`), while complete closure, path and `parts` conformance remains open in Create #286. [Review #561](https://github.com/rig-c/review/issues/561), [Create #277](https://github.com/rig-c/create/issues/277), [Create #286](https://github.com/rig-c/create/issues/286).
1208
+ <a id="preparatory-model-free-record-contract-and-source-seam"></a>
1196
1209
 
1197
- `JOB_API_SCHEMA` (`rig-review/job-api@2`), `JOB_ACT_SCHEMA` (`rig-review/act@2`), `JOB_CAPABILITIES` (`{imageSetVerdict: true}`) and the `@rig-c/review/job-host` facade exports keep their existing package-only default behavior. The normal host (`createJobHostPorts` and `JobSession`) parses `rig-review/job-api@2` requests and rejects `rig-review/job-api@3` or tagged record publish requests with HTTP 400 (`JOB_REQUEST_INVALID` / `JOB_API_SCHEMA_MISMATCH`), leaving generation and committed head unchanged. Runtime activation of the opted-in record mode remains gated on Review #563 shared store, session and front paths, Create #286 closure, path and `parts` conformance, Create #278 writer consumer fetch, ingest and freeze integration, and Review's actual fixture proof against the producer-landed Create #279 fixtures. [Review #563](https://github.com/rig-c/review/issues/563), [Create #286](https://github.com/rig-c/create/issues/286), [Create #278](https://github.com/rig-c/create/issues/278), [Create #279](https://github.com/rig-c/create/issues/279).
1210
+ `src/job-contract.ts`, `src/job-api.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-session.ts`, `src/job-front.ts`, `src/job-host.ts` and `web/job-session.ts` implement and export the active model-free record mode (`rig-review/job-api@3` and `rig-review/act@4`). When a host or session is started with `readRecordPublished` and a non-empty `recordReaderId` (`publicationMode: 'record-and-package'`), `createJobHostPorts` and `JobSession` serve `option-set`, `plan` and `package` publications, `ask`, `next` (`JOB_CAPABILITIES_V3`), `fetch-act` (`rig-review/act@4` for record acts alongside `rig-review/act@2` and `rig-review/act@3` for package acts) and `close` under `rig-review/job-api@3`. On the normal owner URL (`/jobs/<jobId>/?#cap=...`), `retainedPublicationRoutes` serves retained record publications without invoking `loadReview` or synthesizing a fake `manifest` or `source.package` (`api/review` returns `{recordSource, sourceHash, capabilities, feedbackCatalog: {slots: null}}`, and `api/interview` serves retained `option-set` questions and sealed option images), while `prepareJobInspection` and `createJobWindow` render model-free `option-set` and `plan` inspection panels and submit human decisions that finalize `rig-review/act@4` acts (preserving existing `JOB_VISUAL_UNAVAILABLE` / `MODEL_UNAVAILABLE` behavior for package publications). `@rig-c/review/job-host` exports `JOB_API_V3_SCHEMA`, `JOB_RECORD_ACT_SCHEMA`, `JOB_RECORD_READER_ID`, `parseRecordAct`, `prepareJobRecordAct`, `prepareJobRecordSource` and the V3/record type surface (`JobRecordAct`, `JobActV3`, `JobPlanSource`, `JobFetchActRequestV3`, `JobRecordHostHooks`, `JobDisplayPublicationV3`, `DisplayPublicationV3` and companion types). [Review #561](https://github.com/rig-c/review/issues/561), [Review #588](https://github.com/rig-c/review/issues/588), [Review #586](https://github.com/rig-c/review/issues/586).
1211
+
1212
+ `JOB_API_SCHEMA` (`rig-review/job-api@2`), `JOB_ACT_SCHEMA` (`rig-review/act@2`), `JOB_CAPABILITIES` (`{imageSetVerdict: true}`) and default hosts started without `readRecordPublished` (`publicationMode: 'package-only'`) preserve their existing package-only behavior and exact `job-ui/<jobId>.json` descriptor bytes, and reject `rig-review/job-api@3` or tagged record publish requests with HTTP 400 (`JOB_REQUEST_INVALID` / `JOB_API_SCHEMA_MISMATCH`), leaving generation and committed head unchanged. Host startup validates `readRecordPublished`, `recordReaderId` and `publicationMode` on cold start, ordinary reuse and strict `reuseOnly` attachment (`JOB_HOST_OPTION_ID_INVALID` on mismatched hook/ID pairing; `JOB_HOST_REUSE_MISMATCH` on `publicationMode`, `apiSchema`, `actSchema` or `recordReaderId` drift so a package-only listener and a record-mode listener or two different record readers never silently substitute for one another). Satisfied prerequisites are [Review #563](https://github.com/rig-c/review/issues/563) (closed), [Create #277](https://github.com/rig-c/create/issues/277) (closed), [Create #279](https://github.com/rig-c/create/issues/279) (closed), [Create #285](https://github.com/rig-c/create/issues/285) (closed), [Create #286](https://github.com/rig-c/create/issues/286) (closed) and the real Review EN/KO fixture loop proved in [Review #590](https://github.com/rig-c/review/issues/590). Remaining external and cross-repository gates are [Create #278](https://github.com/rig-c/create/issues/278) (open writer consumer fetch, ingest and freeze integration), [Create #317](https://github.com/rig-c/create/issues/317) (waiting on [Review #588](https://github.com/rig-c/review/issues/588) activation) and HQ exact-head sign-off.
1198
1213
 
1199
1214
  | Surface | Exact keys or closed values |
1200
1215
  | --- | --- |
1201
1216
  | `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
1202
1217
  | `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
1203
- | `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`) |
1218
+ | `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`), `{kind: 'reopen', stage}` |
1204
1219
  | `RecordPublishedContext` | `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']` |
1205
1220
  | `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
1206
1221
  | `RecordSource` | `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']` |
1207
1222
  | `rig-review-job-record-source/1` | `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']` |
1208
1223
  | `rig-review-job-record-instance/1` | `['schema', 'fingerprint', 'sourceHash']` |
1209
1224
 
1210
- The read-only official reader returns the six-key `RecordPublishedContext` with producer-sealed `parts`. `prepareJobRecordSource` runs `phase: 'inventory'` on the immutable source root 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. 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.
1225
+ 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.
1211
1226
 
1212
- `interview-picks` records carry `plan: null` and remain valid for source preparation, ask binding and `rig-review/act@4` preparation. An inspection-only plan record with `plan: {steps: []}` and `subjects: []` is valid for source preparation and freshness checks, while plan `checkpoint` and `signoff` ask binding and `rig-review/act@4` preparation require non-empty `plan.steps` and declared subjects (`JOB_ASK_INVALID` / `JOB_ACT_INVALID`). Focused unit tests use synthetic reader doubles and remain distinct from actual Create conformance.
1227
+ `interview-picks` records carry `plan: null` and remain valid for source preparation, ask binding and `rig-review/act@4` preparation. An inspection-only plan record with `plan: {steps: []}` and `subjects: []` is valid for source preparation and freshness checks, while plan `checkpoint` and `signoff` ask binding and `rig-review/act@4` preparation require non-empty `plan.steps` and declared subjects (`JOB_ASK_INVALID` / `JOB_ACT_INVALID`), and plan `reopen` ask binding and `rig-review/act@4` `{stage, words}` preparation require a declared `{kind: 'reopen', stage}` subject on a `plan` record source ([Review #586](https://github.com/rig-c/review/issues/586)). Focused unit tests cover synthetic reader doubles, normal owner URL model-free record inspection (`retainedPublicationRoutes` + `prepareJobInspection` + `createJobWindow`), and archive-backed reader-double evidence over extracted `2-rigging-answers.tar.gz` (`rig-review/job-api@3` and `rig-review/act@4` parsed by `parseRecordAct` using a local `readRecordPublished` reader double and synthetic parts integrity, distinct from official installed Create reader/consumer conformance under [Create #278](https://github.com/rig-c/create/issues/278) and [Create #317](https://github.com/rig-c/create/issues/317)).
package/docs/STABILITY.md CHANGED
@@ -77,6 +77,9 @@ interface JobSessionOptions {
77
77
  readonly reviewer: JobReviewerBinding;
78
78
  readonly readPublished?: JobPublicationReader;
79
79
  readonly partsEnumerator?: JobPartsEnumerator;
80
+ readonly publicationMode?: JobPublicationMode;
81
+ readonly readRecordPublished?: RecordPublicationReader;
82
+ readonly recordReaderId?: string;
80
83
  readonly afterSnapshot?: () => void | Promise<void>;
81
84
  readonly afterDirectorySync?: (path: string) => void;
82
85
  }
@@ -558,7 +561,7 @@ model binding nor a valid image-set binding uses `JOB_ASK_INVALID`.
558
561
 
559
562
  ## Named export inventory
560
563
 
561
- The backend rig-still extension retains the twelve runtime exports and `JOB_ACT_SCHEMA` at act@2. `JobAct` additionally includes `JobRigReviewAct` at act@3 with top-level `JobRigStill`. The facade adds type-only `JobLegacyAct`, `JobRigReviewAct`, `JobRigStill` and `JobRigCapture` exports, and Review #563 adds five type-only exports (`JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`, `JobHostAttachField` and `JobHostAttachFailure`) while keeping the twelve runtime exports unchanged. Existing API/store/reuse markers and ordinary/historical acts retain @2. The rig revision constant, transport limits and the internal `POST /jobs/<jobId>/host` helper remain internal to their modules. Consumer checks distinguish these act revisions as described in [Rig verdict still backend](REVIEW_PACKAGE.md#rig-verdict-still-backend).
564
+ The backend rig-still extension retains the original twelve runtime exports and `JOB_ACT_SCHEMA` at act@2. `JobAct` additionally includes `JobRigReviewAct` at act@3 with top-level `JobRigStill` and `JobPartsVerdictAct` at act@5 (`PartsVerdictValue` with pointed `issues` and `words`, while preserving `JobLegacyPartsVerdictValue` at act@2 for historical acts). The facade adds type-only `JobLegacyAct`, `JobRigReviewAct`, `JobPartsVerdictAct`, `JobLegacyPartsVerdictValue`, `PartsVerdictValue`, `JobPanelComposition`, `PanelComponent`, `JobRigStill` and `JobRigCapture` exports, [Review #563](https://github.com/rig-c/review/issues/563) adds five type-only exports (`JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`, `JobHostAttachField` and `JobHostAttachFailure`), and [Review #555](https://github.com/rig-c/review/issues/555) adds four type-only interview diagnostic exports (`JobInterviewJson`, `JobInterviewRecord`, `JobInterviewDiagnostic` and `JobInterviewDiagnostics`). [Review #588](https://github.com/rig-c/review/issues/588) activates record mode when `readRecordPublished` and `recordReaderId` are supplied to a host or session (`publicationMode: 'record-and-package'`), serving `rig-review/job-api@3` (`JOB_API_V3_SCHEMA`), `rig-review/act@4` (`JOB_RECORD_ACT_SCHEMA`) and normal owner URL model-free record inspection while keeping default package-only hosts and exact `package-only` `job-ui/<jobId>.json` descriptor bytes at @2 and enforcing `publicationMode` / `recordReaderId` reuse compatibility across ordinary reuse and strict `reuseOnly` attachment. It exports six additional record-mode runtime symbols (`JOB_API_V3_SCHEMA`, `JOB_RECORD_ACT_SCHEMA`, `JOB_RECORD_READER_ID`, `parseRecordAct`, `prepareJobRecordAct` and `prepareJobRecordSource`, for eighteen runtime exports total) and the V3/record type surface listed below. The rig and parts-verdict act revision constants, transport limits and the internal `POST /jobs/<jobId>/host` helper remain internal to their modules. Consumer checks distinguish these act revisions as described in [Rig verdict still backend](REVIEW_PACKAGE.md#rig-verdict-still-backend) and [Model-free record mode and source seam](REVIEW_PACKAGE.md#model-free-record-mode-and-source-seam).
562
565
 
563
566
  The exact runtime exports are listed below. Constants preserve their literal
564
567
  values from the frozen semantic contract.
@@ -566,9 +569,15 @@ values from the frozen semantic contract.
566
569
  - `startJobHost`
567
570
  - `startJobHub`
568
571
  - `assertJobImageSetCapability`
572
+ - `parseRecordAct`
573
+ - `prepareJobRecordAct`
574
+ - `prepareJobRecordSource`
569
575
  - `JOB_CAPABILITIES`
570
576
  - `JOB_API_SCHEMA`
577
+ - `JOB_API_V3_SCHEMA`
571
578
  - `JOB_ACT_SCHEMA`
579
+ - `JOB_RECORD_ACT_SCHEMA`
580
+ - `JOB_RECORD_READER_ID`
572
581
  - `JOB_PARTS_ENUMERATOR_RANGE`
573
582
  - `JOB_ENABLED_ACT_KINDS`
574
583
  - `JOB_RESERVED_ACT_KINDS`
@@ -577,7 +586,7 @@ values from the frozen semantic contract.
577
586
  - `JOB_ERROR_CODES`
578
587
 
579
588
  The exact type-only exports follow. Their existing definitions in
580
- `src/job-contract.ts`, `src/job-source.ts`, `src/job-session.ts`,
589
+ `src/job-contract.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-session.ts`,
581
590
  `src/job-worker.ts`, `src/job-front.ts` and `src/job-hub.ts` are reexported
582
591
  without aliases or copied wire shapes.
583
592
 
@@ -622,6 +631,7 @@ without aliases or copied wire shapes.
622
631
  - `JobImageSetInput`
623
632
  - `JobImageSet`
624
633
  - `JobCapabilities`
634
+ - `JobCapabilitiesV3`
625
635
  - `JobModelReviewValue`
626
636
  - `JobImageReviewValue`
627
637
  - `JobReviewerBinding`
@@ -629,33 +639,101 @@ without aliases or copied wire shapes.
629
639
  - `JobVerdict`
630
640
  - `JobPartOutcome`
631
641
  - `JobReviewStage`
642
+ - `JobLegacyAct`
643
+ - `JobRigReviewAct`
644
+ - `JobPartsVerdictAct`
645
+ - `JobLegacyPartsVerdictValue`
646
+ - `PartsVerdictValue`
647
+ - `JobPanelComposition`
648
+ - `PanelComponent`
649
+ - `JobRigStill`
650
+ - `JobRigCapture`
632
651
  - `JobActValues`
633
652
  - `JobUIActValues`
634
653
  - `JobActSources`
635
654
  - `JobAct`
655
+ - `JobRecordAct`
656
+ - `JobActV3`
636
657
  - `JobSubject`
658
+ - `JobRecordSubject`
637
659
  - `JobPendingAsk`
660
+ - `JobPendingAskV3`
661
+ - `JobInterviewJson`
662
+ - `JobInterviewRecord`
663
+ - `JobInterviewDiagnostic`
664
+ - `JobInterviewDiagnostics`
638
665
  - `JobPublication`
666
+ - `JobPublicationV3`
639
667
  - `JobStatus`
668
+ - `JobStatusV3`
640
669
  - `JobPublishRequest`
670
+ - `JobPublishRequestV3`
671
+ - `JobPublishResultV3`
641
672
  - `JobAskRequest`
673
+ - `JobAskRequestV3`
642
674
  - `JobNextRequest`
675
+ - `JobNextRequestV3`
643
676
  - `JobCloseRequest`
677
+ - `JobCloseRequestV3`
644
678
  - `JobAgentRequest`
679
+ - `JobAgentRequestV3`
645
680
  - `JobFetchActRequest`
681
+ - `JobFetchActRequestV3`
646
682
  - `JobErrorCode`
647
683
  - `JobFailure`
648
684
  - `JobResult`
649
685
  - `JobEvent`
686
+ - `JobEventV3`
650
687
  - `JobNextValue`
688
+ - `JobNextValueV3`
651
689
  - `JobResponseValues`
690
+ - `JobResponseValuesV3`
652
691
  - `JobApiResponse`
692
+ - `JobApiResponseV3`
653
693
  - `JobUISubmission`
694
+ - `JobUISubmissionV3`
654
695
  - `JobDisplayAcknowledgment`
655
696
  - `JobDisplayReceipt`
656
697
  - `JobDisplayPublication`
698
+ - `JobDisplayPublicationV3`
699
+ - `DisplayPublicationV3`
657
700
  - `JobHostPorts`
658
701
  - `JobConsumerGrant`
702
+ - `JobPublicationMode`
703
+ - `JobRecordHostHooks`
704
+ - `JobProjectRecord`
705
+ - `JobRecordFreeze`
706
+ - `JobRecordOptionResult`
707
+ - `JobRecordPlanResult`
708
+ - `JobRecordResult`
709
+ - `JobRecordPartsIdentity`
710
+ - `JobRecordActKind`
711
+ - `JobRecordSignoffStage`
712
+ - `JobRecordPicksSubject`
713
+ - `JobRecordCheckpointSubject`
714
+ - `JobRecordSignoffSubject`
715
+ - `JobRecordReopenSubject`
716
+ - `JobRecordPlanSubject`
717
+ - `JobRecordSubject`
718
+ - `JobRecordContextBase`
719
+ - `JobOptionContext`
720
+ - `JobPlanContext`
721
+ - `JobRecordPublishedContext`
722
+ - `JobRecordReaderInput`
723
+ - `JobRecordPublicationReader`
724
+ - `JobRecordSourceBase`
725
+ - `JobOptionSource`
726
+ - `JobPlanSource`
727
+ - `JobRecordSource`
728
+ - `JobSourceV3`
729
+ - `JobRecordSignoffValue`
730
+ - `JobRecordReopenValue`
731
+ - `JobRecordUIActValues`
732
+ - `JobRecordUISubmission`
733
+ - `JobRetainedRecordSource`
734
+ - `JobRetainedSource`
735
+ - `JobRetainedSourceV3`
736
+ - `JobRootIdentity`
659
737
 
660
738
  ## Parts enumeration boundary
661
739
 
@@ -668,9 +746,12 @@ Rows are capped at 4096, roles at 128 UTF-16 code units and literal paths at 409
668
746
  ## Installed acceptance
669
747
 
670
748
  `bun run smoke` packs the package and installs that tarball into an empty project.
671
- A consumer imports the twelve runtime exports and every listed type, including
749
+ A consumer imports the eighteen runtime exports and every listed type, including
672
750
  `JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`,
673
- `JobHostAttachField` and `JobHostAttachFailure`, through `@rig-c/review/job-host`.
751
+ `JobHostAttachField`, `JobHostAttachFailure`, `JobInterviewJson`,
752
+ `JobInterviewRecord`, `JobInterviewDiagnostic`, `JobInterviewDiagnostics` and
753
+ the record-mode `JobRecordAct` / `JobActV3` / `JobPlanSource` /
754
+ `JobFetchActRequestV3` / `JobRecordHostHooks` surface, through `@rig-c/review/job-host`.
674
755
  TypeScript checks the installed consumer and the runtime checks the full owner
675
756
  resources, retained publication, semantic ports, declared hooks, enumerator
676
757
  version/row carriage, ordinary reuse, strict `reuseOnly: {expected}` attachment