@rig-c/review 3.7.0 → 4.0.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/README.md +1 -1
- package/docs/DESIGN.md +145 -74
- package/docs/PANELS.md +20 -12
- package/docs/PARTS_VIEW.md +133 -76
- package/docs/REVIEW_PACKAGE.md +445 -99
- package/docs/STABILITY.md +132 -198
- package/docs/WORKFLOWS.md +41 -120
- package/package.json +4 -3
- package/skills/rig-review/SKILL.md +41 -27
- package/src/build.ts +10 -2
- package/src/cli.ts +17 -16
- package/src/comment-crops.ts +6 -1
- package/src/compare-html.ts +22 -24
- package/src/compare-server.ts +1 -1
- package/src/compare-session.ts +41 -3
- package/src/correction-handoff.ts +27 -4
- package/src/create-pin-gate.ts +3 -0
- package/src/direction-inspection.ts +6 -2
- package/src/feedback-export.ts +68 -1
- package/src/front.ts +5 -200
- package/src/handoff.ts +1 -1
- package/src/interview-routes.ts +1 -1
- package/src/interview-scene.ts +3 -3
- package/src/job-act.ts +77 -73
- package/src/job-api.ts +326 -13
- package/src/job-checkpoint-evidence.ts +113 -0
- package/src/job-cli.ts +27 -14
- package/src/job-contract.ts +284 -62
- package/src/job-front.ts +157 -58
- package/src/job-host.ts +23 -4
- package/src/job-session.ts +109 -24
- package/src/job-source.ts +209 -57
- package/src/job-store.ts +80 -6
- package/src/job-worker.ts +1 -47
- package/src/joined-project.ts +61 -4
- package/src/manifest.ts +32 -4
- package/src/open-workspace.ts +12 -12
- package/src/open.ts +19 -12
- package/src/parts-comment-crops.ts +126 -31
- package/src/parts-comment.ts +351 -28
- package/src/parts-server.ts +19 -7
- package/src/parts-view.ts +588 -109
- package/src/scene-inspection.ts +50 -0
- package/src/server.ts +31 -22
- package/src/session.ts +58 -0
- package/src/stage-comment.ts +48 -1
- package/src/stage-parts.ts +23 -11
- package/web/animation-inspection.ts +1 -1
- package/web/bones-panel.ts +1 -3
- package/web/catalog-en.ts +175 -39
- package/web/catalog-ko.ts +175 -39
- package/web/cloth-panel.ts +1 -2
- package/web/compare.css +3 -13
- package/web/compare.html +3 -3
- package/web/compare.ts +69 -64
- package/web/cuts-panel.ts +1 -3
- package/web/density-strip-panel.ts +1 -2
- package/web/direction-panel.ts +22 -6
- package/web/i18n.ts +13 -1
- package/web/idle-panel.ts +1 -2
- package/web/index.html +1 -5
- package/web/inspection-persistence.ts +2 -1
- package/web/inspector-blocks.ts +149 -40
- package/web/instance-access.ts +24 -5
- package/web/interview-panel.ts +224 -175
- package/web/job-rig-capture.ts +164 -21
- package/web/job-rig-screen.ts +337 -0
- package/web/job-session.ts +611 -1437
- package/web/main.ts +614 -151
- package/web/mesh-panel.ts +1 -2
- package/web/owner-workspace.ts +88 -109
- package/web/part-selection.ts +47 -6
- package/web/part-thumbnails.ts +20 -6
- package/web/parts-render.ts +26 -19
- package/web/parts-viewport-provider.ts +181 -7
- package/web/physics-panel.ts +1 -2
- package/web/readings-panel.ts +1 -2
- package/web/requirements-panel.ts +1 -3
- package/web/retained-frame-stage.ts +105 -0
- package/web/retarget-panel.ts +2 -3
- package/web/rig-fields-panel.ts +1 -2
- package/web/rig-host.ts +64 -0
- package/web/rig-viewport-provider.ts +65 -16
- package/web/scene-plates.ts +57 -4
- package/web/stage-comments.ts +103 -46
- package/web/styles.css +117 -63
- package/web/view-controls.ts +201 -12
- package/web/viewport-capture.ts +12 -2
- package/web/viewport-controller.ts +107 -27
- package/web/viewport-pair.ts +2 -1
- package/web/workspace-preferences.ts +5 -4
- package/web/workspace-ui.ts +151 -19
- package/src/front-worker.ts +0 -2
- package/src/interview-server.ts +0 -54
- package/src/job-hub.ts +0 -304
- package/src/job-image-set.ts +0 -50
- package/web/interview.css +0 -28
- package/web/interview.html +0 -17
- package/web/interview.ts +0 -40
- package/web/job-hub.css +0 -14
- package/web/job-hub.html +0 -5
- package/web/job-hub.ts +0 -179
- package/web/owner-workspace.css +0 -14
- package/web/owner-workspace.html +0 -5
- package/web/parts-flags.ts +0 -48
- package/web/parts.css +0 -104
- package/web/parts.html +0 -49
- package/web/parts.ts +0 -604
- package/web/stage-nav.ts +0 -136
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -31,13 +31,13 @@ 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"}
|
|
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
|
|
|
38
38
|
## Files and references
|
|
39
39
|
|
|
40
|
-
Every path is a literal relative path, including `model`, optional `direction` and `sets`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
|
|
40
|
+
Every path is a literal relative path, including `model`, optional `direction`, `scene` and `sets`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
|
|
41
41
|
|
|
42
42
|
`model` is optional and must point to `rigc-compiled/3` under a filename ending `.model.json`, produced by an upstream gated rigc build. Review uses the public `@rig-c/play` loader and player; Spine JSON/skel is not its input. Its pages are resolved relative to the model document. Missing model means unavailable playback, never a mock playback success. The optional `sets` path declares an attachment-set sidecar for single-package playback. Without that declaration, attachment presets are unavailable. See [Direction inspection](#direction-inspection).
|
|
43
43
|
|
|
@@ -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
|
|
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,12 +843,37 @@ Stage comment capture refuses unrecorded authoring effects, by `COMMENT_UNAPPLIE
|
|
|
843
843
|
|
|
844
844
|
### Parts pointed evidence
|
|
845
845
|
|
|
846
|
-
Pre-rig parts
|
|
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).
|
|
851
850
|
|
|
851
|
+
### Interview-stage project subject
|
|
852
|
+
|
|
853
|
+
`rig-review open <project-root> --project <project-root> --picks-dir <dir>`
|
|
854
|
+
opens an interview-stage Create project before a draft or recorded review
|
|
855
|
+
package exists. Both roots must resolve to the same directory. The picks output
|
|
856
|
+
is an existing dedicated project-relative directory disjoint from inputs.
|
|
857
|
+
No version/draft selector is inferred: demo/build version records and unrelated
|
|
858
|
+
derived evidence are allowed, while an actual draft or a non-null
|
|
859
|
+
`versions[].review_package` requires its existing explicit package designation.
|
|
860
|
+
This form takes exactly one target and no additional inspection options.
|
|
861
|
+
|
|
862
|
+
The existing joined resolver reads the project, retained option sets and input
|
|
863
|
+
hashes. The launcher retains an internal interview subject, not a `ReviewPackage`.
|
|
864
|
+
The shared server serves the same `web/index.html` and bounded interview routes;
|
|
865
|
+
its internal `/api/review` response contains `subject: "interview"`, project
|
|
866
|
+
path/hash, source hash, label and capability flags, with no manifest, model,
|
|
867
|
+
reviewed-package identity or package session. The existing modal mounts the
|
|
868
|
+
existing interview form. Model APIs refuse `MODEL_UNAVAILABLE`; source drift
|
|
869
|
+
refuses `INTERVIEW_OPTIONS_STALE`. Reads do not write sources. The joined dialog and standing record form use one shared list | image | survey
|
|
870
|
+
answer builder. There is no interview Note input. Existing saved or historical
|
|
871
|
+
notes remain readable as read-only text and are carried unchanged. Joined picks
|
|
872
|
+
omit `note` when none exists; the job act retains its required string field.
|
|
873
|
+
Historical records, picks/act/verdict schemas and explicit
|
|
874
|
+
version/draft joins retain their existing readers and checks.
|
|
875
|
+
This opening form does not replace the semantic standing review cycle.
|
|
876
|
+
|
|
852
877
|
## Stage-1 draft mesh inspection
|
|
853
878
|
|
|
854
879
|
`GET /api/stage-parts` in single inspections uses the live handoff's original
|
|
@@ -1004,14 +1029,30 @@ loaded through Play. Independent depth control is unavailable on this surface.
|
|
|
1004
1029
|
|
|
1005
1030
|
A manifest may declare `direction` as the literal package-relative path to a
|
|
1006
1031
|
retained Create `rig-create/direction@1` or `rig-create/direction@2` document
|
|
1007
|
-
(up to 256 KiB). A
|
|
1032
|
+
(up to 256 KiB). A manifest may also declare `scene`, requiring `direction`.
|
|
1033
|
+
The scene must equal the direction@2 path, hash and number and be a closed
|
|
1034
|
+
`rig-create/scene@1` document. Its rig/model and stage match the inspected model;
|
|
1035
|
+
its animation must exist. Background and optional foreground PNGs are contained,
|
|
1036
|
+
byte-hashed, dimension-checked and served with the scene. The closed layer order
|
|
1037
|
+
is background, rig, then the declared foreground. Missing, changed or mismatched
|
|
1038
|
+
inputs refuse by name (`SCENE_REQUIRED`, `SCENE_SOURCE_MISMATCH`,
|
|
1039
|
+
`SCENE_MODEL_MISMATCH`, `SCENE_ANIMATION_MISSING`, `SCENE_PLATE_CHANGED`,
|
|
1040
|
+
`SCENE_PLATE_DIMENSIONS`, `SCENE_LAYER_ORDER`).
|
|
1041
|
+
|
|
1042
|
+
Scene playback uses the shared viewport and its existing canvas, controls and
|
|
1043
|
+
point comments. The take clock follows duration/loop, the camera box frames the
|
|
1044
|
+
composite, and timing maps take seconds to rig-animation seconds. The panel names
|
|
1045
|
+
the take and its planes without JSON. Direction@1 and scene-less publications
|
|
1046
|
+
retain the plain rig view with a reason. Scene and plate bytes enter the existing
|
|
1047
|
+
package/publication source hash; verdict acts gain no fields. Live post summaries
|
|
1048
|
+
use the publication's existing post selector for their version.
|
|
1008
1049
|
Preserve the document's model path relative to the Review package root. Review
|
|
1009
1050
|
requires that path and SHA-256 to match the inspected compiled model and
|
|
1010
1051
|
includes the direction file in the package source hash. The panel shows authored
|
|
1011
|
-
|
|
1052
|
+
take and planes read-only while that inspected model is on stage. Create
|
|
1012
1053
|
remains responsible for validating project history and citations. Viewport pan
|
|
1013
|
-
and zoom affect only inspection.
|
|
1014
|
-
|
|
1054
|
+
and zoom affect only inspection. Camera Apply remains unavailable; authored
|
|
1055
|
+
camera playback requires the declared scene above.
|
|
1015
1056
|
|
|
1016
1057
|
The optional `sets` manifest path names a package-local Play attachment-set
|
|
1017
1058
|
sidecar for the inspected single-package build. Review includes it in the
|
|
@@ -1019,7 +1060,7 @@ source hash and loads its sets through the published runtime. Scratch builds
|
|
|
1019
1060
|
use their own model and do not inherit the inspected build's sidecar. Compare
|
|
1020
1061
|
and standalone parts retain their existing inspection surfaces.
|
|
1021
1062
|
|
|
1022
|
-
|
|
1063
|
+
The standing live-job contract ([Review #484](https://github.com/rig-c/review/issues/484)) retains `source.direction` and the `direction-review` verdict stage unchanged. [Review #797](https://github.com/rig-c/review/issues/797) wires plated take playback through the shared viewport and publication identity, superseding the playback core of #482/#483. [Review #373](https://github.com/rig-c/review/issues/373) remains parked.
|
|
1023
1064
|
|
|
1024
1065
|
### Scene interview records
|
|
1025
1066
|
|
|
@@ -1055,56 +1096,6 @@ or establish official Create writer acceptance.
|
|
|
1055
1096
|
|
|
1056
1097
|
`src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@2`) and `JOB_ACT_SCHEMA` (`rig-review/act@2`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). One-shot file-handoff workflows documented elsewhere in this reference remain preserved as legacy/history compatibility for existing callers.
|
|
1057
1098
|
|
|
1058
|
-
### Embedded N-job owner
|
|
1059
|
-
|
|
1060
|
-
`startJobHub` and `hub.openJob` from `@rig-c/review/job-host` add one
|
|
1061
|
-
process-local embedded owner for N semantic jobs. One PID/listener serves one
|
|
1062
|
-
human owner URL and job list, with a common bootstrap-declared reviewer.
|
|
1063
|
-
The existing job-api@2/act@2 schemas apply independently to each job's identity,
|
|
1064
|
-
source binding, generation, idempotency, grants, pending asks, finalized acts,
|
|
1065
|
-
display acknowledgment and replay cursor. Hub-selected frames use the current
|
|
1066
|
-
`?hub=<incarnation>` query with optional literal `lang=en` or `lang=ko`. The
|
|
1067
|
-
normal cycle remains `publish`,
|
|
1068
|
-
`ask`, `next`, direct writer `fetch-act`, and explicit `close`.
|
|
1069
|
-
|
|
1070
|
-
Trusted `readPublished`, `partsEnumerator` and `installWriterBinding` hooks are
|
|
1071
|
-
registered in the owning process with the existing declared IDs. Owner-list
|
|
1072
|
-
access requires the private hub capability. Each job separately authenticates
|
|
1073
|
-
agent, UI and read-only writer requests. The reviewer binding records trusted
|
|
1074
|
-
bootstrap provenance. Supplied sources stay immutable, and agents never create
|
|
1075
|
-
internal Review state, act files or writer binding files.
|
|
1076
|
-
|
|
1077
|
-
Each `startJobHub` listener start mints one shared canonical lowercase UUIDv4
|
|
1078
|
-
`listenerIncarnation` across all jobs registered on that hub. Opening additional
|
|
1079
|
-
jobs preserves that incarnation, and stopping and restarting the hub rotates
|
|
1080
|
-
`listenerIncarnation` alongside the hub capability and `workspace` query. Each
|
|
1081
|
-
`hub.openJob` call returns a required non-null detached deeply frozen
|
|
1082
|
-
`job.attachment: JobHostReuseExpectation` derived directly from the owning hub
|
|
1083
|
-
context, including when a compact on-disk `job-ui/<jobId>.json` descriptor omits
|
|
1084
|
-
`listenerIncarnation` at the 65,536-byte limit. Passing a runtime
|
|
1085
|
-
`reuseOnly` property to `hub.openJob` rejects with `JOB_REQUEST_INVALID`
|
|
1086
|
-
(`JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer' | 'reuseOnly'>`).
|
|
1087
|
-
|
|
1088
|
-
Closing one job revokes its writer grant while other jobs and the shared owner
|
|
1089
|
-
continue. `await hub.stop()` stops transport and disposes sessions while
|
|
1090
|
-
preserving active durable jobs and their grants. Restart re-registers the
|
|
1091
|
-
required callbacks and refreshes writer origins. Active job identity and grants
|
|
1092
|
-
persist, while the hub capability, `listenerIncarnation` and `workspace`
|
|
1093
|
-
incarnation query rotate and invalidate prior strict `reuseOnly` expectations.
|
|
1094
|
-
Closed retained entries count toward the current hub's 32-entry application
|
|
1095
|
-
bound. The bound provides no hardware performance guarantee.
|
|
1096
|
-
|
|
1097
|
-
Compatible same-job `startJobHost` attachment remains supported via both
|
|
1098
|
-
ordinary authenticated reuse and strict `reuseOnly: {expected}` attachment,
|
|
1099
|
-
which skips `installWriterBinding` during strict bootstrap. Hub registration
|
|
1100
|
-
refuses an active external standalone owner with `JOB_HUB_EXTERNAL_HOST` and a
|
|
1101
|
-
live unresponsive owner with `JOB_HUB_HOST_UNRESPONSIVE`. General cross-process
|
|
1102
|
-
callback registration remains deferred. External consumer-owned adoption remains
|
|
1103
|
-
pending in [Review #512](https://github.com/rig-c/review/issues/512). Public
|
|
1104
|
-
signatures and the host-owned integration example are in
|
|
1105
|
-
[Public API stability](STABILITY.md#embedded-semantic-job-hub) and
|
|
1106
|
-
[Embedded semantic jobs](WORKFLOWS.md#embedded-semantic-jobs).
|
|
1107
|
-
|
|
1108
1099
|
### Vocabulary, authority, CLI and host ports
|
|
1109
1100
|
|
|
1110
1101
|
- **Human UI vs agent verbs.** People submit decisions exclusively through the Review browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`). Agents drive the standing job through four semantic verbs (`publish`, `ask`, `next`, `close` in `JobAgentRequest`). Consumer writers use the separate read-only transport verb `fetch-act` (`JobFetchActRequest`), which is never a human-act writer.
|
|
@@ -1144,38 +1135,11 @@ signatures and the host-owned integration example are in
|
|
|
1144
1135
|
- **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).
|
|
1145
1136
|
- **`interview-picks`.** `JobActValues['interview-picks']` carries `questionId`, ordered `selections` (`itemId`, `optionId`, nullable `otherText`) and `note`, with non-null `source.optionSet` (`id` and `sha256`).
|
|
1146
1137
|
- **`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.
|
|
1147
|
-
- **`parts-verdict`.** `JobActValues['parts-verdict']`
|
|
1148
|
-
- **`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.
|
|
1138
|
+
- **`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`).
|
|
1139
|
+
- **`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.
|
|
1149
1140
|
- **`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.
|
|
1150
1141
|
- **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.
|
|
1151
|
-
- **C4 manifest-referenced parts PNG identity.** C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <
|
|
1152
|
-
|
|
1153
|
-
### Image-set publication and human comparison
|
|
1154
|
-
|
|
1155
|
-
Before asking, agents read `next.value.capabilities.imageSetVerdict` through the
|
|
1156
|
-
existing authenticated semantic API or `session next` CLI and require true with
|
|
1157
|
-
`assertJobImageSetCapability`. Hub metadata carries the same capability. Missing
|
|
1158
|
-
support refuses locally with `JOB_IMAGE_SET_UNSUPPORTED`, while the frozen older
|
|
1159
|
-
parser rejects the new stage with `JOB_ASK_INVALID`.
|
|
1160
|
-
|
|
1161
|
-
The trusted publication reader returns optional `imageSet` with purpose
|
|
1162
|
-
`plate-adoption` and 2–8 ordered `{role, name, path, sha256?}` rows. It uses the
|
|
1163
|
-
existing producer-held frozen record callback, with no inferred plate schema.
|
|
1164
|
-
Exactly one source, at least one candidate and optional references are allowed.
|
|
1165
|
-
Names and job-root-relative paths are unique, contained and symlink-checked.
|
|
1166
|
-
The daemon validates supplied hashes, retains exact bytes and rechecks them at
|
|
1167
|
-
ask and finalize. The hub displays the images side by side in producer order,
|
|
1168
|
-
with their names, roles and hashes. Decode and paint precede display acknowledgment.
|
|
1169
|
-
Equal bytes remain visible and are flagged in `source.duplicateHashes`.
|
|
1170
|
-
|
|
1171
|
-
Image acts carry `source.imageSetDigest`, SHA-256 of UTF-8
|
|
1172
|
-
`JSON.stringify(images.map(({role, name, sha256}) => ({role, name, sha256})))`.
|
|
1173
|
-
Exact key order, array order and Unicode strings are preserved. Paths remain in
|
|
1174
|
-
the source identity and are excluded from that ordered-list digest. The
|
|
1175
|
-
image-only source hash additionally binds the frozen record. Optional image notes
|
|
1176
|
-
use exact member names and human words. Every source identity and digest is
|
|
1177
|
-
server-derived. Consumer fetch, human authority, drafts, nonce and cursor rules
|
|
1178
|
-
apply through the existing cycle. [Public shapes and refusals](STABILITY.md#image-set-verdict-extension).
|
|
1142
|
+
- **C4 manifest-referenced parts PNG identity.** C4 binds the exact public `partsFileReferences(dir)` array from `@rig-c/parts/src/parts.ts`, whose contract is frozen at Parts 2.25.0. The trusted host resolves an installed version in `JOB_PARTS_ENUMERATOR_RANGE` (`>=2.25.0 <3.0.0`), supplies its actual version and official callback through `partsEnumerator`, and declares `partsEnumeratorId`. `JobPartsIdentity.enumeratorVersion` carries that actual version. Manifest paths are work-root-relative and image paths are relative to the manifest directory. Each image carries `path`, bounded-string `role` and raw-byte `sha256`. Review compares the claimed array positionally with the official array, preserving its role/order/duplicate semantics. Upstream roles include `part`, `alternate`, `depth`, `painting` and `figure_mask`. Review bounds shape and paths, refuses traversal/symlinks, decodes PNGs and hashes retained bytes. Missing references refuse with row, role and path, including a missing sibling figure mask when a render copy exists. Unreferenced extras stay outside this parts identity. Composite source hashes use `rig-review-job-source/2`. Create #184 production reader/projection and official-hook wiring remain pending.
|
|
1179
1143
|
|
|
1180
1144
|
### Rig verdict still backend
|
|
1181
1145
|
|
|
@@ -1183,11 +1147,11 @@ New rig-review verdicts use `rig-review/act@3` and a top-level `still` with `pat
|
|
|
1183
1147
|
|
|
1184
1148
|
The authenticated rig UI submission accepts `capture` alongside the human `value`. Its closed fields are `png` as a PNG data URI, `width`, `height`, `camera`, `framing`, `view`, `frame`, optional `animation`, `playing` and `binding`. Binding contains `publicationId`, `instanceKey`, `sourceHash`, `pageId`, `askId`, `drawGeneration` and `playerGeneration`. The daemon compares source/page/ask/instance identity with the current displayed nonce and derives the hash and filename from validated PNG bytes. Draw provenance is supplied by the authenticated human UI. The PNG is the whole default-camera Rig viewport and its background, with tool overlays excluded. The standing window normally composites the player's model rasters and background into one visible canonical bitmap, with tool overlays kept separate. Capture synchronously makes only an equal-size copy of that committed bitmap without pausing active playback. Model rendering and background composition occur exclusively during normal presentation. Whole-device-pixel global translation of the unchanged bitmap preserves capture eligibility. Changes to device-pixel phase, pane-local placement or extent, source binding, or player/frame generation refuse capture. A successful public draw snapshot binds canonical bitmap identity, native dimensions, CSS size and DPR, local placement and device-pixel phase together with the public wrapped clip time (`entry(0).animationTime` as numeric `frame`), internal unwrapped `trackTime` (`player.time`), loop state, animation and source before asynchronous PNG encoding. The first full request and human words are retained unchanged for reply-loss retry across subsequent motion or transport changes. The inspection transport starts paused on `Setup` (`Play` disabled, `Repeat` enabled), drives continuous playback through public `Play`/`Pause` and `Repeat` controls over an owned `requestAnimationFrame` loop, pauses on clip selection or manual time seek, and on a `Repeat` toggle explicitly restarts the clip with the new loop flag and deterministically seeks the current visible time (resetting physics carry and frame delta). Owned animation frames and playback stop on source replacement, hidden-hub visibility transitions, `pagehide` and unmount. Exact-pixel acceptance in an overlay-free square fixture compares the full viewport screenshot against the exported CLI PNG for paused captures, and compares the synchronously sampled canonical bitmap, copied encoding canvas and exported CLI PNG at `toBlob` entry for moving captures while playback continues. Frame chrome lies outside the capture contract.
|
|
1185
1149
|
|
|
1186
|
-
Failed capture, nondefault camera/framing, solo/highlight/comparison and mismatched binding refuse by name. Playing is accepted. Raw PNG is bounded to 8 MiB, each axis to 16384 and the decoded image to 16,777,216 pixels. Only authenticated same-origin rig-capture submissions may use a 12 MiB JSON body. Ordinary mutations retain 256 KiB. PNG
|
|
1150
|
+
Failed capture, nondefault camera/framing, solo/highlight/comparison and mismatched binding refuse by name. Playing is accepted. Raw PNG is bounded to 8 MiB, each axis to 16384 and the decoded image to 16,777,216 pixels. Only authenticated same-origin rig-capture submissions may use a 12 MiB JSON body. Ordinary mutations retain 256 KiB. Authenticated UI act submissions with inline comment images also use the 12 MiB JSON bound (#790); unrelated mutations keep their existing bound. Comment PNGs are stored once by SHA-256 in the same transactional SQLite store as verdict stills. Private job documents and browser events retain content-addressed references; the browser retrieves the original PNG through a job-scoped, UI-capability-protected route and checks its digest before restoring the full comment. Finalized acts from consumer fetch, raw export, agent `next` and the CLI retain the original inline PNGs, key order and exact bytes. A full act and consumer event batch are bounded to 16 MiB; browser event metadata retains the 512 KiB bound. No pixels, text, anchors or historical codecs are changed. PNG BLOB, losslessly packed act bytes, act, replay, answered ask and event commit in one SQLite transaction. Retried submissions reuse the immutable first act. Close revokes fetch while preserving the act and PNG for the act lifetime. Closed jobs retain UI-capability-protected, read-only access to comment crops referenced by their recorded events, so a browser can finish consuming the act and closure. A failed crop read is marked unavailable in the browser event only and does not prevent later events or closure from being consumed; finalized consumer acts remain unchanged.
|
|
1187
1151
|
|
|
1188
1152
|
The existing consumer POST `/jobs/<jobId>/api` accepts the unchanged fetch-act body and existing bearer grant. Default/JSON Accept returns the existing API envelope. `Accept: application/vnd.rig-review.act+json` returns raw act bytes, and `Accept: image/png` returns the bound PNG for the same actId. Destination paths stay local to the CLI.
|
|
1189
1153
|
|
|
1190
|
-
The consumer CLI bounds stdin to 4096 bytes and accepts one existing 64-hex grant with an optional final newline. It bounds raw act reads to
|
|
1154
|
+
The consumer CLI bounds stdin to 4096 bytes and accepts one existing 64-hex grant with an optional final newline. It bounds raw act reads to 16 MiB and PNG reads to 8 MiB independently of Content-Length. It validates both responses before writing a PNG temporary file inside the existing consumer directory, fsyncs the file, renames it to the content-addressed filename, fsyncs the destination directory and then writes exact act bytes to stdout. Per-directory local output serialization preserves existing verified PNGs and refuses conflicting files or a retained `.rig-review-still.lock`, naming the exact local lock path without automatically deleting another writer's lock. Pre-stdout failure removes only this invocation's files. A MIDWRITE EPIPE exits nonzero and may leave the installed PNG. The consumer ignores partial stdout on nonzero exit and owns act.json persistence and pair staging.
|
|
1191
1155
|
|
|
1192
1156
|
The consumer writes successful stdout verbatim as act.json beside the PNG and hashes those exact bytes itself. The act contains the PNG hash only. No self-hash, manifest, envelope, private binding discovery or destination filesystem endpoint is introduced.
|
|
1193
1157
|
|
|
@@ -1202,7 +1166,7 @@ The manifest and complete retained image rows enter the composite source hash. L
|
|
|
1202
1166
|
- **Sibling binding ownership.** `JOB_CONSUMER_AUTH_MODE` is `'writer-owned-sibling-fetch-capability'` (`JobConsumerGrant` with `jobId`, `operation` set to `'fetch-act'`, `actKinds` and `lifetime` set to `'until-explicit-close'`). [Create #184](https://github.com/rig-c/create/issues/184) owns creation and path of a private writer-owned sibling binding outside `project.json` whose versioned record carries only the semantic job locator (Create's production reader/writer readback integration remains pending [Create #184](https://github.com/rig-c/create/issues/184)). The binding is never tracked in version control, never present in unstaged project output and never shipped in templates, public examples or fixtures.
|
|
1203
1167
|
- **Agent isolation and capability lifecycle.** The consumer writer reads its own sibling binding directly. Agents never construct, parse or carry Review session, picks, verdict, applied-record or sibling-binding files. Actual separate-UID isolation remains required for Review's distinct state unreadability test (`JOB_AGENT_ISOLATION_HOLE`), and no same-user forger-resistance claim is made. The random per-job bearer capability grants finalized act fetch (`fetch-act`) only, via exact loopback routes and `Authorization`. Neither `next` nor `status` returns it, and human metadata alone never authenticates a fetch. The capability dies at explicit `close`, old project history cannot restore it, each new job incarnation receives a new grant, invalid grants refuse with `JOB_CAPABILITY_REQUIRED` or `JOB_AUTHORITY_REFUSED` and closed-job fetches refuse with `JOB_CLOSED`. No self-service grant API exists.
|
|
1204
1168
|
- **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.
|
|
1205
|
-
- **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`, `
|
|
1169
|
+
- **Error codes.** `JOB_ERROR_CODES` enumerates the closed refusal set (`JOB_REQUEST_INVALID`, `JOB_BODY_LIMIT`, `JOB_LOOPBACK_REQUIRED`, `JOB_SAME_ORIGIN_REQUIRED`, `JOB_CAPABILITY_REQUIRED`, `JOB_AUTHORITY_REFUSED`, `JOB_UNKNOWN`, `JOB_CLOSED`, `JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`, `JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`, `JOB_PUBLICATION_UNKNOWN`, `JOB_SNAPSHOT_RECLAIMED`, `JOB_ASK_INVALID`, `JOB_ASK_SUPERSEDED`, `JOB_ACT_UNKNOWN`, `JOB_ACT_INVALID`, `JOB_ACT_KIND_DISABLED`, `JOB_ACT_SOURCE_STALE`, `JOB_DISPLAY_MISMATCH`, `JOB_CURSOR_INVALID`, `JOB_STORAGE_FAILED`, `JOB_AGENT_ISOLATION_HOLE`), each returning bounded safe detail with no arbitrary worker text or private paths.
|
|
1206
1170
|
|
|
1207
1171
|
### Model-free record mode and source seam
|
|
1208
1172
|
|
|
@@ -1210,19 +1174,401 @@ The manifest and complete retained image rows enter the composite source hash. L
|
|
|
1210
1174
|
|
|
1211
1175
|
`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).
|
|
1212
1176
|
|
|
1213
|
-
`JOB_API_SCHEMA` (`rig-review/job-api@2`), `JOB_ACT_SCHEMA` (`rig-review/act@2`), `JOB_CAPABILITIES` (`{
|
|
1177
|
+
`JOB_API_SCHEMA` (`rig-review/job-api@2`), `JOB_ACT_SCHEMA` (`rig-review/act@2`), `JOB_CAPABILITIES` (`{}`) 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.
|
|
1214
1178
|
|
|
1215
1179
|
| Surface | Exact keys or closed values |
|
|
1216
1180
|
| --- | --- |
|
|
1217
1181
|
| `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
|
|
1218
1182
|
| `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
|
|
1219
|
-
| `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`), `{kind: 'reopen', stage}` |
|
|
1220
|
-
| `RecordPublishedContext` | `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']` |
|
|
1183
|
+
| `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`, `direction-review`, `interview`), `{kind: 'reopen', stage}` |
|
|
1184
|
+
| `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
|
|
1221
1185
|
| `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
|
|
1222
|
-
| `RecordSource` | `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']` |
|
|
1223
|
-
| `rig-review-job-record-source/1` | `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']` |
|
|
1186
|
+
| `RecordSource` | Required `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
|
|
1187
|
+
| `rig-review-job-record-source/1` | Required `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']`, optional `checkpointEvidence` on plans |
|
|
1224
1188
|
| `rig-review-job-record-instance/1` | `['schema', 'fingerprint', 'sourceHash']` |
|
|
1225
1189
|
|
|
1226
1190
|
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.
|
|
1227
1191
|
|
|
1228
1192
|
`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)).
|
|
1193
|
+
|
|
1194
|
+
Record `interview` and `direction-review` signoffs use the existing signoff modal and are plan-bound like `post-interview`: the published record must declare the subject and contain non-empty `plan.steps`. Each approves the frozen record revision through its project/source hashes; no separate post-version selector or new ask/act field is carried. Existing stage values and act schemas are unchanged. The public package plan-bound stage list remains the original three stages; package `direction-review` signoffs and historical package acts continue to accept `plan: null`.
|
|
1195
|
+
|
|
1196
|
+
### Optional sealed checkpoint evidence
|
|
1197
|
+
|
|
1198
|
+
The trusted `JobPublicationReader` package context and the record reader's
|
|
1199
|
+
`PlanContext` may declare `checkpointEvidence`. Package-only API@2, API@3 package
|
|
1200
|
+
publications in record-and-package mode, and model-free record plan publications
|
|
1201
|
+
share this declaration. It is admitted only through the trusted reader and its
|
|
1202
|
+
exact work-root-relative file closure. Each packet binds an admitted checkpoint
|
|
1203
|
+
subject to an existing plan step. Package aliases use the subject's
|
|
1204
|
+
`planStepId ?? checkpointId`. Record checkpoints use the same checkpoint and plan
|
|
1205
|
+
step ID. Option-set publications refuse this extension.
|
|
1206
|
+
|
|
1207
|
+
The collection contains ordered packets with exactly these fields.
|
|
1208
|
+
|
|
1209
|
+
```ts
|
|
1210
|
+
{
|
|
1211
|
+
schema: 'rig-review-checkpoint-evidence/1',
|
|
1212
|
+
checkpointId: string,
|
|
1213
|
+
planStepId: string,
|
|
1214
|
+
tiles: [{id: string, label: string, path: string, sha256: string}],
|
|
1215
|
+
table: {path: string, sha256: string, label?: string},
|
|
1216
|
+
routesText: string,
|
|
1217
|
+
recommendationText: string
|
|
1218
|
+
}
|
|
1219
|
+
```
|
|
1220
|
+
|
|
1221
|
+
The table's sealed UTF-8 JSON document has exactly `schema`, `columns` and `rows`.
|
|
1222
|
+
Its schema is `rig-review-checkpoint-table/1`. Columns are ordered, nonempty text
|
|
1223
|
+
labels. Each row is an array of exactly that column count, with string, finite
|
|
1224
|
+
number, boolean or null cells. The declaration carries only the table file seal
|
|
1225
|
+
and optional label. The document alone supplies the table body. All rows, column
|
|
1226
|
+
order, tile order and exact Unicode/text values are preserved. Routes and the
|
|
1227
|
+
recommendation are verbatim text. The owner UI displays supplied text as text and
|
|
1228
|
+
labels the recommendation through its EN/KO catalog. An evidence-bearing card's
|
|
1229
|
+
adjacent mapping uses pass for route (i), accepting the openings, and fail plus
|
|
1230
|
+
the owner's words for (ii) or (iii). The browser value remains
|
|
1231
|
+
`{checkpointId, outcome, words}`. The daemon supplies the finalized `planStepId`.
|
|
1232
|
+
|
|
1233
|
+
Admission bounds are explicit.
|
|
1234
|
+
|
|
1235
|
+
| Item | Bound |
|
|
1236
|
+
| --- | --- |
|
|
1237
|
+
| Packets and tiles | 1–8 packets, 1–8 ordered tiles per packet, unique checkpoint IDs and tile IDs within each packet |
|
|
1238
|
+
| Entire canonical declaration | 32 KiB UTF-8 |
|
|
1239
|
+
| IDs and paths | Existing `jobId` 128-character and `jobPath` 4,096-character limits |
|
|
1240
|
+
| Tile labels, optional table label and column labels | Nonempty strings, at most 512 UTF-16 units each |
|
|
1241
|
+
| Routes and recommendation | Nonempty strings, at most 4,096 UTF-16 units each |
|
|
1242
|
+
| Tile bytes | Static noninterlaced 8-bit RGB/RGBA PNG, at most 8 MiB, each edge at most 16,384 and at most 16,777,216 pixels, validated through the existing PNG decoder |
|
|
1243
|
+
| Table bytes | At most 256 KiB per raw document and 512 KiB total raw table bytes per publication |
|
|
1244
|
+
| Table dimensions | 1–32 columns, 0–2,048 rows, at most 16,384 cells per document |
|
|
1245
|
+
| String cells | At most 2,048 UTF-16 units, including empty strings |
|
|
1246
|
+
|
|
1247
|
+
Text permits LF and tab and refuses other ASCII control characters. Present
|
|
1248
|
+
`undefined`, null and empty evidence collections refuse. Missing required keys,
|
|
1249
|
+
unknown packet/tile/table/document keys, duplicate identities, nested cells and
|
|
1250
|
+
incorrect row widths refuse. Absent evidence stays omitted in normalized
|
|
1251
|
+
contexts, sources, metadata and stored state. Existing 512 KiB event metadata (full consumer acts follow #790), 2 MiB owner
|
|
1252
|
+
metadata and 16 MiB durable-document delivery/admission limits remain in force.
|
|
1253
|
+
The declaration and table bounds leave room for existing metadata and events.
|
|
1254
|
+
Existing closure file count and total retained-byte limits also apply.
|
|
1255
|
+
|
|
1256
|
+
Every tile and table path must exactly match a trusted closure member and SHA-256.
|
|
1257
|
+
Review reuses regular-file, descriptor-based, literal portable path containment
|
|
1258
|
+
checks, including every directory component, and rejects symlinks and escapes.
|
|
1259
|
+
Actual PNG bytes are decoded and the table is parsed before publication.
|
|
1260
|
+
`JOB_SOURCE_MISMATCH` carries named details `CHECKPOINT_EVIDENCE_INVALID`,
|
|
1261
|
+
`CHECKPOINT_EVIDENCE_HASH_MISMATCH`, `CHECKPOINT_EVIDENCE_PNG_INVALID` or
|
|
1262
|
+
`CHECKPOINT_EVIDENCE_TABLE_INVALID`. Unreadable paths or byte bounds use
|
|
1263
|
+
`JOB_SOURCE_UNRETAINABLE` with `CHECKPOINT_EVIDENCE_PATH_REFUSED` or
|
|
1264
|
+
`CHECKPOINT_EVIDENCE_TABLE_LIMIT`. Existing live-source and retained-snapshot
|
|
1265
|
+
refusals still apply to movement during retention or subsequent operations.
|
|
1266
|
+
|
|
1267
|
+
Source binding contains the canonical `checkpointEvidence` collection. Packet
|
|
1268
|
+
key order is `schema`, `checkpointId`, `planStepId`, `tiles`, `table`, `routesText`,
|
|
1269
|
+
`recommendationText`. Tile key order is `id`, `label`, `path`, `sha256`. Table
|
|
1270
|
+
key order is `path`, `sha256`, followed by `label` only when supplied. JSON uses
|
|
1271
|
+
these fixed keys and preserves collection order and exact strings. The package
|
|
1272
|
+
`rig-review-job-source/2` composite preimage appends `checkpointEvidence` after
|
|
1273
|
+
`files`. The record `rig-review-job-record-source/1` digest preimage does the same.
|
|
1274
|
+
No evidence field is emitted or hashed for historical absence. Legacy direct
|
|
1275
|
+
package hashes and literal historical digest/source bytes retain their existing
|
|
1276
|
+
form. Labels, paths, IDs, routes and recommendations all participate, so a
|
|
1277
|
+
metadata-only edit changes source and instance identity or refuses against an
|
|
1278
|
+
already bound source. Raw table bytes are bound by their seal, including changes
|
|
1279
|
+
that parse to the same table. Existing API, finalized-act and source schema
|
|
1280
|
+
markers remain as documented above.
|
|
1281
|
+
|
|
1282
|
+
Both publication-pinned `api/review` projections conditionally include the ordered
|
|
1283
|
+
`checkpointEvidence` collection. Metadata retains the declaration fields, adds
|
|
1284
|
+
each tile's `url` as
|
|
1285
|
+
`/api/checkpoint-evidence/<checkpointId>/tiles/<zero-based-index>`, and expands
|
|
1286
|
+
`table` with its parsed `schema`, `columns`, complete `rows` and `url` as
|
|
1287
|
+
`/api/checkpoint-evidence/<checkpointId>/table`. Both tile and table URLs are
|
|
1288
|
+
relative to the pinned publication base, matching existing interview image URLs.
|
|
1289
|
+
The resolver admits only a declared checkpoint member, finds its exact seal and
|
|
1290
|
+
streams its retained bytes through the existing sealed reference route. Table
|
|
1291
|
+
GET returns the exact retained raw JSON bytes, including their whitespace, and
|
|
1292
|
+
supports HEAD through the same route. Its 256 KiB bound and regular-file/path/SHA
|
|
1293
|
+
checks run before streaming. The URL is derived delivery metadata. The producer's
|
|
1294
|
+
table declaration continues to contain only `path`, `sha256` and optional `label`.
|
|
1295
|
+
|
|
1296
|
+
Before presenting the projection, the owner UI fetches the pinned table URL and
|
|
1297
|
+
checks its raw-byte SHA-256 against the source binding's declared table seal.
|
|
1298
|
+
It parses that authenticated UTF-8 JSON and compares its `schema`, `columns` and
|
|
1299
|
+
`rows` with the projected body, preserving every column and row in order. This
|
|
1300
|
+
comparison uses ordinary JSON parsing and exact data equality. The backend owns
|
|
1301
|
+
table grammar validation at admission and metadata projection. A changed metadata
|
|
1302
|
+
row, column, order or schema under the same source hash fails that comparison.
|
|
1303
|
+
Metadata has the same pinned source hash as the publication. A record publication
|
|
1304
|
+
remains manifest-free. Undeclared evidence has no projection, tile or table route.
|
|
1305
|
+
|
|
1306
|
+
Durable reads authenticate evidence-bearing package composite hashes from the
|
|
1307
|
+
retained base-package hash, record, selector, plan, parts and closure. The private
|
|
1308
|
+
retained `checkpointEvidencePackageHash` stores that base hash only for this
|
|
1309
|
+
extension. The package metadata route additionally compares it to `loadReview`
|
|
1310
|
+
on the retained package. Record sources reuse their canonical digest parser.
|
|
1311
|
+
Stored context, publication, ask, act, event and replay copies must agree with
|
|
1312
|
+
the retained declaration and source identity. Null, undefined or missing source
|
|
1313
|
+
copies for an evidence-bound publication refuse with `JOB_SOURCE_MISMATCH` before
|
|
1314
|
+
source property access. These checks require no live files
|
|
1315
|
+
or reclaimed historical snapshots. Retained-file integrity is checked on fresh
|
|
1316
|
+
evidence mutations and actual asset/metadata reads. Record asks/finalizations
|
|
1317
|
+
also repeat the existing two reader phases and reject metadata drift. Package
|
|
1318
|
+
asks use the reader declaration pinned at publication and the existing current
|
|
1319
|
+
record/file seals. They retain the existing single-reader publication lifecycle.
|
|
1320
|
+
An exact committed publication/ask/act retry returns its original identity after
|
|
1321
|
+
live output drift. A fresh mutation still validates currentness. Reopening never
|
|
1322
|
+
adds current live evidence to an old publication.
|
|
1323
|
+
|
|
1324
|
+
Review owns this additive public declaration. Create #395 implementation requires
|
|
1325
|
+
HQ signature at the exact Review shape PR head. Historical record-source readers
|
|
1326
|
+
with the earlier closed key set refuse evidence-bearing sources. New consumers
|
|
1327
|
+
require the signed extended contract. Owner-screen integration,
|
|
1328
|
+
EN/KO visual verification and later release serving have their own acceptance
|
|
1329
|
+
steps.
|
|
1330
|
+
|
|
1331
|
+
### Sealed plan step text
|
|
1332
|
+
|
|
1333
|
+
Both publication-pinned `api/review` responses append delivery-only `planText`
|
|
1334
|
+
when the accepted source has a plan. The daemon authenticates `project.json`
|
|
1335
|
+
from that publication's retained snapshot against its record seal and existing
|
|
1336
|
+
`projectHash`, then projects `does`, `produces`, `bar` and `rests_on`.
|
|
1337
|
+
|
|
1338
|
+
The projected envelope has ordered keys `schema`, `record`, `status`, `steps`.
|
|
1339
|
+
`schema` is `rig-review/job-plan-text@1`, `record` is `{path:"project.json",sha256}`,
|
|
1340
|
+
and `status` is `projected`. Rows follow the accepted plan's exact id/hash order.
|
|
1341
|
+
Each row has `id`, `hash`, optional `does`, `produces`, `bar`, `rests_on`, then
|
|
1342
|
+
`issues`. Each field supplies exactly one value or an ordered
|
|
1343
|
+
`{field,reason:"absent"|"invalid"|"limit"}` issue. Scalar values are strings and
|
|
1344
|
+
`rests_on` is an ordered string array. Empty strings/arrays, whitespace, line
|
|
1345
|
+
endings, Unicode form, duplicate references and array order are preserved.
|
|
1346
|
+
Producer extras stay outside this display projection.
|
|
1347
|
+
|
|
1348
|
+
D1 matches only accepted ids, preserving source order and existing checkpoint
|
|
1349
|
+
aliases (`planStepId ?? checkpointId`). D2 retains its existing whole-plan
|
|
1350
|
+
count/ordered-id admission checks. Hashes are the producer's opaque accepted
|
|
1351
|
+
identities. The existing reader retains responsibility for their semantic value.
|
|
1352
|
+
|
|
1353
|
+
The unavailable envelope has `schema`, `record` (or null),
|
|
1354
|
+
`status:"unavailable"`, `reason`. Named reasons are
|
|
1355
|
+
`PLAN_TEXT_RECORD_UNAVAILABLE`, `PLAN_TEXT_RECORD_UNSUPPORTED`,
|
|
1356
|
+
`PLAN_TEXT_STEPS_ABSENT`, `PLAN_TEXT_STEPS_INVALID`,
|
|
1357
|
+
`PLAN_TEXT_MAPPING_UNAVAILABLE` and `PLAN_TEXT_LIMIT`. The UI shows the named
|
|
1358
|
+
absence and existing ids/hashes. Partial valid fields remain visible beside
|
|
1359
|
+
their missing/invalid field labels. Existing act authority and historical
|
|
1360
|
+
metadata omission retain their fallback behavior.
|
|
1361
|
+
|
|
1362
|
+
The server retains its 8 MiB project read bound. Display limits are 4,096 plan
|
|
1363
|
+
steps, 4,096 `rests_on` entries and 512 KiB UTF-8 for `planText`. Whole owner
|
|
1364
|
+
metadata retains its 2 MiB bound. A small unavailable envelope replaces an
|
|
1365
|
+
oversized projection. If that envelope also exceeds the response budget, the
|
|
1366
|
+
server returns `JOB_BODY_LIMIT` with `PLAN_TEXT_LIMIT`. Values remain complete
|
|
1367
|
+
within the admitted display budget.
|
|
1368
|
+
|
|
1369
|
+
The browser checks the closed grammar, metadata/source association, record SHA
|
|
1370
|
+
and ordered id/hash mapping. Field values have the normal daemon's authority.
|
|
1371
|
+
Type-valid post-server text mutation can pass those checks. The server's sealed
|
|
1372
|
+
record authentication and the browser's source/grammar checks are their
|
|
1373
|
+
respective validation boundaries. Checkpoint evidence retains its established
|
|
1374
|
+
raw-member authentication.
|
|
1375
|
+
|
|
1376
|
+
This metadata is produced at response time. Source/act schemas, producer reader
|
|
1377
|
+
DTOs, stable `job-host` exports, durable state and canonical hash preimages retain
|
|
1378
|
+
their existing definitions. Checkpoint and signoff values continue through their
|
|
1379
|
+
existing forms, outcome select and submission lifecycle.
|
|
1380
|
+
|
|
1381
|
+
Under HQ ruling 7896ec71, the official D2 consumer gate is the supported
|
|
1382
|
+
record-checkpoint flow following Create #395 integration. Create owns the actual
|
|
1383
|
+
producer receipt. Review's plan-signoff rendering has synthetic UI coverage.
|
|
1384
|
+
Normal CLI plan-signoff bootstrap and `plan-approved` act@4 ingestion are a
|
|
1385
|
+
separate Create follow-up. (Naru, 2026-11-11)
|
|
1386
|
+
|
|
1387
|
+
## Comments decoder contract
|
|
1388
|
+
|
|
1389
|
+
The comments feature accepts multiple ordered entries, each general or pinned to
|
|
1390
|
+
an existing inspection target. Surveys remain separate answer inputs: interview
|
|
1391
|
+
selections, inline Other text and per-question notes keep their existing formats,
|
|
1392
|
+
strings and readers. There is no interview-picks arm or question/ask anchor in
|
|
1393
|
+
this extension. Technical configuration and search controls are outside it.
|
|
1394
|
+
|
|
1395
|
+
The decoders and consumer projections are read-only. Since [Review #713](https://github.com/rig-c/review/issues/713)
|
|
1396
|
+
(HQ contract ruling), the UI finalizers write fresh checkpoint, parts-verdict,
|
|
1397
|
+
rig and direction review-verdict and signoff acts as act@6. The UI submission
|
|
1398
|
+
keeps its existing `words` and `issues` fields. [Review #746](https://github.com/rig-c/review/issues/746)
|
|
1399
|
+
adds optional `feedback: Feedback[]` beside required `words` only for the
|
|
1400
|
+
`rig-review` verdict submission. When present, including an empty list, it is
|
|
1401
|
+
the complete comment list: `feedbackItemComments` maps each row's `summary` to
|
|
1402
|
+
`text` and retains its `id`, frames, target, category and `anchor.context`.
|
|
1403
|
+
The existing decoder validates every mapped comment, its evidence and the
|
|
1404
|
+
whole scalar bound; malformed or blank rows refuse rather than falling back to
|
|
1405
|
+
`words`. The act bar sends a detached feedback list when comments exist and
|
|
1406
|
+
keeps `words` as their projection. It omits `feedback` when there are no comments.
|
|
1407
|
+
Absent `feedback` retains the previous written bytes and words-only mapping.
|
|
1408
|
+
Direction and image verdict submissions do not accept `feedback`. The written
|
|
1409
|
+
act remains act@6; historical words-only acts retain their readers.
|
|
1410
|
+
|
|
1411
|
+
Pointed marks, inline crops, bookmarks and valid time-only null frames remain
|
|
1412
|
+
inside the existing `anchor.context`. This is distinct from act@7's top-level
|
|
1413
|
+
`comment.context`, which remains disabled by `EMIT_UNPINNED_CREATE_FIELDS`.
|
|
1414
|
+
No new field or decoder rule is added to the written act.
|
|
1415
|
+
|
|
1416
|
+
For the words-only mapping, the daemon maps a nonblank note
|
|
1417
|
+
to one comment: anchored to the checkpoint for a checkpoint, general otherwise.
|
|
1418
|
+
It maps each Parts issue to a Parts-anchored comment, before the note. A blank
|
|
1419
|
+
or whitespace-only note writes no comment (`comments: []`). Nothing is padded.
|
|
1420
|
+
A note whose projection exceeds the 10,000-unit scalar bound refuses
|
|
1421
|
+
`JOB_ACT_INVALID`. The bound counts the stored `words`, and the `[label]\n`
|
|
1422
|
+
prefix is part of them, so a general note longer than 9,990 units refuses even
|
|
1423
|
+
though act@5 accepted it. Feedback is many comments, not one long note.
|
|
1424
|
+
Each written act must decode through `parseCommentsAct`.
|
|
1425
|
+
Image-review verdicts and interview picks stay at act@2, because Create refuses
|
|
1426
|
+
both under act@6. Record acts stay at act@4, because Create maps only a record
|
|
1427
|
+
checkpoint under act@6. Standalone save paths keep their existing versions.
|
|
1428
|
+
|
|
1429
|
+
The existing `@rig-c/review/job-host` facade exports:
|
|
1430
|
+
|
|
1431
|
+
| Function | Input → output |
|
|
1432
|
+
| --- | --- |
|
|
1433
|
+
| `parseCommentsAct` | `unknown` → `JobCommentsAct` |
|
|
1434
|
+
| `projectComments` | `readonly JobComment[]` → `string` |
|
|
1435
|
+
| `parseCommentsSession` | `unknown` → `ReviewCommentsSession` |
|
|
1436
|
+
| `parseCommentsCompareSession` | `unknown` → `CompareCommentsSession` |
|
|
1437
|
+
| `parseCommentsPartsVerdict` | `unknown` → `PartsCommentsVerdict` |
|
|
1438
|
+
| `projectSelectedCommentsFeedback` | `ReviewCommentsSession, itemId: string` → `{anchor: JobCommentFeedbackAnchor; summary: string}` |
|
|
1439
|
+
|
|
1440
|
+
Use a decoder before projecting untrusted input. These functions perform no
|
|
1441
|
+
filesystem writes. Decode success validates declared identities and syntax; it
|
|
1442
|
+
does not grant producer/source-kind admission or prove retained asset freshness,
|
|
1443
|
+
source-native pixels, clock availability or owner authority. Those checks stay
|
|
1444
|
+
with the existing retained-source, package feedback and crop pipeline. The
|
|
1445
|
+
native-image region preparation adapter is still required before image-region
|
|
1446
|
+
writers activate.
|
|
1447
|
+
|
|
1448
|
+
`JOB_COMMENTS_ACT_SCHEMA` is `rig-review/act@6`. Its exact envelope keys are
|
|
1449
|
+
`schema, actId, jobId, askId, publicationId, kind, authority, at, source, value`.
|
|
1450
|
+
The existing top-level `still` is required only for a model `rig-review` verdict
|
|
1451
|
+
and forbidden otherwise. It retains fixed camera, content-addressed PNG path,
|
|
1452
|
+
SHA-256 and setup-or-numeric-animation-time validation. The raw export and CLI
|
|
1453
|
+
reuse their existing PNG byte checks and preserve original act stdout bytes.
|
|
1454
|
+
The authority remains daemon-owned human `review-ui` authority. Model/image
|
|
1455
|
+
bindings and record plan sources retain their existing definitions; record
|
|
1456
|
+
option-set sources are excluded. Source capabilities remain consumer-owned.
|
|
1457
|
+
|
|
1458
|
+
| Kind | Exact value keys |
|
|
1459
|
+
| --- | --- |
|
|
1460
|
+
| `checkpoint` | `checkpointId, planStepId, outcome, comments` (`pass` or `fail`) |
|
|
1461
|
+
| `parts-verdict` | `verdict, comments` (`approved` or `changes-requested`) |
|
|
1462
|
+
| `review-verdict` | `stage, verdict, comments` (existing rig/direction/image stages and verdicts) |
|
|
1463
|
+
| `signoff` | `stage, decision, comments` (`approved`) |
|
|
1464
|
+
| `reopen` | `stage, comments` (existing declared record plan subject) |
|
|
1465
|
+
|
|
1466
|
+
The declared plan/source/selector and ask eligibility checks remain applicable.
|
|
1467
|
+
The browser never supplies authoritative checkpoint-to-plan mapping. A Parts
|
|
1468
|
+
verdict is approved exactly when it has no pointed Parts issue anchors; general
|
|
1469
|
+
comments do not create issues. Verdict and signoff remain distinct immutable
|
|
1470
|
+
acts even when one user action will submit the same comments to both.
|
|
1471
|
+
|
|
1472
|
+
A `comments` array has at most 1,000 entries. Each entry has exactly `text` and
|
|
1473
|
+
optional `anchor`. Fresh text is a nonblank string of at most 10,000 UTF-16 units;
|
|
1474
|
+
trimming is a validation predicate and never changes the stored text. Reusing a
|
|
1475
|
+
Feedback or Parts codec preserves its stricter existing text limit. Existing
|
|
1476
|
+
evidence IDs stay unique. Intentional duplicate text and stored order remain.
|
|
1477
|
+
Unknown fields and mixed anchor arms refuse.
|
|
1478
|
+
|
|
1479
|
+
Anchors use existing source-bound fields without a new kind discriminator:
|
|
1480
|
+
|
|
1481
|
+
- Feedback without `summary`: `id, frameStart, frameEnd, target, category`, with
|
|
1482
|
+
optional `context` and compare-only `side`. StageComment remains inside
|
|
1483
|
+
`context.comment`; existing codecs and inline PNG validation are reused.
|
|
1484
|
+
- PartsIssue without `summary`: `schema, id, parts, sourceHash, rigRegion,
|
|
1485
|
+
imageRegion, view, crop, nativeCrop`. Finalized item anchors require prepared
|
|
1486
|
+
native crop metadata. Assembled anchors retain null native crop. Optional assembled-only
|
|
1487
|
+
`view.visibleLayers: {name, imageHash}[]` retains the complete visible set in
|
|
1488
|
+
source item order, bound to `sourceHash` and each loaded source image. Entries
|
|
1489
|
+
must be unique and source-bound before restoration replaces the hidden set.
|
|
1490
|
+
Absent fields retain the historical restore branch and recorded bytes. Readers
|
|
1491
|
+
accept both forms; fresh capture writes this field only when the shared
|
|
1492
|
+
`EMIT_UNPINNED_CREATE_FIELDS` gate is enabled after Create confirms its parser pin.
|
|
1493
|
+
- Named image: `name`, optionally the complete existing-field composition
|
|
1494
|
+
`imageRegion, crop, nativeCrop`. Names resolve in the sealed image set. Regions
|
|
1495
|
+
use nonnegative native-pixel integer origins, positive extents and at most
|
|
1496
|
+
16,777,216 pixels. Actual image bounds and crop-to-original equality remain
|
|
1497
|
+
native preparation checks.
|
|
1498
|
+
- Checkpoint: `checkpointId, planStepId`, resolved through the existing source
|
|
1499
|
+
plan and any declared evidence mapping.
|
|
1500
|
+
|
|
1501
|
+
`projectComments` traverses stored order. Each scalar block is
|
|
1502
|
+
`[label]\n` followed by exact `text`, with `\n\n` between blocks; the empty array
|
|
1503
|
+
projects to the empty string. The complete scalar is bounded to 10,000 UTF-16
|
|
1504
|
+
units. Lists retain individual entries. A general label is `general`; other
|
|
1505
|
+
labels are `JSON.stringify` of these logical target tuples:
|
|
1506
|
+
|
|
1507
|
+
| Anchor | Label tuple |
|
|
1508
|
+
| --- | --- |
|
|
1509
|
+
| Checkpoint | `["checkpoint", checkpointId]` |
|
|
1510
|
+
| Parts | `[schema, parts.map(part => part.name), view.mode]` |
|
|
1511
|
+
| Image | `[name]` |
|
|
1512
|
+
| StageComment-backed Feedback | `[mark.schema, mark.mode, mark.viewport, target.kind, target.name, frameStart, frameEnd]` |
|
|
1513
|
+
| Other Feedback | `[target.kind, target.name, frameStart, frameEnd, side ?? null]` |
|
|
1514
|
+
|
|
1515
|
+
Capture IDs, hashes and crop bytes stay in the raw anchor and do not enter the
|
|
1516
|
+
logical label. This keeps wording stable when a later Apply recaptures the same
|
|
1517
|
+
target. Consumer projection never serializes a synthetic historical act/session.
|
|
1518
|
+
|
|
1519
|
+
The standalone schema constants are `REVIEW_COMMENTS_SESSION_SCHEMA` =
|
|
1520
|
+
`rig-review-session/2`, `REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA` =
|
|
1521
|
+
`rig-review-compare-session/2`, and `PARTS_COMMENTS_VERDICT_SCHEMA` =
|
|
1522
|
+
`rig-review-parts-verdict/5`. Session/2 replaces `feedback` with `comments` and
|
|
1523
|
+
checkpoint note entries with outcome-only entries. Compare/2 replaces `feedback`
|
|
1524
|
+
with `comments`, requires an explicit side on Feedback anchors and checks its
|
|
1525
|
+
existing binding hash. Parts/5 replaces `issues` with `comments`, deriving the
|
|
1526
|
+
issue relation from Parts anchors. Other existing envelope/provenance fields
|
|
1527
|
+
remain. `projectSelectedCommentsFeedback` selects exactly one Feedback
|
|
1528
|
+
`anchor.id` and returns that anchor plus the scalar projection of its entry for
|
|
1529
|
+
existing correction-writer arguments. The original new-session stdout remains
|
|
1530
|
+
the immutable evidence.
|
|
1531
|
+
|
|
1532
|
+
Historical @2–@5 acts, session/1, compare-session/1, Parts/4 and survey records
|
|
1533
|
+
stay on their original readers, raw bytes, hashes, stills and replay paths.
|
|
1534
|
+
Display adaptation of old user feedback creates one general comment per existing
|
|
1535
|
+
summary/note/words field, including empty strings; it never rewrites history or
|
|
1536
|
+
reclassifies survey answers. Legacy correction summaries remain literal. Create's
|
|
1537
|
+
old Parts names projection gives a present `issues[]` precedence even for /1-/2;
|
|
1538
|
+
only absent `issues[]` uses `part.note`. Literal-byte controls and all eighteen
|
|
1539
|
+
cross-repository oracle outcomes belong in the PR evidence. Parser-only native
|
|
1540
|
+
coverage does not substitute for Create's actual ingest/replay receipt or owner
|
|
1541
|
+
working-screen review.
|
|
1542
|
+
|
|
1543
|
+
### Comment context (act@7)
|
|
1544
|
+
|
|
1545
|
+
`JOB_COMMENT_CONTEXT_ACT_SCHEMA` is `rig-review/act@7` ([#714](https://github.com/rig-c/review/issues/714)).
|
|
1546
|
+
It is the @6 envelope, kinds, value keys and checks with one addition: each
|
|
1547
|
+
comment entry may carry an optional `context` object after `text` and `anchor`.
|
|
1548
|
+
`context` records where the comment was made so opening it can restore that
|
|
1549
|
+
view. It is not part of the signed projection: `projectComments` covers `text`
|
|
1550
|
+
and `anchor` only. `parseContextCommentsAct` decodes @7 only; `parseCommentsAct`
|
|
1551
|
+
still decodes @6 only and refuses `context`. @2–@6 bytes, hashes and readers do
|
|
1552
|
+
not change.
|
|
1553
|
+
|
|
1554
|
+
`context` is closed and nonempty. Every key is optional and copies a value an
|
|
1555
|
+
existing pin or restore path already carries:
|
|
1556
|
+
|
|
1557
|
+
| Key | Shape | Existing source |
|
|
1558
|
+
| --- | --- | --- |
|
|
1559
|
+
| `subject` | `{ask, sourceHash, selector?}` | the ask's `JobSubject`, the act source's `sourceHash` and `selector`. `ask.kind` must equal the act `kind`; `sourceHash` and `selector` must equal the act source (`JOB_ACT_INVALID`) |
|
|
1560
|
+
| `mode` | `setup`, `animate` or `compare` | StageComment `mode`, bookmark `selection.mode` |
|
|
1561
|
+
| `tab` | `view`, `rig`, `playback` or `feedback` | bookmark `selection.inspector` |
|
|
1562
|
+
| `part` | ControlPart `{side, slot, mode, identity?}` | bookmark `selection.part` (absent, never `null`) |
|
|
1563
|
+
| `region` | world-space `{x, y, width, height}` | StageComment `world`, PartsIssue `rigRegion` |
|
|
1564
|
+
| `viewMode` | `item` or `assembled` | PartsIssue `view.mode` |
|
|
1565
|
+
| `camera` | numeric camera `{space, center, zoom, viewport, visible}` | StageComment `camera` |
|
|
1566
|
+
| `frame` | `{index, basis}` (`producer` or `reference`) | StageComment `frame` (absent when time-only) |
|
|
1567
|
+
|
|
1568
|
+
Each key reuses the decoder of the shape it copies. A `reopen` act has no ask
|
|
1569
|
+
subject, so its comments cannot carry `context.subject`.
|
|
1570
|
+
|
|
1571
|
+
Create refuses unknown fields, so Review emits @7 only when
|
|
1572
|
+
`EMIT_UNPINNED_CREATE_FIELDS` (`src/create-pin-gate.ts`) is true. It is false
|
|
1573
|
+
until the create tower confirms Create has pinned the Review version that reads
|
|
1574
|
+
@7. While it is false, writers drop every `context` and emit @6.
|