@rig-c/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 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. A delta drawn over the revision's mesh is refused by the producer (`REMESH_DELTA_SOURCE`): its input is always the handoff rig. 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.
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
 
@@ -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
@@ -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 files the config names that the producer resolves against the config's directory (`motion.animations_from`, `generation.control.skeleton`; each must stay inside the root, a missing one is listed in `missing`); `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).
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 file name the config resolves against its directory (`motion.animations_from`, `generation.control.skeleton` — handoff files); `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.
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, `motion.animations_from` and `generation.control.skeleton` made absolute when they name a file 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.
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` incarnation query rotate.
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 legacy `startJobHost` attachment remains supported. Hub
1070
- registration refuses an active external standalone owner with
1071
- `JOB_HUB_EXTERNAL_HOST` and a live unresponsive owner with
1072
- `JOB_HUB_HOST_UNRESPONSIVE`. General cross-process callback registration remains
1073
- deferred. External consumer-owned adoption remains pending in
1074
- [Review #512](https://github.com/rig-c/review/issues/512). Public signatures and
1075
- the host-owned integration example are in
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 `partsEnumeratorId?: string`, 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 reused host.
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 disposes its local session.
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 reuse.
246
- Such attachment keeps the registered process-local hooks under hub ownership.
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 rotate, including the nonsecret
255
- `workspace` query that forces a fresh owner document. Obtain the new owner URL
256
- from the new handle. The retained active job's grants keep their identity until
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 and transport limits remain internal to `src/job-contract.ts`. Consumer checks distinguish these act revisions as described in [Rig verdict still backend](REVIEW_PACKAGE.md#rig-verdict-still-backend).
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 through
462
- `@rig-c/review/job-host`. TypeScript checks the installed consumer and the runtime
463
- checks the full owner resources, retained publication, semantic ports, declared
464
- hooks, enumerator version/row carriage, reuse and explicit-close grant lifetime using synthetic host data.
465
- This installed control uses an explicitly synthetic injected enumerator. Production
466
- Create integration and official-import evidence have their separate acceptance gates.
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