rig-review 2.6.0 → 2.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/PANELS.md +1 -1
- package/docs/PARTS_VIEW.md +2 -0
- package/docs/REVIEW_PACKAGE.md +53 -13
- package/docs/STABILITY.md +232 -15
- package/docs/WORKFLOWS.md +2 -0
- package/package.json +2 -2
- package/src/handoff.ts +192 -25
- package/src/interview-project.ts +13 -0
- package/src/job-act.ts +316 -8
- package/src/job-api.ts +821 -8
- package/src/job-contract.ts +299 -0
- package/src/job-front.ts +763 -23
- package/src/job-host.ts +9 -1
- package/src/job-hub.ts +11 -6
- package/src/job-session.ts +68 -9
- package/src/job-source.ts +787 -7
- package/src/job-store.ts +114 -8
- package/src/job-worker.ts +5 -1
- package/src/joined-project.ts +83 -12
- package/src/manifest.ts +5 -3
- package/src/open.ts +5 -4
- package/src/rebuild.ts +445 -51
- package/src/reference.ts +3 -3
- package/src/server.ts +2 -2
- package/src/stage-parts.ts +47 -15
- package/web/catalog-en.ts +5 -0
- package/web/catalog-ko.ts +5 -0
- package/web/main.ts +353 -43
- package/web/part-selection.ts +2 -0
- package/web/parts.ts +22 -4
- package/web/rebuild-client.ts +14 -2
- package/web/stage-nav.ts +20 -12
package/docs/PANELS.md
CHANGED
|
@@ -371,7 +371,7 @@ Hit-testing is in screen pixels through the current camera: a vertex within 6 px
|
|
|
371
371
|
|
|
372
372
|
Everything is a typed delta over the loaded mesh, in setup-pose crop pixels of the rig canvas (x right, y down, the chest regions' crop mapping): `{schema:"rig-review-mesh-edit/1", slot, skin, attachment, source:{vertexCount, triangleCount, hullLength, hash}, units, basis:"setup", preview, ops}` with ordered ops `move {v, from, to}`, `add {at, onEdge?}`, `remove {v}`, `edge {a, b}` and `unedge {a, b}`. Source vertex ids are the attachment's indices; an added vertex takes the next id; a removed id is never reused. `hullLength` is the model's `hull` (the first `hull` vertices, in order, are the hull) and `hash` is the SHA-256 of `JSON.stringify` of the attachment's entry in the hash-verified model document. Source positions are not rounded (a `move`'s `from` is the vertex's exact setup position; `to` and `add.at` are rounded to 0.01 px). This is the input `rig-parts remesh --delta` reads as it is (see [docs/REVIEW_PACKAGE.md](REVIEW_PACKAGE.md#mesh-edit-export)); the former last-drawn-pose basis is gone. The overlay previews moved, added and removed vertices and the constraint edges over the original triangulation; nothing is retriangulated in the browser (the status line says *preview only — the producer retriangulates*).
|
|
373
373
|
|
|
374
|
-
**Download JSON** saves `mesh-edit.json` and `mesh-edit.binding.json` (package source hash, rig and motion SHA-256, the attachment and its hash, export time, viewer and runtime versions and the mapping). **Apply · Rebuild** (#135) sends the delta to the installed producer as `POST /api/rebuild {part, delta, configHash}`: the server writes it as `mesh-edit.json` (the download's bytes) into the scratch directory and runs `rig-parts remesh --rig <handoff rig> --config <handoff config> --parts <handoff parts> --part <part> --delta mesh-edit.json --out rig`, then the shared tail (per-file diff, compile with remesh.json's pack flags, hash). The producer must read `--delta` (`@rig-c/parts` 1.43.0 or later, read from its own `package.json`), else `MODELING_PRODUCER_TOO_OLD <found> 1.43.0`. The delta's schema, basis, source counts and `source.hash` and every op are the producer's judgment: its `REMESH_DELTA_*` / `REMESH_*` line comes back verbatim and the stage keeps its model. A built revision loads in place and the editor re-reads that revision's setup mesh; `context.applied` becomes `rig-review-applied/3` (the delta by content, `deltaSha256` of its bytes, the producer's line, `op: "remesh"`, the per-file diff and the part's counts). While the revision is on the stage, Reset returns to the inspected build and the draft's delta is restored over it.
|
|
374
|
+
**Download JSON** saves `mesh-edit.json` and `mesh-edit.binding.json` (package source hash, rig and motion SHA-256, the attachment and its hash, export time, viewer and runtime versions and the mapping). **Apply · Rebuild** (#135) sends the delta to the installed producer as `POST /api/rebuild {part, delta, configHash}`: the server writes it as `mesh-edit.json` (the download's bytes) into the scratch directory and runs `rig-parts remesh --rig <handoff rig> --config <handoff config> --parts <handoff parts> --part <part> --delta mesh-edit.json --out rig`, then the shared tail (per-file diff, compile with remesh.json's pack flags, hash). The producer must read `--delta` (`@rig-c/parts` 1.43.0 or later, read from its own `package.json`), else `MODELING_PRODUCER_TOO_OLD <found> 1.43.0`. The delta's schema, basis, source counts and `source.hash` and every op are the producer's judgment: its `REMESH_DELTA_*` / `REMESH_*` line comes back verbatim and the stage keeps its model. A built revision loads in place and the editor re-reads that revision's setup mesh; `context.applied` becomes `rig-review-applied/3` (the delta by content, `deltaSha256` of its bytes, the producer's line, `op: "remesh"`, the per-file diff and the part's counts). While the revision is on the stage, Reset returns to the inspected build and the draft's delta is restored over it. In a joined draft, Apply on a displayed scratch revision refuses with `MESH_DELTA_APPLIED_SOURCE`. Export the delta and rebuild the prior revision, including any Mesh Parameters patch, first. Reset returns to the inspected draft and allows a fresh delta. Review refuses a legacy request with the same code when its attachment matches retained scratch geometry and differs from the inspected attachment. Other deltas still go to the producer for validation. The delta rides in the inspection's local draft bound to the attachment hash (at most 300 ops per attachment); it never enters the review session and nothing is written into the package.
|
|
375
375
|
|
|
376
376
|
For inspection automation, `window.rigReviewEditor.meshEdit()` returns the open editor's source (setup-pose crop px per vertex, unrounded), its ops and each drawn vertex as page client pixels, or `null` when the editor is closed; it reads only.
|
|
377
377
|
|
package/docs/PARTS_VIEW.md
CHANGED
|
@@ -444,6 +444,8 @@ Correction-record export is unfinished, blocked on review#369/create#91. Existin
|
|
|
444
444
|
comments and feedback preserve reviewer wording, but are not a substitute for
|
|
445
445
|
that shared export or for create-owned structure decisions.
|
|
446
446
|
|
|
447
|
+
When `--project` and `--project-draft` select a recorded Create draft that declares its `config`, `parts`, `rig` and `check` directories, Stage 1 also enables the mesh correction instruments before a rig version exists while the draft is editable (`parts` or `parts-review` stage without an effective `parts-review` sign-off, and not `--view-only`). The status bar reports the recorded draft producer version as provenance alongside the installed producer and compiler versions; Apply runs the installed producer and compiler resolved by `resolveProducer` and its operation-capability floors (`REMESH_SINCE` and `REMESH_DELTA_SINCE`, plus `EDIT_PRODUCER_MISMATCH` if a patch's `producer` differs from the installed producer), without an equality version gate against the recorded draft producer. Opening an instrument switches to the Setup inspector for that mesh correction, while direct Stage 3 navigation stays refused with `RIG_VERSION_UNAVAILABLE`. When the project stage is outside `parts`/`parts-review`, an effective `parts-review` sign-off is already recorded, or `--view-only` is set, Stage 1 remains inspection-only (`draft.inspectionOnly: true`) and hides the correction instruments; omitting `--parts-verdict-dir` or viewing an applied scratch build keeps the Stage 1 parts verdict save/export controls read-only (`PARTS_VERDICT_READ_ONLY`) while leaving the correction instruments available on an editable draft.
|
|
448
|
+
|
|
447
449
|
### Declared-grid Difference
|
|
448
450
|
|
|
449
451
|
**Difference** in an individual part view reads the optional producer declaration
|
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -159,7 +159,7 @@ An Apply rebuilds through the installed producer from the files the inspected ri
|
|
|
159
159
|
|
|
160
160
|
Without `--parts` the parts directory is `out/` beside the config (for step 4, the opened `out/` itself; for step 5, the build root). A declared or discovered path that is missing, outside its root (the package root; for step 4 the folder holding `out/`; for step 5 the config's folder), or a symlink that leaves it is refused by name: `HANDOFF_PATH_OUTSIDE_ROOT`, `HANDOFF_SYMLINK_ESCAPE`, `HANDOFF_INPUT_MISSING`, `HANDOFF_INPUT_INVALID`, `HANDOFF_PATH_INVALID` (`open` prefixes `OPEN_HANDOFF_INVALID <flag or path>`). `rig-review open` verifies at start (before spawning or reusing a worker) that every inspected package has a compiled `model` that `@rig-c/play` loads and decodes, and in single mode by default also requires a complete producer handoff (`handoffGap`, `producerInputs`, `resolveProducer`, `contourParts`), exiting non-zero with `OPEN_MODEL_UNAVAILABLE: <reason>` when the model or handoff is missing or broken. Passing `--view-only` explicitly permits opening a compiled model that has no producer handoff at all (`handoff === null`), in which case `/api/rebuild` reports the neutral status `"view only, no producer handoff"` (with `viewOnly: true`) and no panel renders a `MODELING_*` error string; a declared or partially-present handoff with a gap still refuses `OPEN_MODEL_UNAVAILABLE: <reason>` even with `--view-only`. When `startServer` runs directly without `--view-only` and no handoff is found, `/api/rebuild` reports `MODELING_INPUT_UNAVAILABLE: config.json — looked at config.json, rig/config.json, ../config.json (beside an opened out/); declare it with rig-review open <dir> --config <path> [--parts <dir>] or the review.json "producer" block`, and Apply refuses `MODELING_HANDOFF_MISSING`.
|
|
161
161
|
|
|
162
|
-
**Hashed files.** The config; the
|
|
162
|
+
**Hashed files.** The config; the references the installed `@rig-c/parts` `configFileReferences` export declares against the config's directory (`requirements`, `motion.animations_from`, `generation.control.skeleton`, `assemble.occluders[i].image` as regular files, and `assemble.occluders[i].plate` as a directory input bound by `<directory>/receipt.json`'s raw SHA-256 with `{path:"<directory>/receipt.json", sha256, directory:"<directory>", spec}` matching `@rig-c/parts` `PLATE_RECEIPT_SPEC` and `create#326` `93b361f8bfec0ec7e20318d9c8e643eef5d7a674`, never by hashing plate sibling files; each must stay inside the root, a missing one is listed in `missing`, and an unknown reference or an older installed loader that omits a declared occluder input is refused by name with `HANDOFF_INPUT_INVALID`); `parts.json` and every regular file directly in `parts/`; every regular file directly in the inspected `rig/` (`rig.json`, `motion.json`, `mesh_report.json`, `sets.json`, …) and `rig/images/`; with `--source`/`--full`/`--head`, that PNG and the regular files directly in those directories; for a discovered handoff, the `painting.png` beside its config when there is one; with `--keypoints` (#111; the review.json block's `keypoints`), that file — the same path rules as `--source` (literal, inside the root, no symlink escape).
|
|
163
163
|
|
|
164
164
|
**Record and identity.** `reviewedSource.handoff` (absent when there is no handoff, so earlier identities are unchanged):
|
|
165
165
|
|
|
@@ -186,13 +186,13 @@ Every edit card states its edit as one config patch; review applies it to a scra
|
|
|
186
186
|
```
|
|
187
187
|
|
|
188
188
|
- **Document.** Exactly these five keys. `ops` holds 1–256 operations, each `replace` or `add` (`{op, path, value}`, value any JSON) or `remove` (`{op, path}`), each with an optional `name` (#103): the `name` the list entry `/<list>/<index>` holds in the config the patch was made against (a physics edit records `{"op":"replace","path":"/constraints/1/damping","value":0.3,"name":"fringe_r1_physics"}`), applied in order with RFC 6902 semantics; `path` is an RFC 6901 JSON Pointer into the config (`~1` is `/`, `~0` is `~`; an array index is a decimal without leading zeros, and `add` may use `-` to append). `""` (the whole config) is refused. `producer` is the producer the patch was made for. `op.cmd` is `rig` (rebuild the whole rig from the patched config) or `remesh` (re-fit one part from its patched `meshes.<part>` entry; `args` must hold `--part <name>`). `op.args` may also hold `--idle-keys ctl|direct`, `--page-edges pot|free` and `--pack-shape rect|polygon`, each once; nothing else, never a path.
|
|
189
|
-
- **Refusals before anything runs.** Malformed (HTTP 400): `EDIT_PATCH_INVALID`, `EDIT_PATCH_OP_UNKNOWN`, `EDIT_PATCH_POINTER_INVALID`, `EDIT_PATCH_CMD_UNKNOWN`, `EDIT_PATCH_ARG_UNKNOWN`. Outcomes (HTTP 200, `{status:"refused", error, producerLine:null}`): `EDIT_PATCH_STALE` when `config_sha256` is not the handoff config's hash; `EDIT_PATCH_PATH_MISSING` when a pointer does not resolve in that config; `EDIT_PATCH_NAME_MISMATCH` when an op's `name` is not the name its index holds there; `EDIT_PATCH_PATH_HELD` when the patch changes a
|
|
189
|
+
- **Refusals before anything runs.** Malformed (HTTP 400): `EDIT_PATCH_INVALID`, `EDIT_PATCH_OP_UNKNOWN`, `EDIT_PATCH_POINTER_INVALID`, `EDIT_PATCH_CMD_UNKNOWN`, `EDIT_PATCH_ARG_UNKNOWN`. Outcomes (HTTP 200, `{status:"refused", error, producerLine:null}`): `EDIT_PATCH_STALE` when `config_sha256` is not the handoff config's hash; `EDIT_PATCH_PATH_MISSING` when a pointer does not resolve in that config; `EDIT_PATCH_NAME_MISMATCH` when an op's `name` is not the name its index holds there; `EDIT_PATCH_PATH_HELD` when the patch changes a reference the config resolves against its directory (`requirements`, `motion.animations_from`, `generation.control.skeleton`, `assemble.occluders[i].image`, `assemble.occluders[i].plate` — handoff inputs); `EDIT_PATCH_OUT_OF_SCOPE` when a `remesh` patch edits outside `/meshes/<part>`; `EDIT_PRODUCER_MISMATCH` when the installed producer is not the patch's; for a `rig` patch the runner runs as the whole-rig `rig` (*Routing*, below), `EDIT_BASELINE_MISMATCH: <first differing path>` unless the session's baseline reproduced the inspected rig (*Producer handoff*, Baseline); and the producer-resolution refusals of an Apply.
|
|
190
190
|
- **Routing (#136).** A `rig` patch runs `rig-parts retune` instead of the whole-rig `rig` when the installed producer is `@rig-c/parts` 1.44.0 or later (`RETUNE_SINCE`, the CHANGELOG's first release with retune) and **every** op's pointer lies at or under one of `/constraints`, `/motion/duration`, `/motion/tracks`, `/motion/blink/t`, `/motion/blink/squash`, `/motion/blink/brow_drop` (`src/retune-route.ts`). The scope is retune's own help: it splices the config's constraints (rig.json `constraints` and `invariants.detached`) and idle (motion.json `animations.idle`) onto the gated inspected rig and holds stops, bones, slots, skeleton, images, every other invariant and every other byte of motion.json (`RETUNE_REQUEST_HELD`). So `/stops`, `/bones`, `/regions`, `/turn`, `/meshes`, `/motion/animations_from`, the blink's `eyes` and `brows` (its motion.json groups) and `still` (a `<part>_still` slot), and a patch mixing any of them with retune's pointers, keep the whole-rig `rig` behind the baseline guard; so does every patch on an older producer. Retune needs no baseline, but it does not carry every repair (#148, `@rig-c/parts` 1.49.1 AUTHORING §retune and `src/retune.ts`): it carries every attachment and every `mesh_report.json` row over as bytes, so a **mesh** repair the config does not reproduce stays; it holds every image file (with stops, bones, slots, skeleton, every invariant but `detached` and motion.json outside the idle) to the config's rebuild, so on a build whose repair redrew an image every retune refuses `RETUNE_REQUEST_HELD: images/<part>.png — the config changes it`; and it splices `rig.json` and `motion.json` as text, so an input that is not the writer's text refuses `RETUNE_INPUT_WRITTEN`. Measured on parts-examples `family/roa` (a hand shoulder repair that redrew `topwear.png`, parts 1.49.1): as committed, retune refuses `RETUNE_INPUT_WRITTEN` (its `rig.json` is not the writer's text); re-serialised in the writer's format, it refuses `RETUNE_REQUEST_HELD: images/topwear.png`. The baseline line says which applies (*Baseline reach*, below). What it judges per value (a track that newly keys a mesh-bound bone, which gains a `<bone>_ctl` under `--idle-keys ctl`) comes back as its own `RETUNE_REQUEST_HELD` line verbatim, as do `RETUNE_CONFIG_REFUSED` and its other refusals.
|
|
191
191
|
- **Baseline reach (#148).** When the baseline does not reproduce, `baseline.reach` (`src/baseline-reach.ts`) reads both rig directories and states what each producer op will still take, from the producer's own holds: `{schema:"rig-review-baseline-reach/1", notWriterText[], images[], retuneHeld, remeshRefused[], meshParts[], bonesDiffer, ops:{retune, delta, version}, text}`. `notWriterText`: the inspected `rig.json`, `motion.json` and `mesh_report.json` that are not `JSON.stringify(value, null, 1)` and a closing newline (the writer, parts `rigJsonText`) — remesh and its mesh edit refuse `rig.json` / `mesh_report.json` (`REMESH_INPUT_WRITTEN`), retune `rig.json` / `motion.json` (`RETUNE_INPUT_WRITTEN`). `images`: the images the config draws differently. `retuneHeld`: retune's first held difference in its own order (stops, bones, slots, skeleton, images, invariants but `detached`, each image, motion.json outside `animations.idle`), or null when a physics or idle edit Applies. `remeshRefused`: the meshed parts (`skins.default.<part>.<part>` of type `mesh`) whose attachment, image or report row (or an `auto` row's motion) the config does not reproduce — remesh from a config entry refuses them `REMESH_BASELINE_MISMATCH` and re-fits the rest; `bonesDiffer` refuses every part. A mesh edit (`remesh --delta`) builds no config entry, so the baseline does not hold it. `ops` is the installed producer's: below 1.44.0 a physics or idle edit is whole-rig. `text` is appended to the baseline line (`baseline: not reproduced — <first differing path> · <text>`) and to `EDIT_BASELINE_MISMATCH: <path> — <text>`. It is review's reading of the producer's rules; the producer's line on Apply stays the judgment. For family/roa as committed: `out/rig/rig.json, out/rig/mesh_report.json are not the text rig writes for their values (reformatted, or written by another tool), and an op that splices a revision as text refuses such a file — use the files as rig wrote them, or re-serialise them in a copy of the package exactly as rig writes them (JSON with one space of indent and a closing newline) and open the copy; whole-rig edits refuse (EDIT_BASELINE_MISMATCH); physics and idle edits (retune) refuse out/rig/rig.json (RETUNE_INPUT_WRITTEN), and past that the config draws out/rig/images/topwear.png differently and retune holds every image (RETUNE_REQUEST_HELD); remesh and a mesh edit refuse out/rig/rig.json, out/rig/mesh_report.json (REMESH_INPUT_WRITTEN); past that, remesh: bottomwear, topwear, hair_back, hair_front are refused (REMESH_BASELINE_MISMATCH: …); handwear_r, neck, earring can be re-fit`.
|
|
192
192
|
- **Producer refusal hint (#148).** When the producer refuses with a line review can explain — `REMESH_INPUT_WRITTEN` / `RETUNE_INPUT_WRITTEN` (a file that is not the writer's text) or `RETUNE_REQUEST_HELD: images/<name>` (an image the config draws differently) — the job keeps `producerLine` as printed and adds `hint` (absent otherwise), also pushed to `lines` as `review: <hint>`; the status line reads `<producer line> · review: <hint>`. For `RETUNE_INPUT_WRITTEN` on `rig.json`: `rig.json in the inspected rig is not the text rig writes for its value (reformatted, or written by another tool); retune splices a revision as text, so it refuses the file — use the files as rig wrote them, or re-serialise them in a copy of the package exactly as rig writes them (JSON with one space of indent and a closing newline) and open the copy`.
|
|
193
193
|
- **Build (#115).** A `rig` patch with any op at or under `/assemble` or `/limbs` — or under `/bones` on a config that declares `limbs`, whose joints are their bones' origins — runs `rig-parts build` (op `build`): those sections are read by the producer's assemble stage, which `rig --config --parts` never runs (rig-parts AUTHORING §3, the `assemble.cuts`, `assemble.patches` and `limbs` rows). It needs the handoff's painting and full run (`--source <png> --full <dir> [--head <dir>]`, or the review.json block); without them it refuses before anything runs: `MODELING_INPUT_UNAVAILABLE: source painting and See-through runs — rig-parts build reassembles the parts from the painting (--source) and the runs (--full, --head) before the rig, and the handoff declares none; declare them with …`. It is a whole-rig op behind the reproduced baseline (`EDIT_BASELINE_MISMATCH`). The files assemble reads by the config's own naming (each cut's `under`, each limb segment's `cap`, each alternate's `source`, `full`, `head` and `skeleton`) are resolved against the handoff config's directory, must stay inside the package root (`BUILD_INPUT_OUTSIDE_ROOT`, `BUILD_INPUT_MISSING`) and are hashed into the build id — a named directory outside the declared runs by its contents (every regular file under it, at most 8 levels deep and 4096 files, each held inside the package root, in path order; over the bound refuses `BUILD_INPUT_TOO_LARGE`), a declared run through the handoff record (#185); a patch may not name a new one (`EDIT_PATCH_PATH_HELD` — it may keep, move or drop one the config names). `config.json` is the patched config with those paths and the two above made absolute, then `rig-parts build --config config.json --source <handoff source> --full <handoff full> [--head <handoff head>] --out out --seam-pairs [args]`; the rig spec is `out/rig`, and the shared tail diffs and compiles it (no second check: build's own check ran on the parts it assembled). A stage that refuses leaves no scratch, and its FAIL lines come back verbatim (the stage prefix `[assemble]`, `[rig]`, `[check]` stripped); a build that stopped at check with bars not met is kept, check's FAIL lines beside it. The job adds `assembled: {inputs:{source, full, head, named:[{field, path, sha256|null}]}, refusals[], checkFails[], lines[] (the cut:, limb cut:, limb cap: and uncovered-hole lines), seam[], seamPairs[] (the base set's `seam pair` lines), recomposite:{line, before, after, errorMap:{url, sha256}|null}, parts:{changed[], unchanged, partsJson:{count, paths}}|null}` (`before` is the handoff's `parts.json` recomposite block, `after` the scratch one; `errorMap` serves `out/recomposite_error_rig.png` read-only at `/rebuild/<id>/recomposite/recomposite_error_rig.png`), and `wallMs.op` is the build's own wall clock (assemble → rig → check).
|
|
194
194
|
- **Cloth (#111).** A `rig` patch whose ops all lie under `/cloth` (the Setup · Cloth block: one recipe per tag the installed reader accepts — read from its own `CLOTH_TARGETS` — with the reader's fields) runs op `cloth`; a patch mixing `/cloth` ops with others is refused before anything runs (`CLOTH_PATCH_MIXED`). Refused before anything runs: `CLOTH_KEYPOINTS_UNDECLARED` when the handoff declares no `--keypoints` (without them the draft moves the body bones the config states — Decision 1), `MODELING_PRODUCER_TOO_OLD <found> 1.49.1` (the first `@rig-c/parts` whose `--write-config` splices `bones`, `constraints` and `motion.tracks` entry by entry, parts#552), `MODELING_INPUT_UNAVAILABLE: source painting …` without `--source`, and, as a whole-rig op, `EDIT_BASELINE_MISMATCH`. `cloth.json` is the patched config written as `rig` writes its scratch config, with the assemble-read paths made absolute as for `build`; then `rig-parts propose --parts <handoff parts> --source <handoff source> --keypoints <handoff keypoints> --out propose --cloth cloth.json --write-config config.json` (no `--wrist-snap` or `--grid-rule`: the handoff states neither). Its refusals come back verbatim, every FAIL line in `cloth.refusals` — the reader's `CONFIG_CLOTH_*`, `PROPOSE_CLOTH_DRAFTED` (a recipe that drafts nothing), `PROPOSE_CLOTH_PART`, and the write's `PROPOSE_WRITE_CONFIG_FRESH`, `PROPOSE_WRITE_CONFIG_CONFLICT` (an entry the recipe re-drafts or removes that equals neither the draft with the recipe nor the draft without it, rig-parts AUTHORING *The config written*) and `PROPOSE_WRITE_CONFIG_SPLICE`. Review reads only the written `config.json`, never the producer's draft file: it lists every JSON Pointer at which the written config differs from `cloth.json` and refuses to build one that differs outside the sections propose splices (`bones`, `constraints`, `meshes`, `regions`, `limbs`, `motion/tracks`, `turn`, `proposed_rig_scale`): `CLOTH_WRITTEN_OUTSIDE_DRAFTED`. The written config is then built (Decision 2) as `rig-parts build --config config.json …` exactly as a `build` patch when the config declares `limbs` (the job adds `assembled`), else `rig-parts rig --config config.json --parts <handoff parts> --out rig`, and goes through the shared tail. The id adds `cloth`, the keypoint file's hash and (for the build route) the build inputs' hash. The job adds `cloth: {route:"build"|"rig", inputs:{source, keypoints:{path, sha256}}, refusals[], line (propose's `wrote config.json: …` line), written:{count, paths[≤200], outside[≤200], sections[]}|null, links[] (per tag: its parts and the written config's chains, the link preview), wallMs:{propose, build}}`. `GET /api/rebuild` adds `cloth: {targets, targetsRead, recipes, tags[] (per tag: its parts by See-through tag or by the recipe's `part`/`parts`, and the chains their `meshes.<part>.segments` name with `points` and `tip`), keypoints, route, reason}`.
|
|
195
|
-
- **Run.** Scratch is `<state>/rebuild/<package source hash>/<id>/`, `id = sha256([rig-review-rebuild/1, "patch", source hash, config SHA-256, the patch's canonical bytes, producer@version, compiler@version])` — no clock; the same patch again reuses its build. `rig`: `config.json` there is the patched config written as the producer's own scratch configs are (2-space JSON, `
|
|
195
|
+
- **Run.** Scratch is `<state>/rebuild/<package source hash>/<id>/`, `id = sha256([rig-review-rebuild/1, "patch", source hash, config SHA-256, the patch's canonical bytes, producer@version, compiler@version])` — no clock; the same patch again reuses its build. `rig`: `config.json` there is the patched config written as the producer's own scratch configs are (2-space JSON, every `configFileReferences` path made absolute when it names an existing entry beside the handoff config), then `rig-parts rig --config config.json --parts <handoff parts> --out rig [args]`, or for a retune-routed patch `rig-parts retune --rig <handoff rig> --config config.json --parts <handoff parts> --out rig [args]` (the same config; retune reads the inspected rig and writes only `rig/`, with `retune.json`). `remesh`: `mesh.json` is the patched `meshes.<part>` entry and `rig-parts remesh --rig <handoff rig> --config <handoff config> --parts <handoff parts> --part <part> --mesh mesh.json --out rig [args]` (remesh reads the config as written). Then `rigc build --rig rig/rig.json --motion rig/motion.json --out build --profile rig-play --pack --page-edges … --pack-shape …` (the args' values, else `free` / `polygon`; for remesh, its `remesh.json` request; for retune, its `retune.json` request) and `rig-parts check --rig rig --out check --parts <handoff parts>` with the same pack flags. A producer or compiler refusal is the first named line verbatim and leaves no scratch; a check `FAIL` is check's judgment, kept beside the build.
|
|
196
196
|
- **A retune's check (#139).** A retune-routed Apply does not run `rig-parts check` a second time: retune already gated and checked the revision it wrote (`checkStage` over that revision, the same `--parts` and pack flags review passes), and from `@rig-c/parts` 1.49.0 (`RETUNE_CHECK_SINCE`, parts#541) `retune.json`'s `check.revision` carries `line` — check's own last line, byte for byte — and `status` — every block's status as that tree's `check.json` records it, in the file's order. Review first binds it to the files: every `revision` hash row's file under `rig/` must hash to its row, none missing, and `rig/` holds no file but those rows and `retune.json`; otherwise the Apply is refused `RETUNE_CHECK_STALE: <file> sha256 <in retune.json> … <on disk>; retune's check is not this revision's, so no build is recorded` (`absent` on the side without the file) and leaves no scratch. Bound, the side becomes the same check summary a separate check gives (below): `pass` ← `pass`; `exitCode` ← 0 when it passes, else 1 (check's own exit); `line` ← `line`; `bars` ← every upper-case `status` entry (`gate`, `loop` and `seam` are read off figures and are not check.json bars); `gate` ← `status.gate` is `PASS`; plus `source:"retune"`. The job's `wallMs.check` is `null` and its lines say `review: check not run again — retune.json carries retune's check of this revision, bound to it by N revision hash row(s): <line>`. Check still runs on the revision, as before, when `retune.json` carries no `line` / `status` (an older producer; the line says so — not a refusal) or when the Apply checks under an exported world (#112; retune's check read the default one). Whole-rig `rig`, `build` and cloth keep running check.
|
|
197
197
|
- **A remesh's check (#174).** A `remesh` patch Apply (#106) reads `rig-parts remesh`'s own check of its revision the same way, with one binding shared with retune: `remesh.json`'s `check.revision` (`line` and `status` since `@rig-c/parts` 1.49.0, `REMESH_CHECK_SINCE`; the same parts#541 change) is bound by its `revision` hash rows to the files under `rig/` (none missing, none but those rows and `remesh.json`), else the Apply is refused `REMESH_CHECK_STALE: <file> sha256 <in remesh.json> … <on disk>; remesh's check is not this revision's, so no build is recorded` and leaves no scratch. remesh checked the revision with its request's `page_edges` / `pack_shape` — the flags review's own check reads from `remesh.json` — and the handoff `--parts`; a patch passes no `--requirements`. Bound, the summary is the same mapping as retune's with `source:"remesh"`; `wallMs.check` is `null` and the line says `review: check not run again — remesh.json carries remesh's check of this revision, bound to it by N revision hash row(s): <line>`. An older `remesh.json` or an Apply under an exported world runs check, and the line says why. The designation remesh (#99) and Edit Mesh's `remesh --delta` (#135) run no review check at all (remesh's own gate holds check there), so they are unchanged.
|
|
198
198
|
- **Request and job.** `POST /api/rebuild` takes exactly `{patch}` (or #99's `{part, regions, configHash}`, or #105's `{part, bust, configHash}` — see *Chest landmarks* below, or #135's `{part, delta, configHash}` — see *Mesh edit export*), same-origin, 64 KiB. The job (`GET /api/rebuild/<id>`): `{schema:"rig-review-rebuild/1", kind:"patch", id, status:"running"|"built"|"refused"|"failed", reused, request:{patch, patchSha256, configHash}, producer, compiler, lines[], producerLine, exitCode, wallMs:{op, compile, check}, check, diff:{count, paths[≤200]}, build:{model, modelUrl, modelHash, files}|null}`. `diff` lists every JSON Pointer at which the scratch `rig.json` differs from the inspected one (a changed leaf or type, a key or index only one side has). `check` is `{schema:"rig-review-check-summary/1", pass (check.json's PASS, or null without one), exitCode, line (check's last `check: …` line, or its first named refusal), bars:{NAME: status}, gate}`, plus `source:"retune"` or `source:"remesh"` when the summary is that op's carried check (#139, #174; absent: check's own output, `check.json` and its stdout).
|
|
@@ -975,6 +975,8 @@ Packages without authored direction continue to use their explicit legacy
|
|
|
975
975
|
selector. Direction patch Apply is unavailable. Existing supported rig and
|
|
976
976
|
draft Apply records keep their producer and result evidence.
|
|
977
977
|
|
|
978
|
+
When `--project` and `--project-draft` select a recorded draft whose project entry declares `config`, `parts`, `rig` and `check` directories, `/api/rebuild` exposes `draft` metadata with the recorded draft id, producer provenance (`draft.producer`) and input paths alongside the resolved installed `producer` and `compiler` without synthesizing a package `reviewedSource.handoff`. Rebuild status resolves the installed producer and compiler via `resolveProducer` and its operation-capability floors (`REMESH_SINCE` for `remesh --mesh`, `REMESH_DELTA_SINCE` for `remesh --delta`, and `EDIT_PRODUCER_MISMATCH` when a config patch's `producer` differs from the installed producer), without an equality version gate against `draft.producer`. While the draft is editable (`project.stage` in `parts` or `parts-review` without an effective `parts-review` sign-off, and not `--view-only`), `/api/rebuild` accepts region rebuilds, `remesh` config patches and mesh deltas in scratch, and refuses whole-rig, retarget and animation operations with `STAGE_DRAFT_OPERATION`. When the draft is not editable or `--view-only` is set, `/api/rebuild` and `/api/stage-parts` report the draft as inspection-only (`PARTS_VERDICT_READ_ONLY: Stage 1 draft is inspection-only` and `draft.inspectionOnly: true`) and refuse rebuild mutations and scratch Stage 1 build reads (`STAGE_DRAFT_UNAVAILABLE`). Separately, saving or exporting the Stage 1 parts verdict requires an editable draft, `--parts-verdict-dir`, no `--view-only`, and the `inspected` build (`PARTS_VERDICT_READ_ONLY` otherwise).
|
|
979
|
+
|
|
978
980
|
A supported made item must match the server-owned settled Apply seal and
|
|
979
981
|
retained scratch model and pages when the item is added or changed and on
|
|
980
982
|
selected export. Older unchanged items remain saved as historical evidence
|
|
@@ -1058,21 +1060,34 @@ agent, UI and read-only writer requests. The reviewer binding records trusted
|
|
|
1058
1060
|
bootstrap provenance. Supplied sources stay immutable, and agents never create
|
|
1059
1061
|
internal Review state, act files or writer binding files.
|
|
1060
1062
|
|
|
1063
|
+
Each `startJobHub` listener start mints one shared canonical lowercase UUIDv4
|
|
1064
|
+
`listenerIncarnation` across all jobs registered on that hub. Opening additional
|
|
1065
|
+
jobs preserves that incarnation, and stopping and restarting the hub rotates
|
|
1066
|
+
`listenerIncarnation` alongside the hub capability and `workspace` query. Each
|
|
1067
|
+
`hub.openJob` call returns a required non-null detached deeply frozen
|
|
1068
|
+
`job.attachment: JobHostReuseExpectation` derived directly from the owning hub
|
|
1069
|
+
context, including when a compact on-disk `job-ui/<jobId>.json` descriptor omits
|
|
1070
|
+
`listenerIncarnation` at the 65,536-byte limit. Passing a runtime
|
|
1071
|
+
`reuseOnly` property to `hub.openJob` rejects with `JOB_REQUEST_INVALID`
|
|
1072
|
+
(`JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer' | 'reuseOnly'>`).
|
|
1073
|
+
|
|
1061
1074
|
Closing one job revokes its writer grant while other jobs and the shared owner
|
|
1062
1075
|
continue. `await hub.stop()` stops transport and disposes sessions while
|
|
1063
1076
|
preserving active durable jobs and their grants. Restart re-registers the
|
|
1064
1077
|
required callbacks and refreshes writer origins. Active job identity and grants
|
|
1065
|
-
persist, while the hub capability and `workspace`
|
|
1078
|
+
persist, while the hub capability, `listenerIncarnation` and `workspace`
|
|
1079
|
+
incarnation query rotate and invalidate prior strict `reuseOnly` expectations.
|
|
1066
1080
|
Closed retained entries count toward the current hub's 32-entry application
|
|
1067
1081
|
bound. The bound provides no hardware performance guarantee.
|
|
1068
1082
|
|
|
1069
|
-
Compatible same-job
|
|
1070
|
-
|
|
1071
|
-
`
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1083
|
+
Compatible same-job `startJobHost` attachment remains supported via both
|
|
1084
|
+
ordinary authenticated reuse and strict `reuseOnly: {expected}` attachment,
|
|
1085
|
+
which skips `installWriterBinding` during strict bootstrap. Hub registration
|
|
1086
|
+
refuses an active external standalone owner with `JOB_HUB_EXTERNAL_HOST` and a
|
|
1087
|
+
live unresponsive owner with `JOB_HUB_HOST_UNRESPONSIVE`. General cross-process
|
|
1088
|
+
callback registration remains deferred. External consumer-owned adoption remains
|
|
1089
|
+
pending in [Review #512](https://github.com/rig-c/review/issues/512). Public
|
|
1090
|
+
signatures and the host-owned integration example are in
|
|
1076
1091
|
[Public API stability](STABILITY.md#embedded-semantic-job-hub) and
|
|
1077
1092
|
[Embedded semantic jobs](WORKFLOWS.md#embedded-semantic-jobs).
|
|
1078
1093
|
|
|
@@ -1088,12 +1103,16 @@ the host-owned integration example are in
|
|
|
1088
1103
|
- Consumer only, `rig-review session fetch-act <job-url> --act <actId> --consumer-capability-stdin [--still-out <existing-directory>]`. The trusted consumer pipes its existing grant on stdin. New rig acts require `--still-out`.
|
|
1089
1104
|
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.
|
|
1090
1105
|
- **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.
|
|
1091
|
-
- **Trusted host ports and public 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 standalone 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 public managed-host startup seam (`startJobHost(options: JobHostOptions): Promise<JobOwnerHost>` from `@rig-c/review/job-host`, where `JobHostOptions extends JobWorkerOptions` adds `readerId?: string`, `bindingId?: string` and `
|
|
1106
|
+
- **Trusted host ports and public 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 standalone 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 public managed-host startup seam (`startJobHost(options: JobHostOptions): Promise<JobOwnerHost>` from `@rig-c/review/job-host`, where `JobHostOptions extends JobWorkerOptions` adds `readerId?: string`, `bindingId?: string`, `partsEnumeratorId?: string` and `reuseOnly?: {readonly expected: JobHostReuseExpectation}`, and `JobOwnerHost` includes `attachment: JobHostReuseExpectation | null`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), each present hook (`readPublished`, `installWriterBinding`, `partsEnumerator`) requires a nonempty declared ID and a missing hook requires its ID to be absent (`JOB_HOST_OPTION_ID_INVALID`). Equal declared IDs, API/act schemas and actual enumerator versions permit authenticated active-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 ordinary reused host.
|
|
1107
|
+
|
|
1108
|
+
`@rig-c/review/job-host` exports `JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`, `JobHostAttachField` and `JobHostAttachFailure` as types while preserving the twelve runtime exports. Each standalone or hub listener start mints a fresh canonical lowercase UUIDv4 `listenerIncarnation` (`^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`) via `randomUUID()` that rotates on listener stop and restart. `GET /jobs/<jobId>/host` retains its exact legacy `JobHostRecord` projection, key order and raw bytes without `listenerIncarnation` or `attachment`. Complete live binding attestation uses the internal authenticated `POST /jobs/<jobId>/host` route (`X-Review-Capability` UI grant and exact normalized `Origin`, with no public helper export) exchanging `{expected, observed: {root, stateDir, store, record}}` (safe nonnegative `{dev, ino}` integers for `root`, `stateDir`, `jobs.sqlite` and `job-ui/<jobId>.json`) for `{ok: true, attachment, pid}`. Each `job-ui/<jobId>.json` descriptor, each `POST /jobs/<jobId>/host` request and each `POST /jobs/<jobId>/host` response has a 65,536-byte (`WORKSPACE_BODY_LIMIT`) ceiling. When adding `listenerIncarnation` would exceed 65,536 bytes, `job-ui/<jobId>.json` omits `listenerIncarnation` so ordinary start and reuse still succeed with `attachment: null` while strict `reuseOnly` refuses `JOB_HOST_ATTACH_REFUSED` with `reason: 'incarnation-missing'` and `phase: 'record'`. Opaque hook IDs and fingerprints are bounded by each 65,536-byte descriptor, request and response envelope without separate 1,024-byte or 4,096-byte field caps.
|
|
1109
|
+
|
|
1110
|
+
`startJobHost` inspects the `reuseOnly` property descriptor before invoking getters, rejecting a `reuseOnly` getter or accessor immediately with `JOB_REQUEST_INVALID` without invoking the getter. When `reuseOnly` is absent or `undefined`, `startJobHost` uses the ordinary `{...options}` startup path and preserves existing ordinary getter, prototype and callback behavior. When `reuseOnly: {expected}` is provided, `startJobHost` snapshots own data properties (including non-enumerable declared fields) of `options`, `reviewer`, `partsEnumerator` and `reuseOnly.expected` (`binding` and `binding.reviewer`) via `Reflect.ownKeys` and property descriptors before the first `await` or session allocation, retaining callbacks by reference and rejecting non-plain objects, symbol keys, unknown keys, or getters and accessors with `JOB_REQUEST_INVALID` without invoking getters. Strict `reuseOnly: {expected}` bootstrap invokes zero callbacks and performs zero allocations or writes, leaving an empty bootstrap write set on both success and refusal. It resolves existing `stateDir` without creating directories, refuses symlinks, hardlinks and SQLite `-wal`, `-shm` or `-journal` sidecars without recovery, inspects existing `jobs.sqlite` in read-only mode without creating files (`SQLITE_OPEN_READONLY | SQLITE_OPEN_NOFOLLOW`, `PRAGMA query_only=ON`), and stages `JobSession.openReadOnly` before the single final `POST /jobs/<jobId>/host` probe (refusing drift after staging with `JOB_HOST_ATTACH_REFUSED`, `reason: 'race'` and `phase: 'adoption'`). It preserves literal `http://127.0.0.1:<decimal-port>` in `origin` (`1..65535`, including explicit port 80 while comparing `Origin` against normalized `new URL(origin).origin`), enforces a 1,500 ms client total deadline and `redirect: 'error'` alongside a 10,000 ms server body deadline, and orders owner acceptance inside a synchronous deferred SQLite read transaction against `sealClose` (`BEGIN IMMEDIATE`, HTTP 409 with `reason: 'closed'` and `phase: 'acceptance'`) and stop flags (HTTP 503 with `reason: 'stopped'` and `phase: 'acceptance'`). Later semantic writes lazily reopen the same existing `jobs.sqlite` file with `SQLITE_OPEN_READWRITE | SQLITE_OPEN_NOFOLLOW`. `JobHostAttachFailure` is the closed union of `{code: 'JOB_HOST_ATTACH_REFUSED', reason, phase}` (`reason` in `'missing' | 'closed' | 'incarnation-missing' | 'replaced' | 'read' | 'probe' | 'stopped' | 'race'` and `phase` in `'input' | 'state' | 'record' | 'probe' | 'adoption' | 'acceptance'`) and `{code: 'JOB_HOST_REUSE_MISMATCH', field, expected, actual}` (`field` as `JobHostAttachField`, `expected` and `actual` as `string | null`).
|
|
1092
1111
|
- **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.
|
|
1093
1112
|
|
|
1094
1113
|
### Publication, producer-held freeze and generation CAS
|
|
1095
1114
|
|
|
1096
|
-
- **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@2`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`.
|
|
1115
|
+
- **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@2`), `jobId` and `requestId`. Stale generations refuse with `JOB_GENERATION_STALE` and conflicting idempotency payloads refuse with `JOB_IDEMPOTENCY_CONFLICT`. When `handleJobApi` (`POST /jobs/<jobId>/api`) catches a thrown refusal, the failure envelope `generation: number` reports `session.lastObservedGeneration`, which is the last durable generation this session observed successfully in storage and is carried in memory without rereading failing storage inside `catch`. That value reports the last observed session generation while preserving the original named refusal code and message (such as `JOB_STORAGE_FAILED` when SQLite files are removed or replaced) and keeping the numeric `generation: number` response type unchanged. A failed session constructor exposes no API ports when its initial storage read fails. Success responses continue to report current `session.status().generation`.
|
|
1097
1116
|
- **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.
|
|
1098
1117
|
- **Managed-state privacy boundary.** Managed state stays behind the host ports. The canonical work root and configured managed-state directory must be disjoint. A root equal to, inside or containing that state directory refuses `JOB_SOURCE_UNRETAINABLE` before job admission, including directory aliases resolved through symlink ancestors. Existing root identity failures, including a directly symlinked source root, retain `JOB_ROOT_REPLACED`. Trusted publication handles follow the origin job's lifetime, and publishing callers must maintain their producer-held freeze.
|
|
1099
1118
|
- **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`).
|
|
@@ -1170,3 +1189,24 @@ The manifest and complete retained image rows enter the composite source hash. L
|
|
|
1170
1189
|
- **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.
|
|
1171
1190
|
- **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.
|
|
1172
1191
|
- **Error codes.** `JOB_ERROR_CODES` enumerates the closed refusal set (`JOB_REQUEST_INVALID`, `JOB_BODY_LIMIT`, `JOB_LOOPBACK_REQUIRED`, `JOB_SAME_ORIGIN_REQUIRED`, `JOB_CAPABILITY_REQUIRED`, `JOB_AUTHORITY_REFUSED`, `JOB_UNKNOWN`, `JOB_CLOSED`, `JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`, `JOB_FREEZE_REQUIRED`, `JOB_RECORD_INCOMPLETE`, `JOB_RECORD_MOVED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`, `JOB_PUBLICATION_UNKNOWN`, `JOB_SNAPSHOT_RECLAIMED`, `JOB_IMAGE_SET_UNSUPPORTED`, `JOB_IMAGE_SET_INVALID`, `JOB_IMAGE_SET_DUPLICATE_NAME`, `JOB_IMAGE_SET_DUPLICATE_PATH`, `JOB_IMAGE_SET_ROLE_INVALID`, `JOB_IMAGE_SET_PATH_REFUSED`, `JOB_ASK_INVALID`, `JOB_ASK_SUPERSEDED`, `JOB_ACT_UNKNOWN`, `JOB_ACT_INVALID`, `JOB_ACT_KIND_DISABLED`, `JOB_ACT_SOURCE_STALE`, `JOB_DISPLAY_MISMATCH`, `JOB_CURSOR_INVALID`, `JOB_STORAGE_FAILED`, `JOB_AGENT_ISOLATION_HOLE`), each returning bounded safe detail with no arbitrary worker text or private paths.
|
|
1192
|
+
|
|
1193
|
+
### Preparatory model-free record contract and source seam
|
|
1194
|
+
|
|
1195
|
+
`src/job-contract.ts`, `src/job-api.ts`, `src/job-source.ts` and `src/job-act.ts` define the preparatory implementation-stage contract, validators, snapshot retention and act-preparation seam for Review #561. Create #277 owns the landed public `readRecordPublished` export and `JOB_RECORD_READER_ID` (`rig-create/publication-reader/2`), while complete closure, path and `parts` conformance remains open in Create #286. [Review #561](https://github.com/rig-c/review/issues/561), [Create #277](https://github.com/rig-c/create/issues/277), [Create #286](https://github.com/rig-c/create/issues/286).
|
|
1196
|
+
|
|
1197
|
+
`JOB_API_SCHEMA` (`rig-review/job-api@2`), `JOB_ACT_SCHEMA` (`rig-review/act@2`), `JOB_CAPABILITIES` (`{imageSetVerdict: true}`) and the `@rig-c/review/job-host` facade exports keep their existing package-only default behavior. The normal host (`createJobHostPorts` and `JobSession`) parses `rig-review/job-api@2` requests and rejects `rig-review/job-api@3` or tagged record publish requests with HTTP 400 (`JOB_REQUEST_INVALID` / `JOB_API_SCHEMA_MISMATCH`), leaving generation and committed head unchanged. Runtime activation of the opted-in record mode remains gated on Review #563 shared store, session and front paths, Create #286 closure, path and `parts` conformance, Create #278 writer consumer fetch, ingest and freeze integration, and Review's actual fixture proof against the producer-landed Create #279 fixtures. [Review #563](https://github.com/rig-c/review/issues/563), [Create #286](https://github.com/rig-c/create/issues/286), [Create #278](https://github.com/rig-c/create/issues/278), [Create #279](https://github.com/rig-c/create/issues/279).
|
|
1198
|
+
|
|
1199
|
+
| Surface | Exact keys or closed values |
|
|
1200
|
+
| --- | --- |
|
|
1201
|
+
| `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
|
|
1202
|
+
| `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
|
|
1203
|
+
| `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`) |
|
|
1204
|
+
| `RecordPublishedContext` | `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']` |
|
|
1205
|
+
| `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
|
|
1206
|
+
| `RecordSource` | `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']` |
|
|
1207
|
+
| `rig-review-job-record-source/1` | `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']` |
|
|
1208
|
+
| `rig-review-job-record-instance/1` | `['schema', 'fingerprint', 'sourceHash']` |
|
|
1209
|
+
|
|
1210
|
+
The read-only official reader returns the six-key `RecordPublishedContext` with producer-sealed `parts`. `prepareJobRecordSource` runs `phase: 'inventory'` on the immutable source root and retains the sorted, duplicate-free `inventory.files` closure into an owned snapshot (`project.json` within 8 MiB, at most 4,096 regular non-symlink files, 64 MiB per file and 256 MiB total bytes). It then calls `phase: 'retained'` on the snapshot root with `parts: inventory.parts` forwarded unchanged and requires `assertEqualRecordContexts(inventory, retainedContext)`. Before ask or finalize, `verifyJobRecordSourceFresh` re-runs `phase: 'inventory'`, rejects any `inventory.parts` drift against the originally sealed `retained.context.parts` (`JOB_SOURCE_MISMATCH` on ask and `JOB_ACT_SOURCE_STALE` on finalize) before invoking `phase: 'retained'`, and forwards the sealed `retained.context.parts` unchanged when equal. Missing reader or contract tokens (`CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`, `CREATE_PLAN_PUBLICATION_CONTRACT_UNAVAILABLE`) refuse with `JOB_SOURCE_UNRETAINABLE`, while named producer tokens (`JOB_RECORD_CLOSURE_INCOMPLETE`, `JOB_RECORD_PARTS_MISMATCH`, `JOB_RECORD_PARTS_LOCK_MISSING`) map to `JOB_RECORD_INCOMPLETE` on publish or ask and `JOB_ACT_SOURCE_STALE` on finalize.
|
|
1211
|
+
|
|
1212
|
+
`interview-picks` records carry `plan: null` and remain valid for source preparation, ask binding and `rig-review/act@4` preparation. An inspection-only plan record with `plan: {steps: []}` and `subjects: []` is valid for source preparation and freshness checks, while plan `checkpoint` and `signoff` ask binding and `rig-review/act@4` preparation require non-empty `plan.steps` and declared subjects (`JOB_ASK_INVALID` / `JOB_ACT_INVALID`). Focused unit tests use synthetic reader doubles and remain distinct from actual Create conformance.
|
package/docs/STABILITY.md
CHANGED
|
@@ -18,12 +18,58 @@ C4 changes `JobPartsManifestPath`, `JobPartImagePath`, `JobPartsIdentity` and th
|
|
|
18
18
|
import {startJobHost} from '@rig-c/review/job-host';
|
|
19
19
|
import type {
|
|
20
20
|
JobHostOptions, JobOwnerHost, JobHostPorts,
|
|
21
|
+
JobHostListenerIncarnation, JobHostReuseBinding, JobHostReuseExpectation,
|
|
22
|
+
JobHostAttachField, JobHostAttachFailure,
|
|
21
23
|
JobSessionOptions, JobSession, JobWorkerOptions,
|
|
22
24
|
JobPublicationReader, JobPublishedContext,
|
|
23
25
|
} from '@rig-c/review/job-host';
|
|
24
26
|
|
|
25
27
|
function startJobHost(options: JobHostOptions): Promise<JobOwnerHost>;
|
|
26
28
|
|
|
29
|
+
type JobHostListenerIncarnation = string;
|
|
30
|
+
|
|
31
|
+
interface JobHostReuseBinding {
|
|
32
|
+
readonly root: string;
|
|
33
|
+
readonly stateDir: string;
|
|
34
|
+
readonly fingerprint: string;
|
|
35
|
+
readonly reviewer: JobReviewerBinding;
|
|
36
|
+
readonly readerId: string | null;
|
|
37
|
+
readonly bindingId: string | null;
|
|
38
|
+
readonly partsEnumeratorId: string | null;
|
|
39
|
+
readonly partsEnumeratorVersion: string | null;
|
|
40
|
+
readonly apiSchema: typeof JOB_API_SCHEMA;
|
|
41
|
+
readonly actSchema: typeof JOB_ACT_SCHEMA;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
interface JobHostReuseExpectation {
|
|
45
|
+
readonly jobId: JobId;
|
|
46
|
+
readonly origin: string;
|
|
47
|
+
readonly listenerIncarnation: JobHostListenerIncarnation;
|
|
48
|
+
readonly binding: JobHostReuseBinding;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
type JobHostAttachField =
|
|
52
|
+
| 'jobId' | 'origin' | 'listenerIncarnation'
|
|
53
|
+
| 'root' | 'stateDir' | 'fingerprint'
|
|
54
|
+
| 'reviewer.id' | 'reviewer.role'
|
|
55
|
+
| 'readerId' | 'bindingId' | 'partsEnumeratorId'
|
|
56
|
+
| 'partsEnumeratorVersion' | 'apiSchema' | 'actSchema' | 'port';
|
|
57
|
+
|
|
58
|
+
type JobHostAttachFailure =
|
|
59
|
+
| {
|
|
60
|
+
readonly code: 'JOB_HOST_ATTACH_REFUSED';
|
|
61
|
+
readonly reason: 'missing' | 'closed' | 'incarnation-missing'
|
|
62
|
+
| 'replaced' | 'read' | 'probe' | 'stopped' | 'race';
|
|
63
|
+
readonly phase: 'input' | 'state' | 'record'
|
|
64
|
+
| 'probe' | 'adoption' | 'acceptance';
|
|
65
|
+
}
|
|
66
|
+
| {
|
|
67
|
+
readonly code: 'JOB_HOST_REUSE_MISMATCH';
|
|
68
|
+
readonly field: JobHostAttachField;
|
|
69
|
+
readonly expected: string | null;
|
|
70
|
+
readonly actual: string | null;
|
|
71
|
+
};
|
|
72
|
+
|
|
27
73
|
interface JobSessionOptions {
|
|
28
74
|
readonly root: string;
|
|
29
75
|
readonly stateDir: string;
|
|
@@ -48,6 +94,9 @@ interface JobHostOptions extends JobWorkerOptions {
|
|
|
48
94
|
readonly readerId?: string;
|
|
49
95
|
readonly bindingId?: string;
|
|
50
96
|
readonly partsEnumeratorId?: string;
|
|
97
|
+
readonly reuseOnly?: {
|
|
98
|
+
readonly expected: JobHostReuseExpectation;
|
|
99
|
+
};
|
|
51
100
|
}
|
|
52
101
|
|
|
53
102
|
type JobPublicationReader = (input: {
|
|
@@ -92,6 +141,7 @@ interface JobOwnerHost {
|
|
|
92
141
|
readonly origin: string;
|
|
93
142
|
readonly ownerUrl: string;
|
|
94
143
|
readonly reused: boolean;
|
|
144
|
+
readonly attachment: JobHostReuseExpectation | null;
|
|
95
145
|
stop(): void;
|
|
96
146
|
}
|
|
97
147
|
|
|
@@ -110,6 +160,27 @@ interface JobHostPorts {
|
|
|
110
160
|
readonly busy: boolean;
|
|
111
161
|
}>>;
|
|
112
162
|
}
|
|
163
|
+
|
|
164
|
+
const attached = await startJobHost({
|
|
165
|
+
...options,
|
|
166
|
+
reuseOnly: {expected},
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
interface InternalJobHostAttachRequest {
|
|
170
|
+
readonly expected: JobHostReuseExpectation;
|
|
171
|
+
readonly observed: {
|
|
172
|
+
readonly root: {readonly dev: number; readonly ino: number};
|
|
173
|
+
readonly stateDir: {readonly dev: number; readonly ino: number};
|
|
174
|
+
readonly store: {readonly dev: number; readonly ino: number};
|
|
175
|
+
readonly record: {readonly dev: number; readonly ino: number};
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
interface InternalJobHostAttachResponse {
|
|
180
|
+
readonly ok: true;
|
|
181
|
+
readonly attachment: JobHostReuseExpectation;
|
|
182
|
+
readonly pid: number;
|
|
183
|
+
}
|
|
113
184
|
```
|
|
114
185
|
|
|
115
186
|
`root` designates the producer work root. `stateDir` must be outside that root.
|
|
@@ -141,17 +212,137 @@ never migrated, relabelled or rebound to new approvals.
|
|
|
141
212
|
|
|
142
213
|
`readPublished` supplies the producer's published semantic context for the exact
|
|
143
214
|
frozen record. `installWriterBinding` receives the private finalized-act fetch
|
|
144
|
-
grant after reuse validation on each successful new or reused startup. The trusted
|
|
215
|
+
grant after reuse validation on each successful new or ordinary reused startup. The trusted
|
|
145
216
|
writer adapter owns its private binding and storage. A callback failure rejects
|
|
146
217
|
startup with `JOB_AUTHORITY_REFUSED`. `afterSnapshot` and `afterDirectorySync` are
|
|
147
218
|
optional disposable-test boundary hooks inherited from the existing seam.
|
|
148
219
|
|
|
220
|
+
Each standalone `startJobHost` and internal `startJobWorker` listener start mints a
|
|
221
|
+
fresh canonical lowercase UUIDv4 `listenerIncarnation` via `randomUUID()`. The format
|
|
222
|
+
matches `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$` in
|
|
223
|
+
exact lowercase with version `4`, variant `8|9|a|b` and zero leading or trailing
|
|
224
|
+
whitespace. Stopping and restarting a listener on the same port, `jobId`, PID and
|
|
225
|
+
durable grants rotates `listenerIncarnation`.
|
|
226
|
+
|
|
227
|
+
`GET /jobs/<jobId>/host` preserves its exact legacy `JobHostRecord` projection, key
|
|
228
|
+
order and raw bytes without `listenerIncarnation` or `attachment`. Complete live
|
|
229
|
+
binding attestation uses the internal authenticated `POST /jobs/<jobId>/host` route
|
|
230
|
+
with the `X-Review-Capability` UI grant and exact normalized `Origin`. That internal
|
|
231
|
+
route has no public helper or wire-type export. It accepts
|
|
232
|
+
`{expected, observed: {root, stateDir, store, record}}` with safe nonnegative
|
|
233
|
+
`{dev, ino}` integers for `root`, `stateDir`, `jobs.sqlite` and
|
|
234
|
+
`job-ui/<jobId>.json`, and returns `{ok: true, attachment, pid}` on HTTP 200.
|
|
235
|
+
|
|
236
|
+
On a newly started standalone host (`reused === false`) or an ordinary reused host
|
|
237
|
+
whose descriptor carries `listenerIncarnation` and whose POST attestation succeeds,
|
|
238
|
+
`host.attachment` is a detached deeply frozen `JobHostReuseExpectation`. Ordinary
|
|
239
|
+
compatible reuse (`reuseOnly` omitted) keeps its `GET /jobs/<jobId>/host`
|
|
240
|
+
compatibility decision, `installWriterBinding` invocation timing and `ownerUrl`.
|
|
241
|
+
Ordinary reuse returns `attachment: null` when `listenerIncarnation` or the
|
|
242
|
+
additional POST attestation is unavailable.
|
|
243
|
+
|
|
244
|
+
Each `job-ui/<jobId>.json` descriptor, each `POST /jobs/<jobId>/host` request and
|
|
245
|
+
each `POST /jobs/<jobId>/host` response has a 65,536-byte (`WORKSPACE_BODY_LIMIT`)
|
|
246
|
+
ceiling. When adding `listenerIncarnation` to `job-ui/<jobId>.json` would exceed
|
|
247
|
+
65,536 UTF-8 bytes, the writer omits `listenerIncarnation` and writes the compact
|
|
248
|
+
legacy descriptor. Ordinary start and reuse still succeed with `attachment: null`,
|
|
249
|
+
while strict `reuseOnly` refuses `JOB_HOST_ATTACH_REFUSED` with
|
|
250
|
+
`reason: 'incarnation-missing'` and `phase: 'record'`. Opaque hook IDs and
|
|
251
|
+
fingerprints are bounded by each 65,536-byte descriptor, request and response
|
|
252
|
+
envelope without separate 1,024-byte or 4,096-byte field caps.
|
|
253
|
+
|
|
254
|
+
`startJobHost` inspects the `reuseOnly` property descriptor before invoking getters.
|
|
255
|
+
A `reuseOnly` getter or accessor rejects immediately with `JOB_REQUEST_INVALID`
|
|
256
|
+
without invoking the getter. When `reuseOnly` is absent or `undefined`,
|
|
257
|
+
`startJobHost` uses the ordinary `{...options}` startup path and preserves existing
|
|
258
|
+
ordinary getter, prototype and callback behavior. When `reuseOnly: {expected}` is
|
|
259
|
+
provided, `startJobHost` snapshots own data properties (including non-enumerable
|
|
260
|
+
declared fields) of `options`, `reviewer`, `partsEnumerator` and
|
|
261
|
+
`reuseOnly.expected` (`binding` and `binding.reviewer`) via `Reflect.ownKeys` and
|
|
262
|
+
property descriptors before the first `await` or session allocation, retaining
|
|
263
|
+
function callbacks by reference. In that strict branch, non-plain objects, symbol
|
|
264
|
+
keys, unknown keys and getters or accessors reject immediately with
|
|
265
|
+
`JOB_REQUEST_INVALID` without invoking getters.
|
|
266
|
+
|
|
267
|
+
When `reuseOnly: {expected}` is provided, `startJobHost` validates `expected` against
|
|
268
|
+
the snapped caller options (`root`, `stateDir`, `fingerprint`, `reviewer.id`,
|
|
269
|
+
`reviewer.role`, `readerId`, `bindingId`, `partsEnumeratorId`,
|
|
270
|
+
`partsEnumeratorVersion`, `apiSchema`, `actSchema`, literal
|
|
271
|
+
`http://127.0.0.1:<decimal-port>` `origin` in `1..65535` including explicit
|
|
272
|
+
`http://127.0.0.1:80`, optional `port` matching the origin port, `jobId` and
|
|
273
|
+
canonical lowercase UUIDv4 `listenerIncarnation`). Option, schema, hook presence or
|
|
274
|
+
value mismatches reject with `JOB_REQUEST_INVALID`, `JOB_STORED_SCHEMA_MISMATCH`,
|
|
275
|
+
`PARTS_ENUMERATOR_VERSION_MISMATCH`, `JOB_HOST_OPTION_ID_INVALID` or
|
|
276
|
+
`JOB_HOST_REUSE_MISMATCH` (`field`, `expected` and `actual`). This includes cases
|
|
277
|
+
where `expected.binding` has an explicit `null` for an omitted hook ID while the
|
|
278
|
+
caller supplies that callback or enumerator, or the reverse.
|
|
279
|
+
|
|
280
|
+
Strict `reuseOnly: {expected}` bootstrap invokes zero callbacks (`installWriterBinding`,
|
|
281
|
+
`readPublished`, `partsEnumerator.enumerate`, `afterSnapshot`, `afterDirectorySync`)
|
|
282
|
+
and performs zero job allocations (`JobStore.open`), DDL, `chmod` or journal-mode
|
|
283
|
+
changes. Its bootstrap write set is empty on both success and refusal. It resolves
|
|
284
|
+
existing `stateDir` without creating directories (`destinationDirectory(..., false)`),
|
|
285
|
+
requires private owned entries without symlinks or hardlinks, and refuses SQLite
|
|
286
|
+
`-wal`, `-shm` or `-journal` sidecars without running recovery. It inspects existing
|
|
287
|
+
`jobs.sqlite` in read-only mode without creating files (`SQLITE_OPEN_READONLY | SQLITE_OPEN_NOFOLLOW`,
|
|
288
|
+
`PRAGMA query_only=ON`), validates `job-ui/<jobId>.json` and PID liveness before
|
|
289
|
+
sending credentials, and stages a read-only session for that exact job
|
|
290
|
+
(`JobSession.openReadOnly`) before the single final `POST /jobs/<jobId>/host` probe.
|
|
291
|
+
After staging, it rechecks `root`, `stateDir`, `store`, `record`, `job-ui`,
|
|
292
|
+
descriptor bytes, revision, UI capability and full binding. Any drift refuses
|
|
293
|
+
`JOB_HOST_ATTACH_REFUSED` with `reason: 'race'` and `phase: 'adoption'`.
|
|
294
|
+
|
|
295
|
+
Literal `http://127.0.0.1:<decimal-port>` is preserved in `expected.origin` and
|
|
296
|
+
`attachment.origin` including explicit port 80, while the HTTP `Origin` header check
|
|
297
|
+
compares against normalized `new URL(origin).origin` (`http://127.0.0.1` for port 80).
|
|
298
|
+
The client probe enforces a 1,500 ms total deadline across headers and body
|
|
299
|
+
(`AbortSignal.timeout(1500)` plus a bounded body read up to 65,536 bytes within the
|
|
300
|
+
remaining time) and `redirect: 'error'` so redirects are refused without following.
|
|
301
|
+
Failed or aborted reads cancel and release their readers. The server enforces a
|
|
302
|
+
10,000 ms body deadline (`jobBody(request, 65536)`).
|
|
303
|
+
|
|
304
|
+
After body parsing, the owner executes a synchronous acceptance section inside a
|
|
305
|
+
deferred SQLite read transaction (`db.transaction(...).deferred()`). It checks
|
|
306
|
+
published, stopped and accepting flags (including standalone `stopped` and hub
|
|
307
|
+
`closing`) and request abort, verifies UI capability, active job status and full
|
|
308
|
+
binding, checks `listenerIncarnation` and captured, current and observed `{dev, ino}`
|
|
309
|
+
identities (`root`, `stateDir`, `store`, `record`) plus exact descriptor bytes,
|
|
310
|
+
rechecks accepting and abort flags, freezes `{ok: true, attachment, pid}` and
|
|
311
|
+
finishes the read transaction. Because the deferred read transaction holds a SQLite
|
|
312
|
+
read snapshot while `sealClose` commits with `BEGIN IMMEDIATE`, acceptance and close
|
|
313
|
+
execute in a single serial order. A prior committed close returns HTTP 409 with
|
|
314
|
+
`reason: 'closed'` and `phase: 'acceptance'`. A concurrent close waits for the read
|
|
315
|
+
snapshot, and a close or stop after acceptance is an ordinary subsequent lifecycle
|
|
316
|
+
event. Standalone or hub stop initiated before or during body parsing returns HTTP
|
|
317
|
+
503 with `reason: 'stopped'` and `phase: 'acceptance'`. `JobHostAttachFailure` is a
|
|
318
|
+
closed two-member union of `{code: 'JOB_HOST_ATTACH_REFUSED', reason, phase}`
|
|
319
|
+
(`reason` in `'missing' | 'closed' | 'incarnation-missing' | 'replaced' | 'read' | 'probe' | 'stopped' | 'race'`
|
|
320
|
+
and `phase` in `'input' | 'state' | 'record' | 'probe' | 'adoption' | 'acceptance'`)
|
|
321
|
+
and `{code: 'JOB_HOST_REUSE_MISMATCH', field, expected, actual}` (`field` as
|
|
322
|
+
`JobHostAttachField`, `expected` and `actual` as `string | null`).
|
|
323
|
+
|
|
149
324
|
`session` retains its existing trusted-host `JobSession` type, including
|
|
150
325
|
`jobId`, `hostCredentials()` and `status()` for bootstrap and inspection.
|
|
151
326
|
`JobSession` is exported as a type for `host.session`. The host separates agent, owner UI and writer
|
|
152
327
|
credentials through their respective channels. Only explicit semantic `close`
|
|
153
328
|
ends a job and revokes its writer grant. `stop()` disposes this host handle and
|
|
154
|
-
stops its owned listener. A reused handle
|
|
329
|
+
stops its owned listener. A reused handle (including strict `reuseOnly` with
|
|
330
|
+
`reused === true` and non-null `attachment`) disposes only its local session and leaves
|
|
331
|
+
the owner listener running. On a strict attached handle, reads use the read-only
|
|
332
|
+
SQLite connection. A later semantic write (`publish`, `ask`, `close`, `ackDisplayed`,
|
|
333
|
+
`commitUIAct`) lazily reopens the same existing `jobs.sqlite` file with
|
|
334
|
+
`SQLITE_OPEN_READWRITE | SQLITE_OPEN_NOFOLLOW` (omitting `SQLITE_OPEN_CREATE`) and
|
|
335
|
+
rechecks storage and exact job identity in the first `IMMEDIATE` transaction.
|
|
336
|
+
|
|
337
|
+
When `handleJobApi` (`POST /jobs/<jobId>/api`) catches a thrown refusal, the failure
|
|
338
|
+
envelope `generation: number` reports `session.lastObservedGeneration`. That value is
|
|
339
|
+
the last durable generation this session observed successfully in storage, carried in
|
|
340
|
+
memory without rereading failing storage inside `catch`. It represents the last
|
|
341
|
+
observed session value while preserving the original named refusal code and message
|
|
342
|
+
(such as `JOB_STORAGE_FAILED` when SQLite files are removed or replaced) and keeping
|
|
343
|
+
the numeric `generation: number` response type unchanged. A failed session
|
|
344
|
+
constructor exposes no API ports when its initial storage read fails. Success
|
|
345
|
+
responses continue to report current `session.status().generation`.
|
|
155
346
|
|
|
156
347
|
Managed state is private storage accessed through the host ports. The canonical
|
|
157
348
|
work root and configured managed-state directory must be disjoint. Before job
|
|
@@ -196,6 +387,7 @@ use `rig-review/job-api@2` and `rig-review/act@2`.
|
|
|
196
387
|
import {startJobHub} from '@rig-c/review/job-host';
|
|
197
388
|
import type {
|
|
198
389
|
JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub,
|
|
390
|
+
JobHostReuseExpectation,
|
|
199
391
|
} from '@rig-c/review/job-host';
|
|
200
392
|
|
|
201
393
|
function startJobHub(options: JobHubOptions): Promise<JobOwnerHub>;
|
|
@@ -206,7 +398,7 @@ interface JobHubOptions {
|
|
|
206
398
|
readonly port?: number;
|
|
207
399
|
}
|
|
208
400
|
|
|
209
|
-
type JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer'>;
|
|
401
|
+
type JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer' | 'reuseOnly'>;
|
|
210
402
|
|
|
211
403
|
interface JobHubJob {
|
|
212
404
|
readonly session: JobSession;
|
|
@@ -214,6 +406,7 @@ interface JobHubJob {
|
|
|
214
406
|
readonly origin: string;
|
|
215
407
|
readonly jobUrl: string;
|
|
216
408
|
readonly reused: boolean;
|
|
409
|
+
readonly attachment: JobHostReuseExpectation;
|
|
217
410
|
}
|
|
218
411
|
|
|
219
412
|
interface JobOwnerHub {
|
|
@@ -233,6 +426,15 @@ active job with a different reviewer refuses `JOB_AUTHORITY_REFUSED`.
|
|
|
233
426
|
The human receives the hub owner URL once. Agents receive their own per-job
|
|
234
427
|
bootstrap credentials privately and address `/jobs/<jobId>/api`.
|
|
235
428
|
|
|
429
|
+
Each `startJobHub` listener start mints one canonical lowercase UUIDv4
|
|
430
|
+
`listenerIncarnation` shared across all jobs registered on that hub. Opening
|
|
431
|
+
additional jobs on the same hub preserves that incarnation. Each `openJob` call
|
|
432
|
+
returns a required non-null detached deeply frozen `job.attachment: JobHostReuseExpectation`
|
|
433
|
+
derived directly from the owning hub context, including when a compact on-disk
|
|
434
|
+
`job-ui/<jobId>.json` descriptor omits `listenerIncarnation` at the 65,536-byte
|
|
435
|
+
limit. Passing a runtime `reuseOnly` property to `hub.openJob` rejects with
|
|
436
|
+
`JOB_REQUEST_INVALID`.
|
|
437
|
+
|
|
236
438
|
Each job keeps its own identity, source bindings, generation CAS, idempotency
|
|
237
439
|
keys, cursors, asks, acts, display receipts and agent/UI/writer grants. Hook IDs
|
|
238
440
|
follow the existing `JobHostOptions` rules. Reopening an active root and
|
|
@@ -242,8 +444,10 @@ cross-process callback registration is deferred. The hub refuses an active
|
|
|
242
444
|
standalone owner with `JOB_HUB_EXTERNAL_HOST`, and a live unresponsive owner
|
|
243
445
|
with `JOB_HUB_HOST_UNRESPONSIVE`, preserving that owner. A second live hub for
|
|
244
446
|
the state directory refuses `JOB_HUB_ALREADY_RUNNING`. Existing `startJobHost`
|
|
245
|
-
callers can still attach to a compatible hub-owned job by authenticated
|
|
246
|
-
|
|
447
|
+
callers can still attach to a compatible hub-owned job by ordinary authenticated
|
|
448
|
+
reuse or strict `reuseOnly: {expected}` attachment (which skips
|
|
449
|
+
`installWriterBinding` during strict bootstrap). Such attachment keeps the
|
|
450
|
+
registered process-local hooks under hub ownership.
|
|
247
451
|
|
|
248
452
|
Semantic `close` ends only the addressed job and revokes its writer grant.
|
|
249
453
|
Closed entries remain in the current hub list. `await hub.stop()` drains work,
|
|
@@ -251,9 +455,10 @@ stops the shared transport and disposes local sessions. Active jobs retain their
|
|
|
251
455
|
durable identity, grants, publications, asks, acts and replay history across
|
|
252
456
|
that transport stop. Restart requires `startJobHub` and `openJob` for each
|
|
253
457
|
required job, registering callbacks again and refreshing the writer adapter's
|
|
254
|
-
origin. The hub capability and incarnation
|
|
255
|
-
|
|
256
|
-
|
|
458
|
+
origin. The hub capability, `listenerIncarnation` and `workspace` incarnation
|
|
459
|
+
query rotate, forcing a fresh owner document and invalidating prior strict
|
|
460
|
+
`reuseOnly` expectations. Obtain the new owner URL and `job.attachment` from the
|
|
461
|
+
new handle. The retained active job's grants keep their identity until
|
|
257
462
|
semantic close. A later new job receives new grants.
|
|
258
463
|
|
|
259
464
|
Admission is an application bound of 32 registered entries, including closed
|
|
@@ -353,7 +558,7 @@ model binding nor a valid image-set binding uses `JOB_ASK_INVALID`.
|
|
|
353
558
|
|
|
354
559
|
## Named export inventory
|
|
355
560
|
|
|
356
|
-
The backend rig-still extension retains the twelve runtime exports and `JOB_ACT_SCHEMA` at act@2. `JobAct` additionally includes `JobRigReviewAct` at act@3 with top-level `JobRigStill`. The facade adds type-only `JobLegacyAct`, `JobRigReviewAct`, `JobRigStill` and `JobRigCapture` exports. Existing API/store/reuse markers and ordinary/historical acts retain @2. The rig revision constant
|
|
561
|
+
The backend rig-still extension retains the twelve runtime exports and `JOB_ACT_SCHEMA` at act@2. `JobAct` additionally includes `JobRigReviewAct` at act@3 with top-level `JobRigStill`. The facade adds type-only `JobLegacyAct`, `JobRigReviewAct`, `JobRigStill` and `JobRigCapture` exports, and Review #563 adds five type-only exports (`JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`, `JobHostAttachField` and `JobHostAttachFailure`) while keeping the twelve runtime exports unchanged. Existing API/store/reuse markers and ordinary/historical acts retain @2. The rig revision constant, transport limits and the internal `POST /jobs/<jobId>/host` helper remain internal to their modules. Consumer checks distinguish these act revisions as described in [Rig verdict still backend](REVIEW_PACKAGE.md#rig-verdict-still-backend).
|
|
357
562
|
|
|
358
563
|
The exact runtime exports are listed below. Constants preserve their literal
|
|
359
564
|
values from the frozen semantic contract.
|
|
@@ -382,6 +587,11 @@ without aliases or copied wire shapes.
|
|
|
382
587
|
- `JobOwnerHub`
|
|
383
588
|
- `JobHostOptions`
|
|
384
589
|
- `JobOwnerHost`
|
|
590
|
+
- `JobHostListenerIncarnation`
|
|
591
|
+
- `JobHostReuseBinding`
|
|
592
|
+
- `JobHostReuseExpectation`
|
|
593
|
+
- `JobHostAttachField`
|
|
594
|
+
- `JobHostAttachFailure`
|
|
385
595
|
- `JobSessionOptions`
|
|
386
596
|
- `JobSession`
|
|
387
597
|
- `JobWorkerOptions`
|
|
@@ -458,12 +668,19 @@ Rows are capped at 4096, roles at 128 UTF-16 code units and literal paths at 409
|
|
|
458
668
|
## Installed acceptance
|
|
459
669
|
|
|
460
670
|
`bun run smoke` packs the package and installs that tarball into an empty project.
|
|
461
|
-
A consumer imports the runtime and every listed type
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
671
|
+
A consumer imports the twelve runtime exports and every listed type, including
|
|
672
|
+
`JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`,
|
|
673
|
+
`JobHostAttachField` and `JobHostAttachFailure`, through `@rig-c/review/job-host`.
|
|
674
|
+
TypeScript checks the installed consumer and the runtime checks the full owner
|
|
675
|
+
resources, retained publication, semantic ports, declared hooks, enumerator
|
|
676
|
+
version/row carriage, ordinary reuse, strict `reuseOnly: {expected}` attachment
|
|
677
|
+
(including `JOB_HOST_REUSE_MISMATCH` on a rotated `listenerIncarnation` and
|
|
678
|
+
`JOB_HOST_ATTACH_REFUSED` on unavailable attachment), and explicit-close grant
|
|
679
|
+
lifetime using synthetic host data. Offline synthetic tarball or linked dependency
|
|
680
|
+
consumer probes remain separate from the fresh `bun run smoke` install executed in
|
|
681
|
+
hosted PR CI. This installed control uses an explicitly synthetic injected
|
|
682
|
+
enumerator. Production Create integration and official-import evidence have their
|
|
683
|
+
separate acceptance gates.
|
|
467
684
|
|
|
468
685
|
The declared export-removal control deletes only `./job-host` from the disposable
|
|
469
686
|
installed manifest and requires the public import to fail for that missing
|
package/docs/WORKFLOWS.md
CHANGED
|
@@ -739,6 +739,8 @@ offers the registered pending sets and displays historical answers read-only.
|
|
|
739
739
|
**3 Rig + animation** and **4 Direction** report that the recorded rig review
|
|
740
740
|
package is unavailable. Reopen with a rig version once Create records one.
|
|
741
741
|
|
|
742
|
+
When the recorded draft entry includes `config`, `parts`, `rig` and `check` directories and the draft is editable (`parts` or `parts-review` stage without an effective `parts-review` sign-off, and not `--view-only`), **1 Parts + mesh** also offers the Chest regions, Mesh parameters and Edit Mesh instruments for mesh-bearing parts regardless of whether `--parts-verdict-dir` is supplied. Selecting an instrument opens the Setup inspector for that part while direct selection of **3 Rig + animation** remains refused with `RIG_VERSION_UNAVAILABLE`. Apply runs the installed producer and compiler in scratch under the existing discovery and operation-capability floors while keeping the recorded draft producer as provenance, and returning to **1 Parts + mesh** or running Undo or Reset updates the displayed mesh and report readings from the active build (verdict saving remains read-only on scratch builds and when `--parts-verdict-dir` is omitted).
|
|
743
|
+
|
|
742
744
|
From a create project with retained choice sets, create a dedicated output
|
|
743
745
|
directory and open the foreground Stage 2 view:
|
|
744
746
|
|