@rig-c/review 2.13.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/PARTS_VIEW.md +1 -1
- package/docs/REVIEW_PACKAGE.md +32 -91
- package/docs/STABILITY.md +27 -194
- package/docs/WORKFLOWS.md +0 -107
- package/package.json +1 -1
- package/skills/rig-review/SKILL.md +11 -25
- package/src/build.ts +2 -2
- package/src/direction-inspection.ts +6 -2
- package/src/front.ts +4 -193
- package/src/interview-scene.ts +3 -3
- package/src/job-act.ts +1 -35
- package/src/job-api.ts +27 -19
- package/src/job-cli.ts +3 -3
- package/src/job-contract.ts +14 -50
- package/src/job-front.ts +17 -44
- package/src/job-host.ts +1 -4
- package/src/job-session.ts +22 -10
- package/src/job-source.ts +3 -17
- package/src/job-store.ts +80 -6
- package/src/job-worker.ts +1 -47
- package/src/manifest.ts +23 -4
- package/src/open.ts +2 -3
- package/src/scene-inspection.ts +50 -0
- package/src/server.ts +1 -1
- package/web/catalog-en.ts +37 -27
- package/web/catalog-ko.ts +37 -27
- package/web/compare.css +0 -4
- package/web/direction-panel.ts +22 -6
- package/web/inspector-blocks.ts +8 -4
- package/web/job-rig-capture.ts +62 -12
- package/web/job-rig-screen.ts +75 -55
- package/web/job-session.ts +89 -1091
- package/web/main.ts +113 -56
- package/web/parts-viewport-provider.ts +8 -3
- package/web/retained-frame-stage.ts +7 -7
- package/web/rig-host.ts +5 -3
- package/web/rig-viewport-provider.ts +2 -0
- package/web/scene-plates.ts +57 -4
- package/web/styles.css +12 -82
- package/web/viewport-capture.ts +12 -2
- package/web/workspace-ui.ts +5 -6
- package/src/front-worker.ts +0 -2
- package/src/job-hub.ts +0 -304
- package/src/job-image-set.ts +0 -73
- package/web/job-hub.ts +0 -160
package/README.md
CHANGED
|
@@ -44,7 +44,7 @@ the same CLI. `@rig-c/review` remains the canonical package.
|
|
|
44
44
|
|
|
45
45
|
`rig-review` runs under **Bun 1.3.0 or later**, which must be on `PATH`; CI runs the installed package on 1.3.0 and on the latest Bun. `open` prints a loopback URL and exits; see [One-command owner handoff](#one-command-owner-handoff). `npx rig-review --help` lists every command.
|
|
46
46
|
|
|
47
|
-
The CLI and `@rig-c/review/job-host` support owner hosting
|
|
47
|
+
The CLI and `@rig-c/review/job-host` support owner hosting. See [Public API stability](docs/STABILITY.md) for exports and signatures.
|
|
48
48
|
|
|
49
49
|
Example stdout from `open` (private capability omitted):
|
|
50
50
|
|
package/docs/PARTS_VIEW.md
CHANGED
|
@@ -469,7 +469,7 @@ uses the individual part view described below.
|
|
|
469
469
|
draw, alpha picking, hidden layers, pan and camera preservation. `tests/parts-comments-browser.ts`
|
|
470
470
|
covers assembled seam capture, chip edits, saved-view restoration, crop evidence and source immutability
|
|
471
471
|
in both languages. `tests/parts-mesh-browser.ts` covers the global mesh control and unavailable states.
|
|
472
|
-
The live job host's `tests/job-
|
|
472
|
+
The live job host's `tests/job-image-screen-browser.ts` covers the same mount through submission and reconnect.
|
|
473
473
|
|
|
474
474
|
## Draft mesh correction connection
|
|
475
475
|
|
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -37,7 +37,7 @@ The illustrative `look` animation in `axes` must also be declared in `animations
|
|
|
37
37
|
|
|
38
38
|
## Files and references
|
|
39
39
|
|
|
40
|
-
Every path is a literal relative path, including `model`, optional `direction` 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
|
|
|
@@ -1029,14 +1029,30 @@ loaded through Play. Independent depth control is unavailable on this surface.
|
|
|
1029
1029
|
|
|
1030
1030
|
A manifest may declare `direction` as the literal package-relative path to a
|
|
1031
1031
|
retained Create `rig-create/direction@1` or `rig-create/direction@2` document
|
|
1032
|
-
(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.
|
|
1033
1049
|
Preserve the document's model path relative to the Review package root. Review
|
|
1034
1050
|
requires that path and SHA-256 to match the inspected compiled model and
|
|
1035
1051
|
includes the direction file in the package source hash. The panel shows authored
|
|
1036
|
-
|
|
1052
|
+
take and planes read-only while that inspected model is on stage. Create
|
|
1037
1053
|
remains responsible for validating project history and citations. Viewport pan
|
|
1038
|
-
and zoom affect only inspection.
|
|
1039
|
-
|
|
1054
|
+
and zoom affect only inspection. Camera Apply remains unavailable; authored
|
|
1055
|
+
camera playback requires the declared scene above.
|
|
1040
1056
|
|
|
1041
1057
|
The optional `sets` manifest path names a package-local Play attachment-set
|
|
1042
1058
|
sidecar for the inspected single-package build. Review includes it in the
|
|
@@ -1044,7 +1060,7 @@ source hash and loads its sets through the published runtime. Scratch builds
|
|
|
1044
1060
|
use their own model and do not inherit the inspected build's sidecar. Compare
|
|
1045
1061
|
and standalone parts retain their existing inspection surfaces.
|
|
1046
1062
|
|
|
1047
|
-
|
|
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.
|
|
1048
1064
|
|
|
1049
1065
|
### Scene interview records
|
|
1050
1066
|
|
|
@@ -1080,56 +1096,6 @@ or establish official Create writer acceptance.
|
|
|
1080
1096
|
|
|
1081
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.
|
|
1082
1098
|
|
|
1083
|
-
### Embedded N-job owner
|
|
1084
|
-
|
|
1085
|
-
`startJobHub` and `hub.openJob` from `@rig-c/review/job-host` add one
|
|
1086
|
-
process-local embedded owner for N semantic jobs. One PID/listener serves one
|
|
1087
|
-
human owner URL and job list, with a common bootstrap-declared reviewer.
|
|
1088
|
-
The existing job-api@2/act@2 schemas apply independently to each job's identity,
|
|
1089
|
-
source binding, generation, idempotency, grants, pending asks, finalized acts,
|
|
1090
|
-
display acknowledgment and replay cursor. Hub-selected frames use the current
|
|
1091
|
-
`?hub=<incarnation>` query with optional literal `lang=en` or `lang=ko`. The
|
|
1092
|
-
normal cycle remains `publish`,
|
|
1093
|
-
`ask`, `next`, direct writer `fetch-act`, and explicit `close`.
|
|
1094
|
-
|
|
1095
|
-
Trusted `readPublished`, `partsEnumerator` and `installWriterBinding` hooks are
|
|
1096
|
-
registered in the owning process with the existing declared IDs. Owner-list
|
|
1097
|
-
access requires the private hub capability. Each job separately authenticates
|
|
1098
|
-
agent, UI and read-only writer requests. The reviewer binding records trusted
|
|
1099
|
-
bootstrap provenance. Supplied sources stay immutable, and agents never create
|
|
1100
|
-
internal Review state, act files or writer binding files.
|
|
1101
|
-
|
|
1102
|
-
Each `startJobHub` listener start mints one shared canonical lowercase UUIDv4
|
|
1103
|
-
`listenerIncarnation` across all jobs registered on that hub. Opening additional
|
|
1104
|
-
jobs preserves that incarnation, and stopping and restarting the hub rotates
|
|
1105
|
-
`listenerIncarnation` alongside the hub capability and `workspace` query. Each
|
|
1106
|
-
`hub.openJob` call returns a required non-null detached deeply frozen
|
|
1107
|
-
`job.attachment: JobHostReuseExpectation` derived directly from the owning hub
|
|
1108
|
-
context, including when a compact on-disk `job-ui/<jobId>.json` descriptor omits
|
|
1109
|
-
`listenerIncarnation` at the 65,536-byte limit. Passing a runtime
|
|
1110
|
-
`reuseOnly` property to `hub.openJob` rejects with `JOB_REQUEST_INVALID`
|
|
1111
|
-
(`JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer' | 'reuseOnly'>`).
|
|
1112
|
-
|
|
1113
|
-
Closing one job revokes its writer grant while other jobs and the shared owner
|
|
1114
|
-
continue. `await hub.stop()` stops transport and disposes sessions while
|
|
1115
|
-
preserving active durable jobs and their grants. Restart re-registers the
|
|
1116
|
-
required callbacks and refreshes writer origins. Active job identity and grants
|
|
1117
|
-
persist, while the hub capability, `listenerIncarnation` and `workspace`
|
|
1118
|
-
incarnation query rotate and invalidate prior strict `reuseOnly` expectations.
|
|
1119
|
-
Closed retained entries count toward the current hub's 32-entry application
|
|
1120
|
-
bound. The bound provides no hardware performance guarantee.
|
|
1121
|
-
|
|
1122
|
-
Compatible same-job `startJobHost` attachment remains supported via both
|
|
1123
|
-
ordinary authenticated reuse and strict `reuseOnly: {expected}` attachment,
|
|
1124
|
-
which skips `installWriterBinding` during strict bootstrap. Hub registration
|
|
1125
|
-
refuses an active external standalone owner with `JOB_HUB_EXTERNAL_HOST` and a
|
|
1126
|
-
live unresponsive owner with `JOB_HUB_HOST_UNRESPONSIVE`. General cross-process
|
|
1127
|
-
callback registration remains deferred. External consumer-owned adoption remains
|
|
1128
|
-
pending in [Review #512](https://github.com/rig-c/review/issues/512). Public
|
|
1129
|
-
signatures and the host-owned integration example are in
|
|
1130
|
-
[Public API stability](STABILITY.md#embedded-semantic-job-hub) and
|
|
1131
|
-
[Embedded semantic jobs](WORKFLOWS.md#embedded-semantic-jobs).
|
|
1132
|
-
|
|
1133
1099
|
### Vocabulary, authority, CLI and host ports
|
|
1134
1100
|
|
|
1135
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.
|
|
@@ -1170,49 +1136,22 @@ signatures and the host-owned integration example are in
|
|
|
1170
1136
|
- **`interview-picks`.** `JobActValues['interview-picks']` carries `questionId`, ordered `selections` (`itemId`, `optionId`, nullable `otherText`) and `note`, with non-null `source.optionSet` (`id` and `sha256`).
|
|
1171
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.
|
|
1172
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`).
|
|
1173
|
-
- **`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.
|
|
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.
|
|
1174
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.
|
|
1175
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.
|
|
1176
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.
|
|
1177
1143
|
|
|
1178
|
-
### Image-set publication and human comparison
|
|
1179
|
-
|
|
1180
|
-
Before asking, agents read `next.value.capabilities.imageSetVerdict` through the
|
|
1181
|
-
existing authenticated semantic API or `session next` CLI and require true with
|
|
1182
|
-
`assertJobImageSetCapability`. Hub metadata carries the same capability. Missing
|
|
1183
|
-
support refuses locally with `JOB_IMAGE_SET_UNSUPPORTED`, while the frozen older
|
|
1184
|
-
parser rejects the new stage with `JOB_ASK_INVALID`.
|
|
1185
|
-
|
|
1186
|
-
The trusted publication reader returns optional `imageSet` with purpose
|
|
1187
|
-
`plate-adoption` and 2–8 ordered `{role, name, path, sha256?}` rows. It uses the
|
|
1188
|
-
existing producer-held frozen record callback, with no inferred plate schema.
|
|
1189
|
-
Exactly one source, at least one candidate and optional references are allowed.
|
|
1190
|
-
Names and job-root-relative paths are unique, contained and symlink-checked.
|
|
1191
|
-
The daemon validates supplied hashes, retains exact bytes and rechecks them at
|
|
1192
|
-
ask and finalize. The hub displays the images side by side in producer order,
|
|
1193
|
-
with their names, roles and hashes. Decode and paint precede display acknowledgment.
|
|
1194
|
-
Equal bytes remain visible and are flagged in `source.duplicateHashes`.
|
|
1195
|
-
|
|
1196
|
-
Image acts carry `source.imageSetDigest`, SHA-256 of UTF-8
|
|
1197
|
-
`JSON.stringify(images.map(({role, name, sha256}) => ({role, name, sha256})))`.
|
|
1198
|
-
Exact key order, array order and Unicode strings are preserved. Paths remain in
|
|
1199
|
-
the source identity and are excluded from that ordered-list digest. The
|
|
1200
|
-
image-only source hash additionally binds the frozen record. Optional image notes
|
|
1201
|
-
use exact member names and human words. Every source identity and digest is
|
|
1202
|
-
server-derived. Consumer fetch, human authority, drafts, nonce and cursor rules
|
|
1203
|
-
apply through the existing cycle. [Public shapes and refusals](STABILITY.md#image-set-verdict-extension).
|
|
1204
|
-
|
|
1205
1144
|
### Rig verdict still backend
|
|
1206
1145
|
|
|
1207
1146
|
New rig-review verdicts use `rig-review/act@3` and a top-level `still` with `path`, `sha256`, `camera:"fixed"` and `frame`. The path is exactly `<sha256>.png`. Setup uses `frame:"setup"`. Numeric seconds require `animation` alongside the frame. Other new acts and historical rig acts retain act@2. `JOB_ACT_SCHEMA`, API@2, stored compatibility markers and the twelve public facade runtime exports retain their established values. The rig-specific revision constant is internal to the contract module. Public type exports include `JobRigReviewAct`, `JobRigStill` and `JobRigCapture`.
|
|
1208
1147
|
|
|
1209
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.
|
|
1210
1149
|
|
|
1211
|
-
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.
|
|
1212
1151
|
|
|
1213
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.
|
|
1214
1153
|
|
|
1215
|
-
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.
|
|
1216
1155
|
|
|
1217
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.
|
|
1218
1157
|
|
|
@@ -1227,7 +1166,7 @@ The manifest and complete retained image rows enter the composite source hash. L
|
|
|
1227
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.
|
|
1228
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.
|
|
1229
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.
|
|
1230
|
-
- **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.
|
|
1231
1170
|
|
|
1232
1171
|
### Model-free record mode and source seam
|
|
1233
1172
|
|
|
@@ -1235,13 +1174,13 @@ The manifest and complete retained image rows enter the composite source hash. L
|
|
|
1235
1174
|
|
|
1236
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).
|
|
1237
1176
|
|
|
1238
|
-
`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.
|
|
1239
1178
|
|
|
1240
1179
|
| Surface | Exact keys or closed values |
|
|
1241
1180
|
| --- | --- |
|
|
1242
1181
|
| `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
|
|
1243
1182
|
| `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
|
|
1244
|
-
| `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`), `{kind: 'reopen', stage}` |
|
|
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}` |
|
|
1245
1184
|
| `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
|
|
1246
1185
|
| `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
|
|
1247
1186
|
| `RecordSource` | Required `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
|
|
@@ -1252,6 +1191,8 @@ The read-only official reader returns the six-key `RecordPublishedContext` with
|
|
|
1252
1191
|
|
|
1253
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)).
|
|
1254
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
|
+
|
|
1255
1196
|
### Optional sealed checkpoint evidence
|
|
1256
1197
|
|
|
1257
1198
|
The trusted `JobPublicationReader` package context and the record reader's
|
|
@@ -1261,7 +1202,7 @@ share this declaration. It is admitted only through the trusted reader and its
|
|
|
1261
1202
|
exact work-root-relative file closure. Each packet binds an admitted checkpoint
|
|
1262
1203
|
subject to an existing plan step. Package aliases use the subject's
|
|
1263
1204
|
`planStepId ?? checkpointId`. Record checkpoints use the same checkpoint and plan
|
|
1264
|
-
step ID.
|
|
1205
|
+
step ID. Option-set publications refuse this extension.
|
|
1265
1206
|
|
|
1266
1207
|
The collection contains ordered packets with exactly these fields.
|
|
1267
1208
|
|
|
@@ -1307,7 +1248,7 @@ Text permits LF and tab and refuses other ASCII control characters. Present
|
|
|
1307
1248
|
`undefined`, null and empty evidence collections refuse. Missing required keys,
|
|
1308
1249
|
unknown packet/tile/table/document keys, duplicate identities, nested cells and
|
|
1309
1250
|
incorrect row widths refuse. Absent evidence stays omitted in normalized
|
|
1310
|
-
contexts, sources, metadata and stored state. Existing 512 KiB event, 2 MiB owner
|
|
1251
|
+
contexts, sources, metadata and stored state. Existing 512 KiB event metadata (full consumer acts follow #790), 2 MiB owner
|
|
1311
1252
|
metadata and 16 MiB durable-document delivery/admission limits remain in force.
|
|
1312
1253
|
The declaration and table bounds leave room for existing metadata and events.
|
|
1313
1254
|
Existing closure file count and total retained-byte limits also apply.
|
package/docs/STABILITY.md
CHANGED
|
@@ -146,7 +146,6 @@ interface JobPublishedContext {
|
|
|
146
146
|
readonly selector: JobSelector | null;
|
|
147
147
|
readonly plan: JobPlanIdentity | null;
|
|
148
148
|
readonly parts: JobPartsIdentity | null;
|
|
149
|
-
readonly imageSet?: JobImageSetInput;
|
|
150
149
|
readonly subjects: readonly JobSubject[];
|
|
151
150
|
readonly partIds: readonly string[];
|
|
152
151
|
readonly files: readonly JobFileIdentity[];
|
|
@@ -340,8 +339,7 @@ Failed or aborted reads cancel and release their readers. The server enforces a
|
|
|
340
339
|
|
|
341
340
|
After body parsing, the owner executes a synchronous acceptance section inside a
|
|
342
341
|
deferred SQLite read transaction (`db.transaction(...).deferred()`). It checks
|
|
343
|
-
published, stopped and accepting flags
|
|
344
|
-
`closing`) and request abort, verifies UI capability, active job status and full
|
|
342
|
+
published, stopped and accepting flags and request abort, verifies UI capability, active job status and full
|
|
345
343
|
binding, checks `listenerIncarnation` and captured, current and observed `{dev, ino}`
|
|
346
344
|
identities (`root`, `stateDir`, `store`, `record`) plus exact descriptor bytes,
|
|
347
345
|
rechecks accepting and abort flags, freezes `{ok: true, attachment, pid}` and
|
|
@@ -350,7 +348,7 @@ read snapshot while `sealClose` commits with `BEGIN IMMEDIATE`, acceptance and c
|
|
|
350
348
|
execute in a single serial order. A prior committed close returns HTTP 409 with
|
|
351
349
|
`reason: 'closed'` and `phase: 'acceptance'`. A concurrent close waits for the read
|
|
352
350
|
snapshot, and a close or stop after acceptance is an ordinary subsequent lifecycle
|
|
353
|
-
event.
|
|
351
|
+
event. Owner stop initiated before or during body parsing returns HTTP
|
|
354
352
|
503 with `reason: 'stopped'` and `phase: 'acceptance'`. `JobHostAttachFailure` is a
|
|
355
353
|
closed two-member union of `{code: 'JOB_HOST_ATTACH_REFUSED', reason, phase}`
|
|
356
354
|
(`reason` in `'missing' | 'closed' | 'incarnation-missing' | 'replaced' | 'read' | 'probe' | 'stopped' | 'race'`
|
|
@@ -412,186 +410,9 @@ The runtime entry starts the full owner host with retained publication routes
|
|
|
412
410
|
and shipped HTML, JavaScript and CSS. Raw Requests and the existing A/B ports
|
|
413
411
|
preserve capability, origin, size, cancellation and replay checks.
|
|
414
412
|
|
|
415
|
-
##
|
|
413
|
+
## Changelog
|
|
416
414
|
|
|
417
|
-
`startJobHub`
|
|
418
|
-
`@rig-c/review/job-host` facade. One host process owns one loopback listener and
|
|
419
|
-
one human owner list at `ownerUrl`. Each `openJob` registers its trusted hooks
|
|
420
|
-
in that process and returns the existing session and semantic ports. The jobs
|
|
421
|
-
use `rig-review/job-api@2` and `rig-review/act@2`.
|
|
422
|
-
|
|
423
|
-
```ts
|
|
424
|
-
import {startJobHub} from '@rig-c/review/job-host';
|
|
425
|
-
import type {
|
|
426
|
-
JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub,
|
|
427
|
-
JobHostReuseExpectation,
|
|
428
|
-
} from '@rig-c/review/job-host';
|
|
429
|
-
|
|
430
|
-
function startJobHub(options: JobHubOptions): Promise<JobOwnerHub>;
|
|
431
|
-
|
|
432
|
-
interface JobHubOptions {
|
|
433
|
-
readonly stateDir: string;
|
|
434
|
-
readonly reviewer: JobReviewerBinding;
|
|
435
|
-
readonly port?: number;
|
|
436
|
-
}
|
|
437
|
-
|
|
438
|
-
type JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer' | 'reuseOnly'>;
|
|
439
|
-
|
|
440
|
-
interface JobHubJob {
|
|
441
|
-
readonly session: JobSession;
|
|
442
|
-
readonly ports: JobHostPorts;
|
|
443
|
-
readonly origin: string;
|
|
444
|
-
readonly jobUrl: string;
|
|
445
|
-
readonly reused: boolean;
|
|
446
|
-
readonly attachment: JobHostReuseExpectation;
|
|
447
|
-
}
|
|
448
|
-
|
|
449
|
-
interface JobOwnerHub {
|
|
450
|
-
readonly origin: string;
|
|
451
|
-
readonly ownerUrl: string;
|
|
452
|
-
openJob(options: JobHubJobOptions): Promise<JobHubJob>;
|
|
453
|
-
stop(): Promise<void>;
|
|
454
|
-
}
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
`stateDir` stays outside every registered work root. `port` accepts 0..65535 and
|
|
458
|
-
defaults to an available port. The bootstrap `reviewer` is common to every job,
|
|
459
|
-
with the same trusted provenance and role checks as `startJobHost`. A retained
|
|
460
|
-
active job with a different reviewer refuses `JOB_AUTHORITY_REFUSED`.
|
|
461
|
-
`ownerUrl` has the form `/hub/?workspace=<incarnation>#cap=<private-capability>`.
|
|
462
|
-
`jobUrl` is the per-job owner URL, including its private UI capability.
|
|
463
|
-
The human receives the hub owner URL once. Agents receive their own per-job
|
|
464
|
-
bootstrap credentials privately and address `/jobs/<jobId>/api`.
|
|
465
|
-
|
|
466
|
-
Each `startJobHub` listener start mints one canonical lowercase UUIDv4
|
|
467
|
-
`listenerIncarnation` shared across all jobs registered on that hub. Opening
|
|
468
|
-
additional jobs on the same hub preserves that incarnation. Each `openJob` call
|
|
469
|
-
returns a required non-null detached deeply frozen `job.attachment: JobHostReuseExpectation`
|
|
470
|
-
derived directly from the owning hub context, including when a compact on-disk
|
|
471
|
-
`job-ui/<jobId>.json` descriptor omits `listenerIncarnation` at the 65,536-byte
|
|
472
|
-
limit. Passing a runtime `reuseOnly` property to `hub.openJob` rejects with
|
|
473
|
-
`JOB_REQUEST_INVALID`.
|
|
474
|
-
|
|
475
|
-
Each job keeps its own identity, source bindings, generation CAS, idempotency
|
|
476
|
-
keys, cursors, asks, acts, display receipts and agent/UI/writer grants. Hook IDs
|
|
477
|
-
follow the existing `JobHostOptions` rules. Reopening an active root and
|
|
478
|
-
fingerprint with compatible hook identities returns the same session with
|
|
479
|
-
`reused` true and invokes the writer-binding callback again. General
|
|
480
|
-
cross-process callback registration is deferred. The hub refuses an active
|
|
481
|
-
standalone owner with `JOB_HUB_EXTERNAL_HOST`, and a live unresponsive owner
|
|
482
|
-
with `JOB_HUB_HOST_UNRESPONSIVE`, preserving that owner. A second live hub for
|
|
483
|
-
the state directory refuses `JOB_HUB_ALREADY_RUNNING`. Existing `startJobHost`
|
|
484
|
-
callers can still attach to a compatible hub-owned job by ordinary authenticated
|
|
485
|
-
reuse or strict `reuseOnly: {expected}` attachment (which skips
|
|
486
|
-
`installWriterBinding` during strict bootstrap). Such attachment keeps the
|
|
487
|
-
registered process-local hooks under hub ownership.
|
|
488
|
-
|
|
489
|
-
Semantic `close` ends only the addressed job and revokes its writer grant.
|
|
490
|
-
Closed entries remain in the current hub list. `await hub.stop()` drains work,
|
|
491
|
-
stops the shared transport and disposes local sessions. Active jobs retain their
|
|
492
|
-
durable identity, grants, publications, asks, acts and replay history across
|
|
493
|
-
that transport stop. Restart requires `startJobHub` and `openJob` for each
|
|
494
|
-
required job, registering callbacks again and refreshing the writer adapter's
|
|
495
|
-
origin. The hub capability, `listenerIncarnation` and `workspace` incarnation
|
|
496
|
-
query rotate, forcing a fresh owner document and invalidating prior strict
|
|
497
|
-
`reuseOnly` expectations. Obtain the new owner URL and `job.attachment` from the
|
|
498
|
-
new handle. The retained active job's grants keep their identity until
|
|
499
|
-
semantic close. A later new job receives new grants.
|
|
500
|
-
|
|
501
|
-
Admission is an application bound of 32 registered entries, including closed
|
|
502
|
-
entries retained in that hub incarnation. `JOB_HUB_LIMIT` refuses a new entry
|
|
503
|
-
at the bound. Compatible reuse of an active entry still succeeds. Selected
|
|
504
|
-
frames are retained lazily under this bound. Hidden hub members suspend their event subscription after bootstrap and resume from the last delivered cursor when selected. Hardware performance requires its
|
|
505
|
-
own measurement.
|
|
506
|
-
|
|
507
|
-
Consumer-owned adoption remains external and pending in
|
|
508
|
-
[Review #512](https://github.com/rig-c/review/issues/512). See the
|
|
509
|
-
[embedded consumer example](WORKFLOWS.md#embedded-semantic-jobs) for trusted-hook
|
|
510
|
-
ownership and the ordinary semantic cycle.
|
|
511
|
-
|
|
512
|
-
## Image-set verdict extension
|
|
513
|
-
|
|
514
|
-
Review #522 adds an HQ-approved image branch to `rig-review/job-api@2` and
|
|
515
|
-
`rig-review/act@2`. The original model source and value keep their exact fields
|
|
516
|
-
and serialization. Model acts carry no image discriminant, digest, duplicate
|
|
517
|
-
array or added nulls. The image branch carries `source.subject = "image-set"`
|
|
518
|
-
and omits `model` and `selector` entirely. Its ask and value use
|
|
519
|
-
`{kind: "review-verdict", stage: "image-review"}` and the existing human UI
|
|
520
|
-
verdict lifecycle. HQ exact-head dependency sign-off is required before landing.
|
|
521
|
-
The current `src/job-contract.ts` candidate SHA-256 is
|
|
522
|
-
`e7d2be222af6be6cc4718a57fbfef6de606a0c6268efc7b32b15e1bd75bcce65`.
|
|
523
|
-
The Tower records the final signed head separately.
|
|
524
|
-
|
|
525
|
-
Agents discover support through `session next <job-url> --wait-ms 0`, reading
|
|
526
|
-
`response.value.capabilities.imageSetVerdict === true`. API callers send the
|
|
527
|
-
existing `next` request with their agent bearer capability. The authenticated
|
|
528
|
-
hub `/hub/host` and owner `/hub/api/jobs` metadata also advertise that capability.
|
|
529
|
-
`JOB_CAPABILITIES` is the current immutable capability object.
|
|
530
|
-
`assertJobImageSetCapability(response.value.capabilities)` throws
|
|
531
|
-
`JOB_IMAGE_SET_UNSUPPORTED` when support is absent. Call it before asking.
|
|
532
|
-
An older installed parser refuses `image-review` with `JOB_ASK_INVALID`.
|
|
533
|
-
The preserved parser control uses its exact original function body and shared
|
|
534
|
-
current validators. It does not run an older server.
|
|
535
|
-
|
|
536
|
-
The trusted `JobPublicationReader` may return optional `imageSet` in its
|
|
537
|
-
`JobPublishedContext`. The existing callback runs only when publication supplies
|
|
538
|
-
a non-null frozen record. A Create root still requires its producer-owned reader.
|
|
539
|
-
Review defines this return value, with no new producer record format or Parts
|
|
540
|
-
adoption adapter. `result.selector` is null for image publication.
|
|
541
|
-
|
|
542
|
-
```ts
|
|
543
|
-
interface JobImageSetInput {
|
|
544
|
-
readonly purpose: 'plate-adoption';
|
|
545
|
-
readonly images: readonly {
|
|
546
|
-
readonly role: 'source' | 'candidate' | 'reference';
|
|
547
|
-
readonly name: string;
|
|
548
|
-
readonly path: string;
|
|
549
|
-
readonly sha256?: string;
|
|
550
|
-
}[];
|
|
551
|
-
}
|
|
552
|
-
function assertJobImageSetCapability(capabilities: unknown): void;
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
The ordered set has 2–8 rows, exactly one `source`, at least one `candidate`, and
|
|
556
|
-
optional `reference` rows. Names and paths must each be unique. Names use the
|
|
557
|
-
existing nonempty 128-unit text bound. Paths are literal job-root-relative paths
|
|
558
|
-
with the existing 4096-unit bound and regular-file, containment and symlink
|
|
559
|
-
checks. Files retain the existing 64 MiB per-file and 256 MiB total source limits.
|
|
560
|
-
Every supplied hash must match disk bytes. The daemon hashes retained inputs,
|
|
561
|
-
seals them, derives ask bindings from checked disk bytes and rechecks at finalize.
|
|
562
|
-
Equal hashes are allowed and produce ordered `source.duplicateHashes` groups of
|
|
563
|
-
`{names: string[], sha256: string}`. Groups appear by first hash occurrence and
|
|
564
|
-
names retain producer order. An empty group array is explicit on image sources.
|
|
565
|
-
|
|
566
|
-
`source.imageSet` contains required derived hashes. `source.imageSetDigest` is
|
|
567
|
-
SHA-256 over the UTF-8 bytes of the following exact JSON serialization.
|
|
568
|
-
|
|
569
|
-
```ts
|
|
570
|
-
JSON.stringify(images.map(({role, name, sha256}) => ({role, name, sha256})))
|
|
571
|
-
```
|
|
572
|
-
|
|
573
|
-
Property order is `role`, `name`, `sha256`. Array order and strings remain exact,
|
|
574
|
-
with no whitespace insertion or Unicode normalization. Paths are excluded from
|
|
575
|
-
this digest. The separate source hash binds the package source hash, frozen
|
|
576
|
-
record and complete image set including paths under `rig-review-job-image-set/1`.
|
|
577
|
-
Consumers can hash their designated bytes and reconstruct the ordered digest
|
|
578
|
-
without parsing Review's private files.
|
|
579
|
-
|
|
580
|
-
The image value is `{stage: "image-review", verdict, words, imageNotes?}`.
|
|
581
|
-
Optional notes are `{name, words}` rows with unique member names and exact human
|
|
582
|
-
text. Unknown fields, duplicate names and nonmember notes refuse. The UI omits
|
|
583
|
-
empty optional notes and preserves whitespace-only notes. Source hashes, digests,
|
|
584
|
-
duplicate groups and authority are daemon-owned and rejected in UI values.
|
|
585
|
-
All images decode and reach the existing painted lifecycle boundary before
|
|
586
|
-
`ackDisplayed` supplies a nonce and enables submission. Retained routes serve only
|
|
587
|
-
sealed indexed image rows. Drafts, visibility messages, replay and writer-owned
|
|
588
|
-
`fetch-act` keep their existing publication/source and capability bindings.
|
|
589
|
-
|
|
590
|
-
New named refusals are `JOB_IMAGE_SET_UNSUPPORTED`, `JOB_IMAGE_SET_INVALID`,
|
|
591
|
-
`JOB_IMAGE_SET_DUPLICATE_NAME`, `JOB_IMAGE_SET_DUPLICATE_PATH`,
|
|
592
|
-
`JOB_IMAGE_SET_ROLE_INVALID` and `JOB_IMAGE_SET_PATH_REFUSED`.
|
|
593
|
-
Disk hash mismatches use `JOB_SOURCE_MISMATCH`. A verdict ask with neither a valid
|
|
594
|
-
model binding nor a valid image-set binding uses `JOB_ASK_INVALID`.
|
|
415
|
+
- Breaking, next cut 4.0.0 (#806): remove `startJobHub` and its `JobHubOptions`, `JobHubJobOptions`, `JobHubJob` and `JobOwnerHub` types; the uncalled semantic-job hub is deleted.
|
|
595
416
|
|
|
596
417
|
## Named export inventory
|
|
597
418
|
|
|
@@ -638,8 +459,6 @@ The exact runtime exports are listed below. Constants preserve their literal
|
|
|
638
459
|
values from the frozen semantic contract.
|
|
639
460
|
|
|
640
461
|
- `startJobHost`
|
|
641
|
-
- `startJobHub`
|
|
642
|
-
- `assertJobImageSetCapability`
|
|
643
462
|
- `parseRecordAct`
|
|
644
463
|
- `prepareJobRecordAct`
|
|
645
464
|
- `prepareJobRecordSource`
|
|
@@ -670,13 +489,9 @@ values from the frozen semantic contract.
|
|
|
670
489
|
|
|
671
490
|
The exact type-only exports follow. Their existing definitions in
|
|
672
491
|
`src/job-contract.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-session.ts`,
|
|
673
|
-
`src/job-worker.ts
|
|
492
|
+
`src/job-worker.ts` and `src/job-front.ts` are reexported
|
|
674
493
|
without aliases or copied wire shapes.
|
|
675
494
|
|
|
676
|
-
- `JobHubOptions`
|
|
677
|
-
- `JobHubJobOptions`
|
|
678
|
-
- `JobHubJob`
|
|
679
|
-
- `JobOwnerHub`
|
|
680
495
|
- `JobHostOptions`
|
|
681
496
|
- `JobOwnerHost`
|
|
682
497
|
- `JobHostListenerIncarnation`
|
|
@@ -710,13 +525,9 @@ without aliases or copied wire shapes.
|
|
|
710
525
|
- `JobSelector`
|
|
711
526
|
- `JobSourceBinding`
|
|
712
527
|
- `JobModelSourceBinding`
|
|
713
|
-
- `JobImageSourceBinding`
|
|
714
|
-
- `JobImageSetInput`
|
|
715
|
-
- `JobImageSet`
|
|
716
528
|
- `JobCapabilities`
|
|
717
529
|
- `JobCapabilitiesV3`
|
|
718
530
|
- `JobModelReviewValue`
|
|
719
|
-
- `JobImageReviewValue`
|
|
720
531
|
- `JobReviewerBinding`
|
|
721
532
|
- `JobHumanAuthority`
|
|
722
533
|
- `JobVerdict`
|
|
@@ -864,3 +675,25 @@ installed manifest and requires the public import to fail for that missing
|
|
|
864
675
|
subpath. It restores the exact manifest bytes, verifies their SHA-256 and imports
|
|
865
676
|
again. The smoke prints the planned RED's raw exit and diagnostic. This control
|
|
866
677
|
runs inside the ordinary installed smoke, alongside existing CLI coverage.
|
|
678
|
+
|
|
679
|
+
## Record direction-review signoff
|
|
680
|
+
|
|
681
|
+
Record publications accept `{kind: 'signoff', stage: 'direction-review'}` through
|
|
682
|
+
the existing signoff path. Like `plan-approved`, `rigging-interview` and
|
|
683
|
+
`post-interview`, it requires a declared subject and non-empty published plan.
|
|
684
|
+
Approval binds the frozen record revision through the existing project/source
|
|
685
|
+
hashes, with no separate post-version selector or new ask/act field. Existing
|
|
686
|
+
stages, schemas and stored act bytes retain their meaning. See the
|
|
687
|
+
[record contract](REVIEW_PACKAGE.md#model-free-record-mode-and-source-seam).
|
|
688
|
+
|
|
689
|
+
The public `JOB_PLAN_BOUND_SIGNOFF_STAGES` remains the original three-entry
|
|
690
|
+
package list. The fourth stage is record-only; package `direction-review`
|
|
691
|
+
signoffs and historical comments acts still accept a nullable plan.
|
|
692
|
+
|
|
693
|
+
## Record interview signoff
|
|
694
|
+
|
|
695
|
+
Record publications also accept `{kind: 'signoff', stage: 'interview'}` through
|
|
696
|
+
the existing modal and record act shape. A declared subject and non-empty displayed
|
|
697
|
+
plan remain required. The record stage type has five members; the public package
|
|
698
|
+
plan-bound list remains at three. Package interview signoffs and historical acts
|
|
699
|
+
retain their existing nullable-plan behavior. No schema or runtime export changes.
|