rig-review 1.16.6 → 1.17.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 +2 -1
- package/docs/DESIGN.md +11 -0
- package/docs/REVIEW_PACKAGE.md +75 -3
- package/docs/WORKFLOWS.md +52 -0
- package/package.json +7 -7
- package/skills/rig-review/SKILL.md +50 -0
- package/src/bones-check.ts +1 -1
- package/src/destination-directory.ts +28 -0
- package/src/entry.ts +59 -0
- package/src/environment-check.ts +1 -1
- package/src/job-act.ts +164 -0
- package/src/job-api.ts +275 -0
- package/src/job-cli.ts +120 -0
- package/src/job-contract.ts +521 -0
- package/src/job-front.ts +443 -0
- package/src/job-session.ts +352 -0
- package/src/job-source.ts +291 -0
- package/src/job-store.ts +163 -0
- package/src/job-worker.ts +56 -0
- package/src/open.ts +4 -3
- package/src/parts-view.ts +7 -13
- package/src/readings-run.ts +1 -1
- package/src/rebuild.ts +1 -1
- package/src/requirements-run.ts +1 -1
- package/src/state-dir.ts +16 -13
- package/src/strip-export.ts +6 -4
- package/web/catalog-en.ts +66 -0
- package/web/catalog-ko.ts +66 -0
- package/web/job-session.ts +1623 -0
- package/web/parts.ts +28 -19
- package/web/scene-plates.ts +95 -0
- package/web/stage-nav.ts +28 -7
- package/web/styles.css +27 -2
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
# @rig-c/review
|
|
14
14
|
|
|
15
|
-
A local workspace for a person to inspect an agent's rig output, compare
|
|
15
|
+
A local workspace for a person to inspect an agent's rig output, compare references, and export issue-ready feedback. The person opens a package or output folder instead of a custom viewer built per rig.
|
|
16
16
|
|
|
17
17
|
The app provides one inspection workspace for setup geometry and motion, compiled-model playback through `@rig-c/play`, local image, video and pose-sequence references, checkpoints, audio audition, and saved structured feedback. **The producer writes motion in scratch; review never authors keys.** Navigation changes inspection time; it never retimes, and review never writes the package's `motion.json`: motion edits are data (config patches, pose maps, retarget flags) the installed producer turns into a scratch build. Meshes are edited in setup space and rebuilt by the producer (`rig-parts remesh --delta`, #100/#135); weights and source art are not edited.
|
|
18
18
|
|
|
@@ -97,3 +97,4 @@ Development and releasing: [Contributing workflows](https://github.com/rig-c/rev
|
|
|
97
97
|
- [Animation inspection](docs/ANIMATION_INSPECTION.md)
|
|
98
98
|
- [Installed-producer fixture](docs/LIVE_FIXTURE.md)
|
|
99
99
|
- [Agent skill](skills/rig-review/SKILL.md)
|
|
100
|
+
- [Live job contract](docs/REVIEW_PACKAGE.md#live-job-contract) and [standing workflow](docs/WORKFLOWS.md#standing-live-job-workflow)
|
package/docs/DESIGN.md
CHANGED
|
@@ -155,6 +155,17 @@ not create pipeline stages or sign-offs. Opening or switching never submits a
|
|
|
155
155
|
verdict, applies an edit or starts a producer job. Interview and Direction name
|
|
156
156
|
their missing consumer contracts; no tools are fabricated for them.
|
|
157
157
|
|
|
158
|
+
### Standing live job boundary
|
|
159
|
+
|
|
160
|
+
`src/job-contract.ts` freezes the semantic live-job boundary (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session open|publish|ask|next|close` CLI (`src/entry.ts`, `src/job-cli.ts`). Public package exports remain `./package.json` only until the public installed managed-host export lands in [Review #489](https://github.com/rig-c/review/issues/489), 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). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
|
|
161
|
+
|
|
162
|
+
- **One standing window and owner visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media remain internal. A missing required visual (`visual.status` set to `'unavailable'`) is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
|
|
163
|
+
- **Human UI authority vs agent verbs.** People submit finalized acts through the browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`) under a bootstrap-declared `reviewer` (`id` and `role` as `'owner'` or `'delegate'`). That reviewer binding is declared by trusted host bootstrap, cannot be typed or overridden in the browser UI, represents provenance rather than keyboard-user authentication, and maps to Create's existing `by` authority. Agents use `publish`, `ask`, `next` and `close` with `expectedGeneration` CAS and `idempotencyKey`. `publish` requires an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record`) held until acknowledgment as a caller obligation, with no watched-root or automatic-close guarantee. Only explicit `close` ends an active job.
|
|
164
|
+
- **Exact displayed source, cursor replay and draft retention.** Finalized acts and job events replay through durable cursors (`next` and `subscribeJob`). The daemon derives `JobSourceBinding` from validated retained bytes and the page-scoped `displayedNonce` receipt rather than browser-supplied hashes. When a new publication updates the displayed source, old local drafts remain retained for their original source binding and are flagged without rebinding onto the new publication.
|
|
165
|
+
- **Enabled vs reserved act kinds.** Five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`) while `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`). Checkpoint acts carry `pass` or `fail` only (`pending` is UI draft only) and require `words` as a string preserved verbatim including empty or whitespace-only text, with `planStepId` copied by the daemon from the validated ask and stage derived by Create. Signoff acts carry `approved` only with required verbatim `words` (empty or whitespace-only allowed) and remain separate from verdicts and Create stage transitions. Plan-bound signoffs (`plan-approved`, `rigging-interview`, `post-interview`) and checkpoints use step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, parts bindings (`JobPartsIdentity`) are limited to the declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal `parts/*.png` images plus exact `painting_in_rig.png` beside `parts.json` (root or project prefix only) — so `figure_mask` is missing and C3 is not yet a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without a Review field parser. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding while unreferenced stale extras are excluded.
|
|
166
|
+
- **Writer-owned sibling fetch, internal host seam and legacy file handoffs.** [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads via a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration), never tracked in version control or unstaged project output, never constructed or carried by agents, dead at explicit `close`, and renewed on each job incarnation. In the internal managed-host startup seam (`startJobHost` in `src/job-front.ts`, kept internal until [Review #489](https://github.com/rig-c/review/issues/489)), hook-bearing host callers declare `readerId` and `bindingId`; equality governs listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside the active cycle. Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files, and existing `--picks-file`, saved verdict path, reshaped feedback JSON and `--verbatim-file` handoffs are legacy/history bypass findings for the active cycle.
|
|
167
|
+
- **Direction scope.** Direction carriage in `#484` is metadata-only and distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) remains parked.
|
|
168
|
+
|
|
158
169
|
Stage 1 in a single compiled inspection with a producer handoff shows the
|
|
159
170
|
handoff's **separated parts and draft meshes**, labelled **Draft rig · structure
|
|
160
171
|
evidence only**. It proves each part's original raster crop against the rig image
|
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -213,7 +213,7 @@ Every edit card states its edit as one config patch; review applies it to a scra
|
|
|
213
213
|
|
|
214
214
|
**`context.readings`.** Feedback written after a readings run carries the pairs of the last finished run: `{schema:"rig-review-readings/1", animation, requests[] (the readings as sent), environment, environmentPassed, builds:{inspected:<model sha256>, scratch:<build id>|null}, compiler:{package, version}, ticks:{inspected, scratch|null}}`; `null` when none ran. Absent and `null` stay valid; a present value must have this shape. The results themselves are not recorded: the AI receiving the review reruns the same `rigc render` readings on the named builds.
|
|
215
215
|
|
|
216
|
-
**Requirements (#113).** `GET /api/requirements` (single review) answers what the handoff's rig spec offers: `{status:"ready"|"unavailable", reason, bones[], slots[], meshes:{<slot>:[mesh attachment]}, slotBones:{<slot>:<bone>}, constraints:[{name, type:"ik"|"transform", bones[], drives[]}], animations:[{name, duration}], scratch:<build id>|null}`. `POST /api/requirements` (same-origin, capability, 64 KiB) takes exactly `{fps, build:"inspected"|"scratch", requirements:[1–64]}`, each requirement an object of at most 12 lower-case keys whose values are names, finite numbers or a `{bone, point}` / `{stage:[x, y]}` target; `may_fold` is refused. Malformed: HTTP 400 `REQUIREMENTS_REQUEST_INVALID`. Which kind, field, name or bar reads is the producer reader's to say. Outcomes (HTTP 200 `{status:"refused", error}`): `MODELING_HANDOFF_MISSING`, `MODELING_INPUT_UNAVAILABLE`, `REQUIREMENTS_NO_SCRATCH`, `MODELING_PRODUCER_NOT_INSTALLED`, `REQUIREMENTS_STATE_INSIDE_PACKAGE`, `REQUIREMENTS_BUSY`. Review writes `{spec:"spine-parts-requirements/1", fps, requirements}` (one-space JSON and a newline) as `requirements.json` in `<state>/requirements/<package hash>/<run id>/` and runs `rig-parts check --rig <the handoff rig, or the latest scratch build's rig spec> --out out --parts <handoff parts> --requirements requirements.json` there; the directory is removed after the run. The job (`GET /api/requirements/<id>`): `{schema:"rig-review-requirements/1", id, status:"running"|"checked"|"refused"|"failed", build, buildId, file:{sha256, size, text}, producer, exitCode, wallMs, rows:[{name, kind, animation, status, measured, least, greatest, worst:{frame, time, text}|null, reason, line}], summary, checkLine, refusals[] (`REQUIREMENTS_*` lines verbatim), problems[] (`CHECK_REQUIREMENT_MET` / `CHECK_REQUIREMENT_MEASURABLE` lines verbatim), error, lines[]}`; rows come from `check.json`'s `requirements` block, else from the printed `NAME: STATUS — …` lines.
|
|
216
|
+
**Requirements (#113).** `GET /api/requirements` (single review) answers what the handoff's rig spec offers: `{status:"ready"|"unavailable", reason, bones[], slots[], meshes:{<slot>:[mesh attachment]}, slotBones:{<slot>:<bone>}, constraints:[{name, type:"ik"|"transform", bones[], drives[]}], animations:[{name, duration}], scratch:<build id>|null}`. `POST /api/requirements` (same-origin, capability, 64 KiB) takes exactly `{fps, build:"inspected"|"scratch", requirements:[1–64]}`, each requirement an object of at most 12 lower-case keys whose values are names, finite numbers or a `{bone, point}` / `{stage:[x, y]}` target; `may_fold` is refused. Malformed: HTTP 400 `REQUIREMENTS_REQUEST_INVALID`. Which kind, field, name or bar reads is the producer reader's to say. Outcomes (HTTP 200 `{status:"refused", error}`): `MODELING_HANDOFF_MISSING`, `MODELING_INPUT_UNAVAILABLE`, `REQUIREMENTS_NO_SCRATCH`, `MODELING_PRODUCER_NOT_INSTALLED`, `REQUIREMENTS_STATE_INSIDE_PACKAGE`, `STATE_DIRECTORY_INVALID`, `REQUIREMENTS_BUSY`. Review writes `{spec:"spine-parts-requirements/1", fps, requirements}` (one-space JSON and a newline) as `requirements.json` in `<state>/requirements/<package hash>/<run id>/` and runs `rig-parts check --rig <the handoff rig, or the latest scratch build's rig spec> --out out --parts <handoff parts> --requirements requirements.json` there; the directory is removed after the run. The job (`GET /api/requirements/<id>`): `{schema:"rig-review-requirements/1", id, status:"running"|"checked"|"refused"|"failed", build, buildId, file:{sha256, size, text}, producer, exitCode, wallMs, rows:[{name, kind, animation, status, measured, least, greatest, worst:{frame, time, text}|null, reason, line}], summary, checkLine, refusals[] (`REQUIREMENTS_*` lines verbatim), problems[] (`CHECK_REQUIREMENT_MET` / `CHECK_REQUIREMENT_MEASURABLE` lines verbatim), error, lines[]}`; rows come from `check.json`'s `requirements` block, else from the printed `NAME: STATUS — …` lines.
|
|
217
217
|
|
|
218
218
|
**Self-targeted requirements (#142).** The panel refuses before Add, as `REQUIREMENTS_SELF_TARGET`, a `contact` whose target is its own bone and point and an `aim` whose target bone is the aimed bone: both measure 0 in every frame and the producer reports them as PASS (its own refusal is rig-c/parts#540). A bone's tip against its own origin is not refused; it measures the bone's length. A fresh contact or aim form proposes a target bone other than the subject (the next bone in rig order).
|
|
219
219
|
|
|
@@ -400,11 +400,11 @@ PNG responses are `image/png` attachment downloads; JSON responses are `applicat
|
|
|
400
400
|
|
|
401
401
|
Only selected-basis report `frameTimes` supplies strip times. A matching report animation is required. Uniform metadata remains supported by inspection transport but does not become a strip sampling substitute. A clockless JSON group keeps its inclusive frames and `time:null`; clockless PNG refuses with `Report has no frameTimes — regenerate with pose 0.30.0 or later`. A compare A without a clock remains renderable from B's explicit times and has no inferred A frame label. Each actual reference PTS is selected nearest to the request (ties earlier), and all rig rows use that same PTS. Requested/decoded times outside the common clip/video domain refuse, without a per-source clamp.
|
|
402
402
|
|
|
403
|
-
Each interval has its own source-row grid; overlapping groups preserve their feedback ids and repeated frames. Source packages and reference are checked before and after export, including exact model/page/motion bytes through existing package hashes. The PNG footer includes full rig/motion hashes (null stays absent), revisions, viewer/runtime and actual renderer versions. Exports are derived evidence, never a new source or approval. CLI destinations and `.json` sidecars must be new files outside
|
|
403
|
+
Each interval has its own source-row grid; overlapping groups preserve their feedback ids and repeated frames. Source packages and reference are checked before and after export, including exact model/page/motion bytes through existing package hashes. The PNG footer includes full rig/motion hashes (null stays absent), revisions, viewer/runtime and actual renderer versions. Exports are derived evidence, never a new source or approval. CLI destinations and `.json` sidecars must be new files. An existing output parent may be reached through a symlink, including macOS `/var`, if the physical destination is outside every source root. An existing destination entry, including a dangling symlink, is refused. Downloads have no arbitrary filesystem destination parameter.
|
|
404
404
|
|
|
405
405
|
The pure layout reserves a maximum `footerHeight` budget for complete provenance. The native renderer wraps the actual footer text before allocation and uses only that measured height; `rendering.width/height` records the actual PNG extent. Unsupported RGB/dark tint refuses by name (`STRIP_UNSUPPORTED_TINT`) rather than claiming Canvas2D pixel parity for features its published renderer omits. Labels and footer use concrete font-family lists, never a generic family (Node Canvas resolves those to the machine's first family); when no family of the mono or sans list is installed, rendering refuses `STRIP_FONT`, naming both lists, before any reference probe or drawing.
|
|
406
406
|
|
|
407
|
-
A strip plan with one clock basis reports `plan.basis:"single"|"a"|"b"`. A comparison batch containing both sides reports `plan.basis:"mixed"`; each group still carries its own `basis` and its own report-derived sample times. Consumers must use the group basis for a mixed plan rather than treating the first group as a batch-wide clock. The selected basis row labels requested producer frames/times; actual PTS and independently calculated actual frames remain separate rendering metadata. Output containment
|
|
407
|
+
A strip plan with one clock basis reports `plan.basis:"single"|"a"|"b"`. A comparison batch containing both sides reports `plan.basis:"mixed"`; each group still carries its own `basis` and its own report-derived sample times. Consumers must use the group basis for a mixed plan rather than treating the first group as a batch-wide clock. The selected basis row labels requested producer frames/times; actual PTS and independently calculated actual frames remain separate rendering metadata. Output containment uses native platform separators, including Windows drive and UNC paths.
|
|
408
408
|
|
|
409
409
|
## Open-managed handoff and explicit single reference
|
|
410
410
|
|
|
@@ -499,6 +499,25 @@ applies the same canonical check and refuses with its own `*_STATE_INSIDE_PACKAG
|
|
|
499
499
|
code naming the folder. No package manifest, source video, motion or compiled
|
|
500
500
|
model is written by open. There is no browser launch or new LAN exposure.
|
|
501
501
|
|
|
502
|
+
Review resolves the existing directory prefix of a state path or explicit
|
|
503
|
+
parts verdict parent. An `ENOENT` suffix can be created when the command needs
|
|
504
|
+
it. A regular file in the directory path (`ENOTDIR`) or a symlink loop
|
|
505
|
+
(`ELOOP`) stops resolution. Parts verdict resolution preserves the original
|
|
506
|
+
output filename, and protected input collisions still refuse by name.
|
|
507
|
+
State guards return `STATE_DIRECTORY_INVALID` through the existing HTTP 200
|
|
508
|
+
refusal response on guarded routes.
|
|
509
|
+
|
|
510
|
+
| Input | Previous behavior | Current behavior |
|
|
511
|
+
| --- | --- | --- |
|
|
512
|
+
| Strip destination under a symlink to an existing directory outside the source roots | `strip.output` refused the symlink with the `without symlinks` suffix | Writes to the physical directory with the original filename |
|
|
513
|
+
| Strip destination with a missing parent | Raw `ENOENT` | `strip.output: parent must be an existing directory` |
|
|
514
|
+
| Strip destination with a loop in its parent path | Raw `ELOOP` if raised during lookup, or the earlier `without symlinks` refusal | `strip.output: parent must be an existing directory` |
|
|
515
|
+
| `open` state path through a regular file or loop | Raw `ENOTDIR` or `ELOOP` | `OPEN_STATE_INVALID` |
|
|
516
|
+
| `control` state path through a regular file or loop | Raw `ENOTDIR` or `ELOOP` | `CONTROL_STATE` |
|
|
517
|
+
| State guard sees a regular file inside the package with a requested suffix | `*_STATE_INSIDE_PACKAGE` | `STATE_DIRECTORY_INVALID` |
|
|
518
|
+
| State guard sees a symlink loop | Raw `ELOOP` | `STATE_DIRECTORY_INVALID` |
|
|
519
|
+
| Parts or atlas verdict parent through a regular file or loop | Raw `ENOTDIR` or `ELOOP` | `PARTS_VERDICT_DESTINATION_INVALID` |
|
|
520
|
+
|
|
502
521
|
The printed feedback retrieval command uses POSIX shell quoting for literal path
|
|
503
522
|
arguments. It is not a PowerShell or cmd.exe command string.
|
|
504
523
|
|
|
@@ -896,6 +915,8 @@ and exact draft skin/slot/attachment address, with named refusal if absent.
|
|
|
896
915
|
|
|
897
916
|
### Correction handoff
|
|
898
917
|
|
|
918
|
+
For the active standing live-job cycle, see [Live job contract](#live-job-contract), [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184). In the active cycle, agents do not build, parse, reshape or carry Review session, picks, verdict or applied-record storage files, while `described-correction` and `mesh-edit` remain reserved disabled act kinds (`JOB_ACT_KIND_DISABLED`). The file-based `--correction`, `--feedback-file`, reshaped feedback JSON and `--verbatim-file` flow below is retained as legacy/history documentation and is a bypass finding if used in the active cycle.
|
|
919
|
+
|
|
899
920
|
The existing feedback context may carry `correction: {path, selector}` on a
|
|
900
921
|
saved single-package item. The path is `described` or `made`. A selector names
|
|
901
922
|
`{stage:"parts-review",kind:"draft",id}`,
|
|
@@ -991,3 +1012,54 @@ sidecar for the inspected single-package build. Review includes it in the
|
|
|
991
1012
|
source hash and loads its sets through the published runtime. Scratch builds
|
|
992
1013
|
use their own model and do not inherit the inspected build's sidecar. Compare
|
|
993
1014
|
and standalone parts retain their existing inspection surfaces.
|
|
1015
|
+
|
|
1016
|
+
In the standing live-job contract ([Review #484](https://github.com/rig-c/review/issues/484)), direction carriage is metadata-only (`source.direction` and the `direction-review` stage on `review-verdict`). That metadata carriage is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) remains parked.
|
|
1017
|
+
|
|
1018
|
+
## Live job contract
|
|
1019
|
+
|
|
1020
|
+
`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@1`) and `JOB_ACT_SCHEMA` (`rig-review/act@1`), 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`). Public package `exports` remain restricted to `./package.json` until the public installed managed-host export lands in [Review #489](https://github.com/rig-c/review/issues/489), 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.
|
|
1021
|
+
|
|
1022
|
+
### Vocabulary, authority, CLI and host ports
|
|
1023
|
+
|
|
1024
|
+
- **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.
|
|
1025
|
+
- **Exact `rig-review session` CLI surface.** `src/entry.ts` and `src/job-cli.ts` implement:
|
|
1026
|
+
- `rig-review session open <root>` (requires `RIG_REVIEW_JOB_REVIEWER_ID` and `RIG_REVIEW_JOB_REVIEWER_ROLE` as `owner` or `delegate`; optional `RIG_REVIEW_JOB_PORT` `0..65535`; optional `RIG_REVIEW_JOB_AGENT_FD` `>= 3` receiving one `{jobId, origin, agentCapability}` JSON line before printing `ownerUrl` on stdout).
|
|
1027
|
+
- `rig-review session publish <job-url> --generation <n> --key <id> --result <relative-path> --freeze-hold <id> [--selector <JSON>] [--record <path> --record-hash <sha256>] [--request-id <id>]`
|
|
1028
|
+
- `rig-review session ask <job-url> --generation <n> --key <id> --publication <id> --subject <JSON> [--request-id <id>]`
|
|
1029
|
+
- `rig-review session next <job-url> [--after <cursor>] [--wait-ms <n>] [--request-id <id>]`
|
|
1030
|
+
- `rig-review session close <job-url> --generation <n> --key <id> --reason <words> [--request-id <id>]`
|
|
1031
|
+
Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `http://127.0.0.1:<port>/jobs/<jobId>` and refuse `fetch-act` (`JOB_AUTHORITY_REFUSED`). See [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow) for an ordinary-package launch, bootstrap and explicit close example.
|
|
1032
|
+
- **Bootstrap-declared reviewer.** `JobReviewerBinding` (`id` and `role` as `'owner'` or `'delegate'` inside `JobHumanAuthority`) is declared by trusted host bootstrap when opening the window. The browser UI cannot type, edit or override this binding. It records bootstrap-declared provenance rather than keyboard-user authentication. Create maps `role` to its existing `by` authority and preserves the declared reviewer identity.
|
|
1033
|
+
- **Trusted host ports and internal managed-host startup seam.** `JobHostPorts` separates `handleJobApi` (which accepts agent verbs and consumer `fetch-act` only) from closed same-origin UI routes (`readPublication`, `commitUIAct`, `ackDisplayed`, `jobLiveness`, `subscribeJob`, mounted by `createJobFront` under `/jobs/<jobId>/…` with sealed retained publication routes; the owner HTML root accepts the default or literal `?lang=en` or `?lang=ko` only) that remain unavailable to agent tokens. Raw `Request` objects preserve real `Origin`, capability, body size and abort context. A TypeScript value is never authentication evidence. In the internal managed-host startup seam (`startJobHost(options: JobHostOptions): Promise<JobOwnerHost>` in `src/job-front.ts`, where `JobHostOptions extends JobWorkerOptions` adds `readerId?: string` and `bindingId?: string`, kept internal until [Review #489](https://github.com/rig-c/review/issues/489) owns the public export name and package exports), each present hook (`readPublished`, `installWriterBinding`) requires a nonempty declared ID and a missing hook requires its ID to be absent (`JOB_HOST_OPTION_ID_INVALID`). Equal declared IDs permit listener reuse across processes and newly allocated function objects via `/jobs/<jobId>/host` (`schema: 'rig-review-job-host/1'`); differing IDs, hook-presence differences and unrecorded older listener IDs fail by name (`JOB_HOST_REUSE_MISMATCH`) with the option name and both IDs while preserving the existing listener. No function hashes are used. `installWriterBinding` receives `{jobId, origin, fetchCapability}` after reuse validation and runs on a matching new or reused host.
|
|
1034
|
+
- **Standing window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line (a job survives zero open owner tabs and reuses the same active job/link on later `session open` until explicit `close`). Internal agent and HQ media stay internal. Each `JobPublication` reports `visual` with `status` set to `'available'` or `'unavailable'` with a named `code`. A missing required visual is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
|
|
1035
|
+
|
|
1036
|
+
### Publication, producer-held freeze and generation CAS
|
|
1037
|
+
|
|
1038
|
+
- **Mutating requests and CAS.** Agent mutations (`publish`, `ask`, `close` in `JobMutation`) require `expectedGeneration` (a nonnegative safe integer) and `idempotencyKey` alongside `schema` (`rig-review/job-api@1`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`.
|
|
1039
|
+
- **Explicit producer-held freeze.** `JobPublishRequest` designates a root-relative `result` (`path` and nullable `selector`, never a command) and requires `freeze` with `kind` set to `'producer-held'`, `holdId` and `record` (`JobFileIdentity` for the exact record used for selection, or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved or incomplete record (`JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local CAS. The freeze assertion is a caller obligation on the publishing producer or agent, not a lock Review can impose on independent writers.
|
|
1040
|
+
- **Explicit close lifecycle.** Review offers no watched-root or automatic-close guarantee. Only an explicit `close` request (`JobCloseRequest` with `reason`) ends an active job (`status` transitions from `'active'` to `'closed'`, and subsequent mutations or fetches refuse with `JOB_CLOSED`).
|
|
1041
|
+
- **Finalized acts and cursor replay.** `JobNextRequest` (`verb` set to `'next'`, `after` cursor or `null`, and daemon-bounded `waitMs`) and `subscribeJob` replay complete durable `JobEvent` items (`published`, `pending`, `act`, `closed`) in order, returning `JobNextValue` (`events`, `cursor`, and `status` as `'events'`, `'timeout'` or `'closed'`). Waiting is abortable and never consumes an act. Invalid cursors refuse with `JOB_CURSOR_INVALID`.
|
|
1042
|
+
|
|
1043
|
+
### Exact displayed source and local draft retention
|
|
1044
|
+
|
|
1045
|
+
- **Daemon-derived source binding.** `JobSourceBinding` requires non-null `sourceHash` (`JobSha256`) and `package` (`id` and `revision`), and requires explicit values or explicit `null` for its typed nullable fields (`projectHash`, `selector` as `draft` / `rig` / `post`, `model`, `direction`, `optionSet`, `appliedResult`, `plan`, `parts`). Original input paths are literal project-relative or package-relative provenance only, and no public field names a Review state directory or stored document. The daemon derives `JobSourceBinding` from validated retained bytes and the actual displayed publication. Clients never provide trusted source hashes or transfer prior approval onto a new binding.
|
|
1046
|
+
- **Display receipt and UI submission.** `JobDisplayPublication` pins same-origin `routes` (`entry`, `apiBase`, `assetsBase`) to that specific `publicationId` and `instanceKey` without a mutable current alias. All metadata, images, runtime assets, routes and pending form dependencies prepare before the visible swap; paint and the single `displayedNonce` acknowledgment precede retirement of the previous view, and failed preparation or acknowledgment restores the prior view and draft. After `ackDisplayed` validates `JobDisplayAcknowledgment` (`publicationId`, `pageId`, `sourceHash`), it returns `JobDisplayReceipt` containing the page-scoped `displayedNonce` secret (never returned by the agent or consumer API). `JobUISubmission` supplies `publicationId`, `askId`, `pageId`, `displayedNonce`, `expectedGeneration`, `submissionId`, `kind` and `value` (`JobUIActValues`). Neither `authority` nor `source` is accepted from the browser. The daemon derives both from the validated nonce and displayed publication (`JOB_DISPLAY_MISMATCH`, `JOB_ACT_SOURCE_STALE`). Retrying the same `submissionId` returns the same immutable `JobAct`, while a changed payload refuses.
|
|
1047
|
+
- **Old drafts retained and flagged without rebinding.** When a new publication updates or replaces the displayed source, older local drafts remain retained in storage under their original source binding and are flagged without rebinding or transferring onto the new publication.
|
|
1048
|
+
|
|
1049
|
+
### Act kinds, plan identity and parts identity
|
|
1050
|
+
|
|
1051
|
+
- **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).
|
|
1052
|
+
- **`interview-picks`.** `JobActValues['interview-picks']` carries `questionId`, ordered `selections` (`itemId`, `optionId`, nullable `otherText`) and `note`, with non-null `source.optionSet` (`id` and `sha256`).
|
|
1053
|
+
- **`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.
|
|
1054
|
+
- **`parts-verdict`.** `JobActValues['parts-verdict']` carries `verdict` (`'pending'`, `'approved'` or `'changes-requested'`), `parts` (`partId`, `part` outcome and note, `mesh` outcome and note with `JobPartOutcome` as `'pending'`, `'clean'` or `'flagged'`) and `words`, requiring non-null `source.projectHash`, a `draft` selector and `source.parts`.
|
|
1055
|
+
- **`review-verdict`.** `JobActValues['review-verdict']` 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.
|
|
1056
|
+
- **`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.
|
|
1057
|
+
- **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.
|
|
1058
|
+
- **Manifest-referenced parts PNG set and C3 limitation.** In the current C3 runtime (`JobPartsIdentity` and `src/job-source.ts`), parts binding is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — exact `manifest` (`parts.json` or `${string}/parts.json` and `sha256`) plus lexically ordered unique `images` (`JobPartImagePath` and `sha256`) restricted to normal `parts/*.png` (`parts/${string}.png` or `${string}/parts/${string}.png`) and exact `painting_in_rig.png` beside `parts.json` at the root or project prefix only (`'painting_in_rig.png'` or `${string}/painting_in_rig.png`). Because `figure_mask` is missing from C3, current C3 runtime does not cover the complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without its own `parts.json` field parser or duplicated field rules. Within the current C3 set, missing or changed referenced bytes — including a referenced `painting_in_rig.png` — invalidate the binding, while unreferenced stale extra files are excluded and do not cause refusal. Both the manifest and the bound referenced set enter `sourceHash`, with no new parts filename or migration.
|
|
1059
|
+
|
|
1060
|
+
### Writer-owned sibling fetch capability and consumer writes
|
|
1061
|
+
|
|
1062
|
+
- **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.
|
|
1063
|
+
- **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.
|
|
1064
|
+
- **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.
|
|
1065
|
+
- **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_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.
|
package/docs/WORKFLOWS.md
CHANGED
|
@@ -358,8 +358,56 @@ The four-stage navigator preserves this entry and its explicit save behavior. Co
|
|
|
358
358
|
|
|
359
359
|
The managed front forwards only the trusted stage-atlas frame query (`stageEmbed=1`, `lang=en|ko`, and a required `side=a|b` for compare; no side for single). Unknown or duplicate keys are refused; the frame carries no filesystem path, command or capability. Stage navigation never changes CLI arguments or package bindings.
|
|
360
360
|
|
|
361
|
+
## Standing live job workflow
|
|
362
|
+
|
|
363
|
+
The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), 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`). Public package exports remain restricted to `./package.json` while a public installed managed-host export is queued in [Review #489](https://github.com/rig-c/review/issues/489), 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`). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) for the full schema and host seam reference.
|
|
364
|
+
|
|
365
|
+
Exact CLI usage from `src/entry.ts` and `src/job-cli.ts` (`publish`, `ask`, `next` and `close` also accept optional `--request-id <id>`):
|
|
366
|
+
|
|
367
|
+
```text
|
|
368
|
+
Usage: rig-review session open <root>
|
|
369
|
+
rig-review session publish <job-url> --generation <n> --key <id> --result <relative-path> --freeze-hold <id> [--selector <JSON>] [--record <path> --record-hash <sha256>]
|
|
370
|
+
rig-review session ask <job-url> --generation <n> --key <id> --publication <id> --subject <JSON>
|
|
371
|
+
rig-review session next <job-url> [--after <cursor>] [--wait-ms <n>]
|
|
372
|
+
rig-review session close <job-url> --generation <n> --key <id> --reason <words>
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
`rig-review session --help` prints this usage (`src/entry.ts` dispatches only the `session` namespace to the live-job CLI and delegates all other argv and exit behavior to `src/cli.ts`). `rig-review session open <root>` requires `RIG_REVIEW_JOB_REVIEWER_ID` and `RIG_REVIEW_JOB_REVIEWER_ROLE` (`owner` or `delegate`; missing or invalid values refuse with `JOB_AUTHORITY_REFUSED`), accepts optional `RIG_REVIEW_JOB_PORT` (`0..65535`), and optionally writes one private `{jobId, origin, agentCapability}` JSON line to an inherited writable descriptor `>= 3` named by `RIG_REVIEW_JOB_AGENT_FD` before printing the standing owner URL on stdout. A standing job survives zero open owner tabs; a later `session open` on the same root reuses the active job/link and exits, while the initial listener stays attached until `SIGINT`/`SIGTERM` or until an explicit `close` event ends the job incarnation. The owner HTML root (`/jobs/<jobId>/`) accepts the default or literal `?lang=en` or `?lang=ko` and refuses other or duplicate queries (`JOB_REQUEST_INVALID`). Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `<origin>/jobs/<jobId>`. Ordinary non-Create package launch, publish, ask, poll and explicit close example (capabilities stay in private descriptors/env and are never printed in logs or reports):
|
|
376
|
+
|
|
377
|
+
```sh
|
|
378
|
+
# Terminal 1 — create a private bootstrap directory (umask 077) and keep the new listener in the foreground:
|
|
379
|
+
boot=$(umask 077 && mktemp -d)
|
|
380
|
+
RIG_REVIEW_JOB_REVIEWER_ID=owner-1 \
|
|
381
|
+
RIG_REVIEW_JOB_REVIEWER_ROLE=owner \
|
|
382
|
+
RIG_REVIEW_JOB_AGENT_FD=3 \
|
|
383
|
+
rig-review session open /absolute/path/to/work-root 3>"$boot/bootstrap.json"
|
|
384
|
+
|
|
385
|
+
# Terminal 2 — with RIG_REVIEW_JOB_AGENT_CAPABILITY set privately from $boot/bootstrap.json:
|
|
386
|
+
rig-review session publish http://127.0.0.1:<port>/jobs/<job-id> \
|
|
387
|
+
--generation 0 --key pub-1 --result package --freeze-hold hold-1 \
|
|
388
|
+
--selector '{"kind":"rig","version":1}'
|
|
389
|
+
rig-review session ask http://127.0.0.1:<port>/jobs/<job-id> \
|
|
390
|
+
--generation 1 --key ask-1 --publication <publication-id> \
|
|
391
|
+
--subject '{"kind":"review-verdict","stage":"rig-review"}'
|
|
392
|
+
rig-review session next http://127.0.0.1:<port>/jobs/<job-id> --wait-ms 5000
|
|
393
|
+
# Pass the current generation returned by next (human UI acts advance generation):
|
|
394
|
+
rig-review session close http://127.0.0.1:<port>/jobs/<job-id> \
|
|
395
|
+
--generation <current-generation> --key close-1 --reason "inspection complete"
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
- **One standing window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media stay internal and are never substituted for the owner handoff. When a required visual is missing (`visual.status` set to `'unavailable'` with a named `code`), the agent stops immediately and files a Create on-path Review card rather than falling back to chat text or images.
|
|
399
|
+
- **Human UI vs agent verbs.** People submit through the Review browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`). Trusted host bootstrap declares `reviewer` (`id` and `role` as `'owner'` or `'delegate'`), which the browser UI cannot type or override. This binding records bootstrap-declared provenance rather than keyboard-user authentication, and Create maps `role` to its existing `by` authority. Agents use only `publish`, `ask`, `next` and `close` (`JobAgentRequest`), with `expectedGeneration` compare-and-swap (CAS) and `idempotencyKey` on mutations.
|
|
400
|
+
- **Explicit producer-held freeze and explicit close.** Every `publish` request designates a root-relative `result` (`path` and `selector`, never a command) and carries an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record` as `JobFileIdentity` or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved record (`JOB_RECORD_MOVED`, `JOB_RECORD_INCOMPLETE`, `JOB_FREEZE_REQUIRED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local generation CAS (`JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`). The freeze assertion is a caller obligation rather than a lock Review can impose on independent writers. Review offers no watched-root or automatic-close guarantee, and only explicit `close` ends an active job.
|
|
401
|
+
- **Exact displayed source and retained drafts.** The daemon derives `JobSourceBinding` from validated retained bytes and the actual displayed publication (`ackDisplayed` returning a page-scoped `displayedNonce` receipt, pinned same-origin `routes` with no mutable current alias). All metadata, images, runtime assets, routes and pending form dependencies prepare before the visible swap; paint and the single `displayedNonce` acknowledgment precede retirement of the previous view, and failed preparation or acknowledgment restores the prior view and draft. Clients never supply trusted source hashes or transfer prior approval onto a new binding. When a new publication updates the displayed source, old local drafts remain retained in storage for their original source binding and are flagged without rebinding onto the new publication.
|
|
402
|
+
- **Finalized acts, five enabled kinds and cursor replay.** `next` (`after` cursor and bounded abortable `waitMs` that never consumes an act) and `subscribeJob` replay complete durable `JobEvent` records (`published`, `pending`, `act`, `closed`). Only five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`). `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`).
|
|
403
|
+
- **Checkpoints, signoffs, plan steps and parts PNGs.** In `checkpoint` acts, `outcome` is `'pass'` or `'fail'` only (`'pending'` stays in the UI draft and never produces a finalized act), and required `words` is preserved verbatim as a string including empty or whitespace-only text. The browser sends `checkpointId`, `outcome` and `words` only while the daemon copies resolved `planStepId` from the validated ask, and Create derives execution stage from its authoritative step phase and order without Review stamping a stage. Only `'pass'` is eligible for Create's checkpoint sign-off writer, while `'fail'` is feedback or a named consumer refusal. In `signoff` acts, `decision` is `'approved'` only (changes requested are a verdict) with required `words` preserved verbatim including empty or whitespace-only text. A verdict, a signoff and a Create stage transition are three separate writes, and plan-bound signoff stages (`plan-approved`, `rigging-interview`, `post-interview`) require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, `JobPartsIdentity` is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal images at `parts/*.png` (`parts/${string}.png` or `${string}/parts/${string}.png`) plus exact `painting_in_rig.png` beside `parts.json` at the root or project prefix only (`painting_in_rig.png` or `${string}/painting_in_rig.png`) — so `figure_mask` is missing and C3 does not yet cover a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without parsing `parts.json` fields itself. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding, while unreferenced stale extra files are excluded without refusal.
|
|
404
|
+
- **No agent file carriage, writer-owned sibling fetch and internal host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and act fetch through a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration). That binding is never tracked in version control or unstaged project output, dies at explicit `close` with a new grant per job incarnation, and grants read-only `fetch-act` over loopback with `Authorization`. In the internal managed-host startup seam (`startJobHost` in `src/job-front.ts`, kept internal until [Review #489](https://github.com/rig-c/review/issues/489)), hook-bearing host callers declare `readerId` for `readPublished` and `bindingId` for `installWriterBinding`; missing or invalid IDs refuse with `JOB_HOST_OPTION_ID_INVALID`, and listener reuse requires equal `readerId` and `bindingId` or refuses with `JOB_HOST_REUSE_MISMATCH` (with no function hashes). Future mesh-edit consumption is owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159), where Create fetches a finalized mesh act and passes its typed value in process to Parts' public exported API without Parts reading Review or Create storage.
|
|
405
|
+
- **Direction metadata vs playback.** Direction carriage in `#484` is metadata-only (`source.direction` and `direction-review`) and is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) stays parked.
|
|
406
|
+
|
|
361
407
|
## Create choice interview
|
|
362
408
|
|
|
409
|
+
In the active standing live-job cycle ([Standing live job workflow](#standing-live-job-workflow), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184)), interview choices and parts verdicts use the semantic job API (`interview-picks` and `parts-verdict` acts fetched directly by the Create writer via its private sibling capability). The `--picks-dir`, `--picks-file`, `--parts-verdict-dir` and saved verdict path commands below are preserved as legacy/history one-shot handoff documentation and are bypass findings if used in the active cycle.
|
|
410
|
+
|
|
363
411
|
Open the interview beside its separated parts in the standard inspection host.
|
|
364
412
|
Use the materialized Create review package and designate the exact project and
|
|
365
413
|
rig version. The picks directory must already exist inside the project and be
|
|
@@ -386,6 +434,8 @@ to export from that session.
|
|
|
386
434
|
|
|
387
435
|
### Open a recorded draft before rig review
|
|
388
436
|
|
|
437
|
+
In the active standing live-job cycle ([Standing live job workflow](#standing-live-job-workflow), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184)), draft parts and mesh verdicts are submitted as `parts-verdict` acts over the semantic job API and fetched directly by the Create writer. The `--picks-dir`, `--parts-verdict-dir` and `--picks-file` commands below are preserved as legacy/history one-shot handoffs and are bypass findings if used in the active cycle.
|
|
438
|
+
|
|
389
439
|
Select a Create draft explicitly and open its recorded compiled check directory.
|
|
390
440
|
Create the picks directory and, for a pending parts verdict, a separate verdict
|
|
391
441
|
directory inside the project before opening the host.
|
|
@@ -439,6 +489,8 @@ refusal when the browser cannot display a bound image.
|
|
|
439
489
|
|
|
440
490
|
## Correction handoff
|
|
441
491
|
|
|
492
|
+
In the active standing live-job cycle ([Standing live job workflow](#standing-live-job-workflow), [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)), `described-correction` and `mesh-edit` remain reserved disabled act kinds (`JOB_ACT_KIND_DISABLED`), and agents never build, parse, reshape or carry Review session, feedback, applied-record or verbatim files. The `--correction`, `--feedback-file`, reshaped feedback JSON and `--verbatim-file` commands below are preserved as legacy/history one-shot handoffs and are bypass findings if used in the active cycle.
|
|
493
|
+
|
|
442
494
|
In **Write review**, choose described or made under **Correction handoff** and
|
|
443
495
|
supply the Create review stage and its draft ID or version. A direction-review
|
|
444
496
|
version also needs its declared post model path. Add the feedback and submit.
|
package/package.json
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rig-review",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.17.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Local human rig inspection and structured feedback export",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"scripts": {
|
|
8
|
-
"review": "bun src/
|
|
9
|
-
"check": "bun src/
|
|
8
|
+
"review": "bun src/entry.ts",
|
|
9
|
+
"check": "bun src/entry.ts check",
|
|
10
10
|
"check:demo": "bun run check -- examples/demo/review.json",
|
|
11
|
-
"demo": "bun src/
|
|
11
|
+
"demo": "bun src/entry.ts examples/demo/review.json --view-only",
|
|
12
12
|
"check:readme": "bun scripts/check-readme.ts",
|
|
13
13
|
"typecheck": "tsc --noEmit",
|
|
14
14
|
"test": "bun test",
|
|
15
15
|
"build": "bun src/build.ts",
|
|
16
|
-
"feedback": "bun src/
|
|
17
|
-
"open": "bun src/
|
|
16
|
+
"feedback": "bun src/entry.ts feedback",
|
|
17
|
+
"open": "bun src/entry.ts open",
|
|
18
18
|
"smoke": "bun scripts/install-smoke.ts",
|
|
19
19
|
"prepublishOnly": "node scripts/prepublish.cjs"
|
|
20
20
|
},
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"bun": ">=1.3.0"
|
|
33
33
|
},
|
|
34
34
|
"bin": {
|
|
35
|
-
"rig-review": "src/
|
|
35
|
+
"rig-review": "src/entry.ts"
|
|
36
36
|
},
|
|
37
37
|
"files": [
|
|
38
38
|
"src",
|
|
@@ -10,8 +10,56 @@ compatibility: Requires Bun 1.3.0 or later on PATH. The canonical npm package is
|
|
|
10
10
|
Use this to hand separated parts, a rig or a post to a person for inspection,
|
|
11
11
|
or to read back their submitted review.
|
|
12
12
|
|
|
13
|
+
## Active cycle standing live-job contract
|
|
14
|
+
|
|
15
|
+
For the active Create and Parts cycle, the authoritative contract is `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.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`). Public package exports remain `./package.json` only until the public installed managed-host export lands in [Review #489](https://github.com/rig-c/review/issues/489), 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`). Do not invent public export names, producer scene fields or unimplemented flags, and never expose capabilities in reports or logs. See [Live job contract](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#standing-live-job-workflow).
|
|
16
|
+
|
|
17
|
+
Exact CLI namespace (`src/entry.ts`, `src/job-cli.ts`; `publish`, `ask`, `next`, `close` also accept optional `--request-id <id>`):
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
Usage: rig-review session open <root>
|
|
21
|
+
rig-review session publish <job-url> --generation <n> --key <id> --result <relative-path> --freeze-hold <id> [--selector <JSON>] [--record <path> --record-hash <sha256>]
|
|
22
|
+
rig-review session ask <job-url> --generation <n> --key <id> --publication <id> --subject <JSON>
|
|
23
|
+
rig-review session next <job-url> [--after <cursor>] [--wait-ms <n>]
|
|
24
|
+
rig-review session close <job-url> --generation <n> --key <id> --reason <words>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`rig-review session open <root>` requires `RIG_REVIEW_JOB_REVIEWER_ID` and `RIG_REVIEW_JOB_REVIEWER_ROLE` (`owner` or `delegate`), accepts optional `RIG_REVIEW_JOB_PORT` (`0..65535`), and optionally writes one private `{jobId, origin, agentCapability}` JSON line to descriptor `RIG_REVIEW_JOB_AGENT_FD` (`>= 3`) before printing the owner URL on stdout. A new listener stays in the foreground until `SIGINT`/`SIGTERM` or explicit `close`; run follow-up agent verbs in a second terminal with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`). Ordinary non-Create package launch, bootstrap and explicit close example:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
# Terminal 1 — create a private bootstrap directory (umask 077) and keep session open in the foreground:
|
|
31
|
+
boot=$(umask 077 && mktemp -d)
|
|
32
|
+
RIG_REVIEW_JOB_REVIEWER_ID=owner-1 \
|
|
33
|
+
RIG_REVIEW_JOB_REVIEWER_ROLE=owner \
|
|
34
|
+
RIG_REVIEW_JOB_AGENT_FD=3 \
|
|
35
|
+
rig-review session open /absolute/path/to/work-root 3>"$boot/bootstrap.json"
|
|
36
|
+
|
|
37
|
+
# Terminal 2 — with RIG_REVIEW_JOB_AGENT_CAPABILITY set privately from $boot/bootstrap.json:
|
|
38
|
+
rig-review session publish http://127.0.0.1:<port>/jobs/<job-id> \
|
|
39
|
+
--generation 0 --key pub-1 --result package --freeze-hold hold-1 \
|
|
40
|
+
--selector '{"kind":"rig","version":1}'
|
|
41
|
+
rig-review session ask http://127.0.0.1:<port>/jobs/<job-id> \
|
|
42
|
+
--generation 1 --key ask-1 --publication <publication-id> \
|
|
43
|
+
--subject '{"kind":"review-verdict","stage":"rig-review"}'
|
|
44
|
+
rig-review session next http://127.0.0.1:<port>/jobs/<job-id> --wait-ms 5000
|
|
45
|
+
# Pass the current generation returned by next (human UI acts advance generation):
|
|
46
|
+
rig-review session close http://127.0.0.1:<port>/jobs/<job-id> \
|
|
47
|
+
--generation <current-generation> --key close-1 --reason "inspection complete"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- **One standing Review window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media stay internal. A missing required visual (`visual.status` set to `'unavailable'`) is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
|
|
51
|
+
- **Human UI vs agent verbs.** People submit through the Review UI (`actor` set to `'human'`, `channel` set to `'review-ui'`). Trusted host bootstrap declares `reviewer` (`id` and `role` as `'owner'` or `'delegate'`), which the browser UI cannot type or override (declared provenance, not keyboard authentication, mapped by Create to its `by` authority). Agents use only `publish`, `ask`, `next` and `close` with `expectedGeneration` CAS and `idempotencyKey` on mutations.
|
|
52
|
+
- **Explicit producer-held freeze and explicit close.** Every `publish` carries an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record` as `JobFileIdentity` or `null` for a declared non-Create root) held until acknowledgment as a caller obligation. Review validates retained bytes, detects a moved record and commits local generation CAS. No watched-root or automatic-close guarantee exists, and only explicit `close` ends an active job.
|
|
53
|
+
- **Exact displayed source, cursor replay and draft retention.** `next` (`after` cursor and bounded abortable `waitMs` that never consumes an act) replays complete durable `JobEvent` items (`published`, `pending`, `act`, `closed`). The daemon derives `JobSourceBinding` from validated retained bytes and the page-scoped `displayedNonce` receipt rather than browser-supplied hashes. When a new publication replaces or updates the displayed source, old local drafts remain retained for their original source binding and are flagged without rebinding onto the new publication.
|
|
54
|
+
- **Five enabled act kinds and two reserved disabled kinds.** Enabled kinds are `interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict` and `signoff`. Reserved kinds `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay disabled (`JOB_ACT_KIND_DISABLED`) and cannot be asked or submitted.
|
|
55
|
+
- **Checkpoints, signoffs, plan steps and parts PNGs.** Finalized `checkpoint` acts carry `outcome` `'pass'` or `'fail'` only (`'pending'` stays in the UI draft), require `words` as a string preserved verbatim including empty or whitespace-only text, copy `planStepId` from the validated ask on the daemon while the browser sends `checkpointId`, `outcome` and `words` only, and leave stage derivation to Create (only `'pass'` is eligible for Create's checkpoint sign-off writer). Finalized `signoff` acts carry `decision` `'approved'` only with required `words` preserved verbatim including empty or whitespace-only text, remain separate from verdicts and Create stage transitions, and require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) (without Review recomputing `stepHash`) on `plan-approved`, `rigging-interview` and `post-interview`. In the current C3 runtime, `JobPartsIdentity` is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal `parts/*.png` images plus exact `painting_in_rig.png` beside `parts.json` (root or project prefix only) — so `figure_mask` is missing and C3 is not yet a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), which owns the roles without a Review field parser. Within the current C3 set, changed or missing referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding while unreferenced stale extras are excluded.
|
|
56
|
+
- **No agent file carriage, writer-owned sibling fetch and internal host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads using a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration) that is never tracked in version control or unstaged project output, dies at explicit `close` and receives a new grant on each job incarnation. In the internal managed-host startup seam (`startJobHost` in `src/job-front.ts`, kept internal until [Review #489](https://github.com/rig-c/review/issues/489)), hook-bearing host callers declare `readerId` and `bindingId`; equality governs listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside this cycle.
|
|
57
|
+
- **Direction metadata vs playback.** Direction carriage in `#484` is metadata-only (`source.direction` and `direction-review`) and is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) stays parked.
|
|
58
|
+
|
|
13
59
|
## What an agent drives vs. what the person drives
|
|
14
60
|
|
|
61
|
+
The one-shot CLI file-handoff instructions in this section and in Correction readback below (`--picks-dir`, `--picks-file`, `--parts-verdict-dir`, `--verdict`, `--correction`, reshaped feedback JSON and `--verbatim-file`) are preserved as legacy/history compatibility for standalone and historical runs. Using those file handoffs in the active standing live-job cycle is a bypass finding ([Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184)).
|
|
62
|
+
|
|
15
63
|
Use the installed CLI. For compiled packages, run `rig-review check <package>`
|
|
16
64
|
before handoff to validate the package and read its source SHA-256. Use managed
|
|
17
65
|
`rig-review open` for joined inspection and embedded saves. Give the reviewer
|
|
@@ -77,6 +125,8 @@ Opening, navigating and saving Review records confer no Create authority.
|
|
|
77
125
|
|
|
78
126
|
## Correction readback
|
|
79
127
|
|
|
128
|
+
In the active standing live-job cycle ([Active cycle standing live-job contract](#active-cycle-standing-live-job-contract), [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)), `described-correction` and `mesh-edit` remain reserved disabled act kinds (`JOB_ACT_KIND_DISABLED`), and agents never build, parse, reshape or carry Review session, feedback, applied-record or verbatim files. The `--correction`, `--verdict`, reshaped feedback JSON and `--verbatim-file` flow below is preserved as legacy/history compatibility and is a bypass finding if used in the active cycle.
|
|
129
|
+
|
|
80
130
|
In **Write review**, the person marks the feedback as described or made under
|
|
81
131
|
**Correction handoff**, supplies the Create selector, and submits. Look for an
|
|
82
132
|
explicit `context.correction` in submitted feedback. Its selector
|
package/src/bones-check.ts
CHANGED
|
@@ -61,7 +61,7 @@ export function createBonesCheck(p: ReviewPackage, options: { stateDir: string;
|
|
|
61
61
|
let running = false;
|
|
62
62
|
async function run(input: unknown): Promise<BonesCheckResult> {
|
|
63
63
|
const { ops, configHash } = parseBonesCheck(input);
|
|
64
|
-
assertStateDirOutside(options.stateDir, p, message => new RebuildError('REBUILD_STATE_INSIDE_PACKAGE', message));
|
|
64
|
+
assertStateDirOutside(options.stateDir, p, (message, code) => new RebuildError(code ?? 'REBUILD_STATE_INSIDE_PACKAGE', message));
|
|
65
65
|
await options.unchanged();
|
|
66
66
|
const inputs = await producerInputs(p.handoff, p.handoffReason);
|
|
67
67
|
const original = JSON.parse(inputs.configText) as JsonValue;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { realpathSync, statSync } from 'node:fs';
|
|
2
|
+
import { basename, dirname, join, resolve } from 'node:path';
|
|
3
|
+
|
|
4
|
+
export class DestinationDirectoryError extends Error {}
|
|
5
|
+
|
|
6
|
+
/** Resolve directory aliases and keep an ENOENT suffix only when the caller can create it. */
|
|
7
|
+
export function destinationDirectory(path: string, refusal: string, allowMissing = true): string {
|
|
8
|
+
const suffix: string[] = [];
|
|
9
|
+
for (let current = resolve(path); ; current = dirname(current)) {
|
|
10
|
+
let physical: string;
|
|
11
|
+
try {
|
|
12
|
+
physical = realpathSync(current);
|
|
13
|
+
} catch (error) {
|
|
14
|
+
const code = (error as NodeJS.ErrnoException).code;
|
|
15
|
+
if (code === 'ENOENT' && allowMissing && dirname(current) !== current) {
|
|
16
|
+
suffix.unshift(basename(current));
|
|
17
|
+
continue;
|
|
18
|
+
}
|
|
19
|
+
if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'ELOOP') {
|
|
20
|
+
throw new DestinationDirectoryError(refusal, { cause: error });
|
|
21
|
+
}
|
|
22
|
+
throw error;
|
|
23
|
+
}
|
|
24
|
+
// Some runtimes report ENOENT for a descendant of a regular file.
|
|
25
|
+
if (!statSync(physical).isDirectory()) throw new DestinationDirectoryError(refusal);
|
|
26
|
+
return join(physical, ...suffix);
|
|
27
|
+
}
|
|
28
|
+
}
|
package/src/entry.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/** The legacy CLI keeps every argv and exit contract outside the session namespace. */
|
|
3
|
+
import {writeSync} from 'node:fs';
|
|
4
|
+
import {main as legacyMain} from './cli.ts';
|
|
5
|
+
import {jobCommand, type JobCLIOptions} from './job-cli.ts';
|
|
6
|
+
import {startJobHost} from './job-front.ts';
|
|
7
|
+
import {defaultStateDir, openFingerprint} from './open.ts';
|
|
8
|
+
import {JobError} from './job-store.ts';
|
|
9
|
+
|
|
10
|
+
const sessionUsage = `Usage: rig-review session open <root>
|
|
11
|
+
rig-review session publish <job-url> --generation <n> --key <id> --result <relative-path> --freeze-hold <id> [--selector <JSON>] [--record <path> --record-hash <sha256>]
|
|
12
|
+
rig-review session ask <job-url> --generation <n> --key <id> --publication <id> --subject <JSON>
|
|
13
|
+
rig-review session next <job-url> [--after <cursor>] [--wait-ms <n>]
|
|
14
|
+
rig-review session close <job-url> --generation <n> --key <id> --reason <words>
|
|
15
|
+
Open requires RIG_REVIEW_JOB_REVIEWER_ID and RIG_REVIEW_JOB_REVIEWER_ROLE (owner or delegate).
|
|
16
|
+
RIG_REVIEW_JOB_AGENT_FD optionally delivers the private agent bootstrap on an inherited writable descriptor >= 3.
|
|
17
|
+
Agent verbs use RIG_REVIEW_JOB_AGENT_CAPABILITY. Create's writer binding is installed by its trusted host callback.`;
|
|
18
|
+
|
|
19
|
+
export async function main(args: string[], options: {stateDir?: string; job?: JobCLIOptions} = {}): Promise<void> {
|
|
20
|
+
const sessionArgs = args[0] === 'session' ? args.slice(1) : args[0] === '--' && args[1] === 'session' ? args.slice(2) : null;
|
|
21
|
+
if (!sessionArgs) return legacyMain(args, {stateDir: options.stateDir});
|
|
22
|
+
if (sessionArgs.length === 0 || sessionArgs[0] === '--help' || sessionArgs[0] === '-h') {
|
|
23
|
+
console.log(sessionUsage);
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
return jobCommand(sessionArgs, {
|
|
27
|
+
...options.job,
|
|
28
|
+
open: options.job?.open ?? (async root => {
|
|
29
|
+
const id = process.env.RIG_REVIEW_JOB_REVIEWER_ID;
|
|
30
|
+
const role = process.env.RIG_REVIEW_JOB_REVIEWER_ROLE;
|
|
31
|
+
if (!id || role !== 'owner' && role !== 'delegate') throw new JobError('JOB_AUTHORITY_REFUSED');
|
|
32
|
+
const rawPort = process.env.RIG_REVIEW_JOB_PORT;
|
|
33
|
+
const port = rawPort === undefined ? undefined : Number(rawPort);
|
|
34
|
+
if (port !== undefined && (!Number.isSafeInteger(port) || port < 0 || port > 65535)) throw new JobError('JOB_REQUEST_INVALID');
|
|
35
|
+
const rawFD = process.env.RIG_REVIEW_JOB_AGENT_FD;
|
|
36
|
+
const descriptor = rawFD === undefined ? null : Number(rawFD);
|
|
37
|
+
if (descriptor !== null && (!Number.isSafeInteger(descriptor) || descriptor < 3)) throw new JobError('JOB_REQUEST_INVALID');
|
|
38
|
+
const host = await startJobHost({root, stateDir: options.stateDir ?? defaultStateDir(),
|
|
39
|
+
fingerprint: await openFingerprint(), reviewer: {id, role}, port});
|
|
40
|
+
try {
|
|
41
|
+
if (descriptor !== null) {
|
|
42
|
+
writeSync(descriptor, JSON.stringify({jobId: host.session.jobId, origin: host.origin,
|
|
43
|
+
agentCapability: host.session.hostCredentials().agent}) + '\n');
|
|
44
|
+
}
|
|
45
|
+
} catch (error) {host.stop(); throw error;}
|
|
46
|
+
if (!host.reused) {
|
|
47
|
+
const stop = () => {host.stop();};
|
|
48
|
+
process.once('SIGINT', stop);
|
|
49
|
+
process.once('SIGTERM', stop);
|
|
50
|
+
} else host.stop();
|
|
51
|
+
return {ownerUrl: host.ownerUrl};
|
|
52
|
+
}),
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
if (import.meta.main) main(Bun.argv.slice(2)).catch(error => {
|
|
57
|
+
console.error(error instanceof Error ? error.message : error);
|
|
58
|
+
process.exitCode = 1;
|
|
59
|
+
});
|
package/src/environment-check.ts
CHANGED
|
@@ -79,7 +79,7 @@ export function createEnvironmentCheck(p: ReviewPackage, options: EnvironmentChe
|
|
|
79
79
|
let running: string | null = null;
|
|
80
80
|
const snapshot = (job: EnvironmentCheckJob): EnvironmentCheckJob => JSON.parse(JSON.stringify(job)) as EnvironmentCheckJob;
|
|
81
81
|
function assertStateOutside(): void {
|
|
82
|
-
assertStateDirOutside(options.stateDir, p, message => new EnvironmentCheckError('ENVIRONMENT_CHECK_STATE_INSIDE_PACKAGE', message));
|
|
82
|
+
assertStateDirOutside(options.stateDir, p, (message, code) => new EnvironmentCheckError(code ?? 'ENVIRONMENT_CHECK_STATE_INSIDE_PACKAGE', message));
|
|
83
83
|
}
|
|
84
84
|
|
|
85
85
|
async function execute(job: EnvironmentCheckJob, dir: string, bin: string, rig: string, parts: string, text: string): Promise<void> {
|