rig-review 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -44,7 +44,7 @@ the same CLI. `@rig-c/review` remains the canonical package.
44
44
 
45
45
  `rig-review` runs under **Bun 1.3.0 or later**, which must be on `PATH`; CI runs the installed package on 1.3.0 and on the latest Bun. `open` prints a loopback URL and exits; see [One-command owner handoff](#one-command-owner-handoff). `npx rig-review --help` lists every command.
46
46
 
47
- The CLI and `@rig-c/review/job-host` managed owner host are supported surfaces. See [Public API stability](docs/STABILITY.md) for the frozen exports and signatures.
47
+ The CLI and `@rig-c/review/job-host` support owner hosting, including embedded N-job `startJobHub`/`openJob`. See [Public API stability](docs/STABILITY.md) for exports and signatures.
48
48
 
49
49
  Example stdout from `open` (private capability omitted):
50
50
 
@@ -261,7 +261,10 @@ Without a painting the comparison controls are absent and the reference pane nam
261
261
  actual displayed pixels, camera preservation, mode/opacity save/reload/restore and both exports in EN/KO.
262
262
  Its native crop remains the original part RGBA, while the viewport crop shows the displayed comparison.
263
263
  A current image/painting render failure clears the part pixels and refuses comment creation/editing
264
- as `PARTS_PAINT_FAILED` until a successful repaint. Older failed generations cannot invalidate a
264
+ as `PARTS_PAINT_FAILED` until a successful repaint. Both buffers clear and both cameras reset to
265
+ 1:1 centred on the actual canvas. Zoom, pan, Fit and saved comment/stage camera restoration stay
266
+ locked until rendering succeeds; retrying the part restores its painted frame before navigation resumes.
267
+ Older failed generations cannot invalidate a
265
268
  newer successful view (`tests/parts-async-navigation.test.ts`; focused browser evidence in
266
269
  `tests/parts-paint-failure-browser.ts`).
267
270
 
@@ -279,7 +282,8 @@ assemble in a separate fixture directory. It is an evidence script, never an app
279
282
  [the waiting consumer #390](https://github.com/rig-c/review/issues/390). Review adds no producer resampler.
280
283
  Neither visual comparison nor opening a package supplies an approval.
281
284
 
282
- Parts native zoom ranges from `min(fit, 1)` to 16; exact native 1 is always reachable. **Fit** is
285
+ Parts native zoom ranges from `min(fit, 1)` to 16. Exact native 1 is always reachable for a valid,
286
+ successfully rendered frame. **Fit** is
283
287
  a separate action, and **1:1** is shown only at exactly 1. Out-of-range requests refuse as
284
288
  `PARTS_CAMERA_RANGE`; the compiled rig's Fit-relative 0.25–8 policy stays unchanged.
285
289
 
@@ -1021,6 +1021,43 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
1021
1021
 
1022
1022
  `src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@2`) and `JOB_ACT_SCHEMA` (`rig-review/act@2`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). One-shot file-handoff workflows documented elsewhere in this reference remain preserved as legacy/history compatibility for existing callers.
1023
1023
 
1024
+ ### Embedded N-job owner
1025
+
1026
+ `startJobHub` and `hub.openJob` from `@rig-c/review/job-host` add one
1027
+ process-local embedded owner for N semantic jobs. One PID/listener serves one
1028
+ human owner URL and job list, with a common bootstrap-declared reviewer.
1029
+ The existing job-api@2/act@2 schemas apply independently to each job's identity,
1030
+ source binding, generation, idempotency, grants, pending asks, finalized acts,
1031
+ display acknowledgment and replay cursor. Hub-selected frames use the current
1032
+ `?hub=<incarnation>` query with optional literal `lang=en` or `lang=ko`. The
1033
+ normal cycle remains `publish`,
1034
+ `ask`, `next`, direct writer `fetch-act`, and explicit `close`.
1035
+
1036
+ Trusted `readPublished`, `partsEnumerator` and `installWriterBinding` hooks are
1037
+ registered in the owning process with the existing declared IDs. Owner-list
1038
+ access requires the private hub capability. Each job separately authenticates
1039
+ agent, UI and read-only writer requests. The reviewer binding records trusted
1040
+ bootstrap provenance. Supplied sources stay immutable, and agents never create
1041
+ internal Review state, act files or writer binding files.
1042
+
1043
+ Closing one job revokes its writer grant while other jobs and the shared owner
1044
+ continue. `await hub.stop()` stops transport and disposes sessions while
1045
+ preserving active durable jobs and their grants. Restart re-registers the
1046
+ required callbacks and refreshes writer origins. Active job identity and grants
1047
+ persist, while the hub capability and `workspace` incarnation query rotate.
1048
+ Closed retained entries count toward the current hub's 32-entry application
1049
+ bound. The bound provides no hardware performance guarantee.
1050
+
1051
+ Compatible same-job legacy `startJobHost` attachment remains supported. Hub
1052
+ registration refuses an active external standalone owner with
1053
+ `JOB_HUB_EXTERNAL_HOST` and a live unresponsive owner with
1054
+ `JOB_HUB_HOST_UNRESPONSIVE`. General cross-process callback registration remains
1055
+ deferred. External consumer-owned adoption remains pending in
1056
+ [Review #512](https://github.com/rig-c/review/issues/512). Public signatures and
1057
+ the host-owned integration example are in
1058
+ [Public API stability](STABILITY.md#embedded-semantic-job-hub) and
1059
+ [Embedded semantic jobs](WORKFLOWS.md#embedded-semantic-jobs).
1060
+
1024
1061
  ### Vocabulary, authority, CLI and host ports
1025
1062
 
1026
1063
  - **Human UI vs agent verbs.** People submit decisions exclusively through the Review browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`). Agents drive the standing job through four semantic verbs (`publish`, `ask`, `next`, `close` in `JobAgentRequest`). Consumer writers use the separate read-only transport verb `fetch-act` (`JobFetchActRequest`), which is never a human-act writer.
@@ -1032,7 +1069,7 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
1032
1069
  - `rig-review session close <job-url> --generation <n> --key <id> --reason <words> [--request-id <id>]`
1033
1070
  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.
1034
1071
  - **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.
1035
- - **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 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.
1072
+ - **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.
1036
1073
  - **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.
1037
1074
 
1038
1075
  ### Publication, producer-held freeze and generation CAS
package/docs/STABILITY.md CHANGED
@@ -156,12 +156,96 @@ The runtime entry starts the full owner host with retained publication routes
156
156
  and shipped HTML, JavaScript and CSS. Raw Requests and the existing A/B ports
157
157
  preserve capability, origin, size, cancellation and replay checks.
158
158
 
159
+ ## Embedded semantic-job hub
160
+
161
+ `startJobHub` adds an embedded N-job owner to the same public
162
+ `@rig-c/review/job-host` facade. One host process owns one loopback listener and
163
+ one human owner list at `ownerUrl`. Each `openJob` registers its trusted hooks
164
+ in that process and returns the existing session and semantic ports. The jobs
165
+ use `rig-review/job-api@2` and `rig-review/act@2`.
166
+
167
+ ```ts
168
+ import {startJobHub} from '@rig-c/review/job-host';
169
+ import type {
170
+ JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub,
171
+ } from '@rig-c/review/job-host';
172
+
173
+ function startJobHub(options: JobHubOptions): Promise<JobOwnerHub>;
174
+
175
+ interface JobHubOptions {
176
+ readonly stateDir: string;
177
+ readonly reviewer: JobReviewerBinding;
178
+ readonly port?: number;
179
+ }
180
+
181
+ type JobHubJobOptions = Omit<JobHostOptions, 'stateDir' | 'port' | 'reviewer'>;
182
+
183
+ interface JobHubJob {
184
+ readonly session: JobSession;
185
+ readonly ports: JobHostPorts;
186
+ readonly origin: string;
187
+ readonly jobUrl: string;
188
+ readonly reused: boolean;
189
+ }
190
+
191
+ interface JobOwnerHub {
192
+ readonly origin: string;
193
+ readonly ownerUrl: string;
194
+ openJob(options: JobHubJobOptions): Promise<JobHubJob>;
195
+ stop(): Promise<void>;
196
+ }
197
+ ```
198
+
199
+ `stateDir` stays outside every registered work root. `port` accepts 0..65535 and
200
+ defaults to an available port. The bootstrap `reviewer` is common to every job,
201
+ with the same trusted provenance and role checks as `startJobHost`. A retained
202
+ active job with a different reviewer refuses `JOB_AUTHORITY_REFUSED`.
203
+ `ownerUrl` has the form `/hub/?workspace=<incarnation>#cap=<private-capability>`.
204
+ `jobUrl` is the per-job owner URL, including its private UI capability.
205
+ The human receives the hub owner URL once. Agents receive their own per-job
206
+ bootstrap credentials privately and address `/jobs/<jobId>/api`.
207
+
208
+ Each job keeps its own identity, source bindings, generation CAS, idempotency
209
+ keys, cursors, asks, acts, display receipts and agent/UI/writer grants. Hook IDs
210
+ follow the existing `JobHostOptions` rules. Reopening an active root and
211
+ fingerprint with compatible hook identities returns the same session with
212
+ `reused` true and invokes the writer-binding callback again. General
213
+ cross-process callback registration is deferred. The hub refuses an active
214
+ standalone owner with `JOB_HUB_EXTERNAL_HOST`, and a live unresponsive owner
215
+ with `JOB_HUB_HOST_UNRESPONSIVE`, preserving that owner. A second live hub for
216
+ the state directory refuses `JOB_HUB_ALREADY_RUNNING`. Existing `startJobHost`
217
+ callers can still attach to a compatible hub-owned job by authenticated reuse.
218
+ Such attachment keeps the registered process-local hooks under hub ownership.
219
+
220
+ Semantic `close` ends only the addressed job and revokes its writer grant.
221
+ Closed entries remain in the current hub list. `await hub.stop()` drains work,
222
+ stops the shared transport and disposes local sessions. Active jobs retain their
223
+ durable identity, grants, publications, asks, acts and replay history across
224
+ that transport stop. Restart requires `startJobHub` and `openJob` for each
225
+ required job, registering callbacks again and refreshing the writer adapter's
226
+ origin. The hub capability and incarnation rotate, including the nonsecret
227
+ `workspace` query that forces a fresh owner document. Obtain the new owner URL
228
+ from the new handle. The retained active job's grants keep their identity until
229
+ semantic close. A later new job receives new grants.
230
+
231
+ Admission is an application bound of 32 registered entries, including closed
232
+ entries retained in that hub incarnation. `JOB_HUB_LIMIT` refuses a new entry
233
+ at the bound. Compatible reuse of an active entry still succeeds. Selected
234
+ frames are retained lazily under this bound. Hidden hub members suspend their event subscription after bootstrap and resume from the last delivered cursor when selected. Hardware performance requires its
235
+ own measurement.
236
+
237
+ Consumer-owned adoption remains external and pending in
238
+ [Review #512](https://github.com/rig-c/review/issues/512). See the
239
+ [embedded consumer example](WORKFLOWS.md#embedded-semantic-jobs) for trusted-hook
240
+ ownership and the ordinary semantic cycle.
241
+
159
242
  ## Named export inventory
160
243
 
161
244
  The exact runtime exports are listed below. Constants preserve their literal
162
245
  values from the frozen semantic contract.
163
246
 
164
247
  - `startJobHost`
248
+ - `startJobHub`
165
249
  - `JOB_API_SCHEMA`
166
250
  - `JOB_ACT_SCHEMA`
167
251
  - `JOB_PARTS_ENUMERATOR_RANGE`
@@ -173,9 +257,13 @@ values from the frozen semantic contract.
173
257
 
174
258
  The exact type-only exports follow. Their existing definitions in
175
259
  `src/job-contract.ts`, `src/job-source.ts`, `src/job-session.ts`,
176
- `src/job-worker.ts` and `src/job-front.ts` are reexported
260
+ `src/job-worker.ts`, `src/job-front.ts` and `src/job-hub.ts` are reexported
177
261
  without aliases or copied wire shapes.
178
262
 
263
+ - `JobHubOptions`
264
+ - `JobHubJobOptions`
265
+ - `JobHubJob`
266
+ - `JobOwnerHub`
179
267
  - `JobHostOptions`
180
268
  - `JobOwnerHost`
181
269
  - `JobSessionOptions`
package/docs/WORKFLOWS.md CHANGED
@@ -281,14 +281,10 @@ options refuse with `OPEN_OPTION_INVALID`; existing single options retain their
281
281
  behavior. Flags and their literal values are consumed before counting operands.
282
282
  Core's `rigc review` continues forwarding to `open`; Review owns this grammar.
283
283
 
284
- The embedded semantic-job hub also remains pending. Its same-process host will
285
- own trusted `readPublished`, `partsEnumerator` and `installWriterBinding`
286
- callbacks. General cross-process callback transport is deferred. Each job retains
287
- independent source, reviewer, capabilities, generation CAS, cursor, displayed
288
- acknowledgment and writer grant under job-api@2/act@2. Registration-handle detach,
289
- host stop and semantic close remain separate lifecycle concerns. Follow the
290
- current [standing live-job workflow](#standing-live-job-workflow) and
291
- [public host contract](STABILITY.md#managed-owner-host) for semantic jobs.
284
+ Embedded semantic jobs share one owner list through `startJobHub` and
285
+ `hub.openJob`. Their trusted callbacks stay in the host process. Follow
286
+ [Embedded semantic jobs](#embedded-semantic-jobs) and the
287
+ [public hub contract](STABILITY.md#embedded-semantic-job-hub).
292
288
 
293
289
  ### Launcher contract
294
290
 
@@ -507,6 +503,108 @@ The four-stage navigator preserves this entry and its explicit save behavior. Co
507
503
 
508
504
  The managed front forwards only the trusted stage-atlas frame query (`stageEmbed=1`, `lang=en|ko`, and a required `side=a|b` for compare; no side for single). Unknown or duplicate keys are refused; the frame carries no filesystem path, command or capability. Stage navigation never changes CLI arguments or package bindings.
509
505
 
506
+ ## Embedded semantic jobs
507
+
508
+ Use **N reviews → one invocation, one owner URL** for both CLI folder inspection
509
+ and embedded semantic jobs. External consumer-owned adoption remains
510
+ pending in [Review #512](https://github.com/rig-c/review/issues/512).
511
+
512
+ In an embedded consumer, start one hub and register each job from that same
513
+ process. Give the human `hub.ownerUrl` and one what-to-look-at line. The hub
514
+ owns one PID/listener and a list that selects each job's standing Review UI.
515
+ The bootstrap reviewer binding applies to all registered jobs. Each job retains
516
+ its separate generation, source, asks, acts, replay cursor and grants under
517
+ job-api@2/act@2. View-only CLI folder entries retain their inspection workflow.
518
+
519
+ This minimal Bun integration uses public imports. Its `host` argument is an
520
+ explicit trusted-hook placeholder supplied by the consumer application. The
521
+ consumer implements the publication reader, imports the official installed
522
+ Parts enumerator, and installs the writer's private binding through its own
523
+ adapter. The example defines their required public types and leaves those
524
+ consumer-owned implementations to the host.
525
+
526
+ ```ts
527
+ import {startJobHub} from '@rig-c/review/job-host';
528
+ import type {
529
+ JobHubJob, JobHubJobOptions, JobOwnerHub, JobReviewerBinding,
530
+ } from '@rig-c/review/job-host';
531
+
532
+ type TrustedHostHooks = Required<Pick<JobHubJobOptions,
533
+ 'readPublished' | 'readerId' | 'partsEnumerator' | 'partsEnumeratorId' |
534
+ 'installWriterBinding' | 'bindingId'>>;
535
+
536
+ async function openReviews(host: {
537
+ stateDir: string;
538
+ reviewer: JobReviewerBinding;
539
+ jobs: readonly {
540
+ root: string;
541
+ fingerprint: string;
542
+ hooks: TrustedHostHooks;
543
+ }[];
544
+ }): Promise<{hub: JobOwnerHub; jobs: JobHubJob[]}> {
545
+ const hub = await startJobHub({
546
+ stateDir: host.stateDir,
547
+ reviewer: host.reviewer,
548
+ });
549
+ const jobs: JobHubJob[] = [];
550
+ try {
551
+ for (const job of host.jobs) {
552
+ jobs.push(await hub.openJob({
553
+ root: job.root,
554
+ fingerprint: job.fingerprint,
555
+ ...job.hooks,
556
+ }));
557
+ }
558
+ return {hub, jobs};
559
+ } catch (error) {
560
+ await hub.stop();
561
+ throw error;
562
+ }
563
+ }
564
+ ```
565
+
566
+ The consumer calls `openReviews` once with its designated jobs and retains the
567
+ returned `{hub, jobs}`. Privately hand `hub.ownerUrl` to the person. `stateDir`
568
+ is outside all job roots. Keep the host alive until its explicit transport
569
+ shutdown and await `hub.stop()` then. The public types and complete lifecycle are in
570
+ [Public API stability](STABILITY.md#embedded-semantic-job-hub).
571
+
572
+ For each handle in the returned `jobs`, trusted bootstrap uses
573
+ `job.session.hostCredentials()` to
574
+ deliver only that job's agent credential through a private agent channel.
575
+ Use `<origin>/jobs/<jobId>` as the CLI job address. `jobUrl` carries an owner UI
576
+ capability and belongs to the owner channel. The hub's private capability
577
+ allows owner-list selection. Bootstrap-declared reviewer provenance is distinct
578
+ from authenticating the person at the keyboard.
579
+
580
+ 1. Freeze the producer's designated record and result through publication
581
+ acknowledgment, then `publish` with the job's current generation and an
582
+ idempotency key.
583
+ 2. `ask` for the exact publication and supported semantic subject. The person
584
+ inspects and submits in that job's Review UI.
585
+ 3. Use `next` to replay events and their cursor. The trusted writer directly
586
+ uses read-only `fetch-act` with its separately installed grant to consume a
587
+ finalized act. Check API@2/act@2 and the exact source binding.
588
+ 4. Use semantic `close` for that job when its cycle ends. Other jobs and the
589
+ owner list continue. The closed entry stays visible in the list.
590
+
591
+ Agents use the semantic commands. Supplied sources and compiled assets stay
592
+ immutable, and agents never construct internal Review state, human acts or
593
+ binding files. Trusted callbacks remain process-local. Compatible active
594
+ root/fingerprint registrations reuse the job after hook-ID validation. Legacy
595
+ `startJobHost` can attach to a matching hub-owned job. A hub registration that
596
+ finds an active standalone owner refuses `JOB_HUB_EXTERNAL_HOST`, while a live
597
+ unresponsive descriptor refuses `JOB_HUB_HOST_UNRESPONSIVE`. General
598
+ cross-process callback registration is deferred.
599
+
600
+ Transport stop preserves active durable jobs and their grants. After restart,
601
+ register every required job's callbacks again, refresh the writer binding's
602
+ origin, and obtain the new hub owner URL. The hub capability and `workspace`
603
+ incarnation query rotate. Each retained active job keeps its identity and grants
604
+ until explicit close. The current hub admits at most 32 entries, including
605
+ closed retained entries, and lazily retains selected frames. This application
606
+ bound has no hardware performance guarantee. Hidden hub members suspend their event subscription after bootstrap and resume from the last delivered cursor when selected.
607
+
510
608
  ## Standing live job workflow
511
609
 
512
610
  The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@2`, `JOB_ACT_SCHEMA` set to `rig-review/act@2`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](STABILITY.md#managed-owner-host), and Create's production publication reader and writer-owned sibling `fetch-act` readback remain pending [Create #184](https://github.com/rig-c/create/issues/184) (publishing a Create root containing `project.json` without a host `readPublished` callback refuses `JOB_SOURCE_UNRETAINABLE` with `CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) for the full schema and host seam reference.
@@ -521,7 +619,7 @@ Usage: rig-review session open <root>
521
619
  rig-review session close <job-url> --generation <n> --key <id> --reason <words>
522
620
  ```
523
621
 
524
- `rig-review session --help` prints this usage (`src/entry.ts` dispatches only the `session` namespace to the live-job CLI and delegates all other argv and exit behavior to `src/cli.ts`). `rig-review session open <root>` requires `RIG_REVIEW_JOB_REVIEWER_ID` and `RIG_REVIEW_JOB_REVIEWER_ROLE` (`owner` or `delegate`; missing or invalid values refuse with `JOB_AUTHORITY_REFUSED`), accepts optional `RIG_REVIEW_JOB_PORT` (`0..65535`), and optionally writes one private `{jobId, origin, agentCapability}` JSON line to an inherited writable descriptor `>= 3` named by `RIG_REVIEW_JOB_AGENT_FD` before printing the standing owner URL on stdout. A standing job survives zero open owner tabs; a later `session open` on the same root reuses the active job/link and exits, while the initial listener stays attached until `SIGINT`/`SIGTERM` or until an explicit `close` event ends the job incarnation. The owner HTML root (`/jobs/<jobId>/`) accepts the default or literal `?lang=en` or `?lang=ko` and refuses other or duplicate queries (`JOB_REQUEST_INVALID`). Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `<origin>/jobs/<jobId>`. Ordinary non-Create package launch, publish, ask, poll and explicit close example (capabilities stay in private descriptors/env and are never printed in logs or reports):
622
+ `rig-review session --help` prints this usage (`src/entry.ts` dispatches only the `session` namespace to the live-job CLI and delegates all other argv and exit behavior to `src/cli.ts`). `rig-review session open <root>` requires `RIG_REVIEW_JOB_REVIEWER_ID` and `RIG_REVIEW_JOB_REVIEWER_ROLE` (`owner` or `delegate`; missing or invalid values refuse with `JOB_AUTHORITY_REFUSED`), accepts optional `RIG_REVIEW_JOB_PORT` (`0..65535`), and optionally writes one private `{jobId, origin, agentCapability}` JSON line to an inherited writable descriptor `>= 3` named by `RIG_REVIEW_JOB_AGENT_FD` before printing the standing owner URL on stdout. A standing job survives zero open owner tabs; a later `session open` on the same root reuses the active job/link and exits, while the initial listener stays attached until `SIGINT`/`SIGTERM` or until an explicit `close` event ends the job incarnation. The standalone owner HTML root (`/jobs/<jobId>/`) accepts the default or literal `?lang=en` or `?lang=ko` and refuses other or duplicate queries (`JOB_REQUEST_INVALID`). Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `<origin>/jobs/<jobId>`. Ordinary non-Create package launch, publish, ask, poll and explicit close example (capabilities stay in private descriptors/env and are never printed in logs or reports):
525
623
 
526
624
  ```sh
527
625
  # Terminal 1 — create a private bootstrap directory (umask 077) and keep the new listener in the foreground:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "2.2.0",
3
+ "version": "2.3.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -65,11 +65,39 @@ Leave existing workers under their owner's control. Follow
65
65
  [workspace lifecycle and restart](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#workspace-lifecycle-and-restart)
66
66
  for host reuse, live unresponsive PID refusal and aggregate shutdown behavior.
67
67
 
68
- Plain foreground multi-target invocation and the embedded semantic-job hub remain
69
- pending. Core's `rigc review` passes arguments through unchanged. Follow the
70
- current active-cycle contract below for semantic jobs and trusted callbacks.
71
- Keep imagery, questions and approvals in the Review UI, using supported commands
72
- and APIs. Agents never construct internal Review state or human acts.
68
+ For both CLI and embedded integrations, use **N reviews → one invocation, one
69
+ owner URL**. Core's `rigc review` passes arguments through unchanged. For
70
+ semantic jobs, use `startJobHub` from `@rig-c/review/job-host` once and call
71
+ `hub.openJob` per designated job in that process. Give the person `hub.ownerUrl`
72
+ and one what-to-look-at line. One PID/listener owns the list and selected Review
73
+ UI, with a common trusted bootstrap reviewer. Keep each job's identity,
74
+ generation CAS, source, asks, acts, cursors and grants separate under
75
+ job-api@2/act@2. Follow the
76
+ [embedded workflow and trusted-hook example](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#embedded-semantic-jobs)
77
+ and [public signatures](https://github.com/rig-c/review/blob/main/docs/STABILITY.md#embedded-semantic-job-hub).
78
+
79
+ Register `readPublished`, `partsEnumerator` and `installWriterBinding` with their
80
+ declared IDs in the owning process. The consumer host owns these implementations
81
+ and private bootstrap channels. General cross-process callback registration is
82
+ deferred. Compatible legacy `startJobHost` attachment to a hub-owned job remains
83
+ supported. An active external standalone owner refuses `JOB_HUB_EXTERNAL_HOST`,
84
+ and a live unresponsive owner refuses `JOB_HUB_HOST_UNRESPONSIVE`.
85
+
86
+ Use `publish`, `ask` and `next` per job. The trusted writer directly fetches
87
+ finalized acts with its separate read-only grant. Human submission stays in the
88
+ Review UI. Semantic `close` ends only that job and revokes its writer grant.
89
+ `await hub.stop()` stops transport, preserving active durable jobs and grants.
90
+ On restart, re-register callbacks, refresh writer origins and obtain the new hub
91
+ owner URL. The hub capability and `workspace` incarnation rotate, while retained
92
+ active job identities and grants persist until close. Closed retained entries
93
+ count toward the hub's 32-entry application bound. Selected frames are retained
94
+ lazily within that bound, with no hardware performance guarantee.
95
+
96
+ External consumer-owned hub adoption remains pending in
97
+ [Review #512](https://github.com/rig-c/review/issues/512). Keep imagery, questions
98
+ and approvals in the Review UI through supported commands and APIs. Supplied
99
+ sources stay immutable. Agents never construct internal Review state, binding
100
+ files or human acts, and owner capabilities stay in private owner channels.
73
101
 
74
102
  ## Active cycle standing live-job contract
75
103
 
package/src/build.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { fileURLToPath } from 'node:url';
2
2
  export const appRoot=fileURLToPath(new URL('..',import.meta.url));
3
- export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'|'workspace'='single'):Promise<Blob> {
4
- const result=await Bun.build({entrypoints:[appRoot+(mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
3
+ export async function buildWeb(mode:'single'|'compare'|'parts'|'interview'|'workspace'|'job-hub'='single'):Promise<Blob> {
4
+ const result=await Bun.build({entrypoints:[appRoot+(mode==='job-hub'?'web/job-hub.ts':mode==='workspace'?'web/owner-workspace.ts':mode==='compare'?'web/compare.ts':mode==='parts'?'web/parts.ts':mode==='interview'?'web/interview.ts':'web/main.ts')],target:'browser',format:'esm',minify:false});
5
5
  if(!result.success)throw new Error(result.logs.map(v=>v.message).join('\n'));
6
6
  const output=result.outputs.find(v=>v.path.endsWith('.js'));if(!output)throw new Error('frontend bundle: JavaScript output missing');return output;
7
7
  }
package/src/job-front.ts CHANGED
@@ -40,6 +40,7 @@ function result<Value>(value: JobResult<Value>): Response {
40
40
  export function createJobFront(options: {
41
41
  origin: string;
42
42
  ports: JobHostPorts;
43
+ hubIncarnation?: string;
43
44
  resource: (name: 'index.html' | 'job.js' | 'styles.css') => Promise<BodyInit>;
44
45
  publication?: (jobId: string, publicationId: string, instanceKey: string, path: string, request: Request) => Promise<Response>;
45
46
  }) {
@@ -124,8 +125,16 @@ export function createJobFront(options: {
124
125
  });
125
126
  return new Response(body, { headers: { ...headers, 'Content-Type': 'application/x-ndjson' } });
126
127
  }
127
- if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search)))
128
+ const embedded = route === '' && url.searchParams.has('hub');
129
+ if (embedded) {
130
+ if (!options.hubIncarnation || url.searchParams.get('hub') !== options.hubIncarnation ||
131
+ [...url.searchParams.keys()].some(key => !['hub', 'lang'].includes(key) || url.searchParams.getAll(key).length !== 1) ||
132
+ url.searchParams.has('lang') && !['en', 'ko'].includes(url.searchParams.get('lang')!)) {
133
+ return failure('JOB_REQUEST_INVALID', 400);
134
+ }
135
+ } else if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search))) {
128
136
  return failure('JOB_REQUEST_INVALID', 400);
137
+ }
129
138
  const instance = /^publications\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/instances\/([a-f0-9]{64})\/(.*)$/.exec(route);
130
139
  if (instance && options.publication) {
131
140
  return options.publication(jobId, instance[1]!, instance[2]!, instance[3]!, request);
@@ -138,7 +147,9 @@ export function createJobFront(options: {
138
147
  return failure('JOB_REQUEST_INVALID', 404);
139
148
  const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'job.js' ? 'text/javascript' : 'text/css';
140
149
  return new Response(request.method === 'HEAD' ? null : await options.resource(name), {
141
- headers: { ...headers, 'Content-Type': type },
150
+ headers: { ...headers, 'Content-Type': type, ...(embedded ? {
151
+ 'Content-Security-Policy': headers['Content-Security-Policy'].replace("frame-ancestors 'none'", "frame-ancestors 'self'"),
152
+ } : {}) },
142
153
  });
143
154
  }
144
155
  return {
@@ -274,7 +285,7 @@ function retainedPublicationRoutes(session: JobSession) {
274
285
  };
275
286
  }
276
287
 
277
- interface JobHostRecord {
288
+ export interface JobHostRecord {
278
289
  schema: 'rig-review-job-host/1';
279
290
  apiSchema: typeof JOB_API_SCHEMA;
280
291
  actSchema: typeof JOB_ACT_SCHEMA;
@@ -330,37 +341,75 @@ export interface JobOwnerHost {
330
341
  stop(): void;
331
342
  }
332
343
 
333
- /** Full standing owner host. #489 can publish this seam after its own contract review. */
334
- export async function startJobHost(options: JobHostOptions): Promise<JobOwnerHost> {
335
- const startup = {...options};
344
+ export function jobHostIdentity(startup: JobHostOptions) {
336
345
  const readerId = declaredHostId('readPublished', startup.readPublished, startup.readerId);
337
346
  const bindingId = declaredHostId('installWriterBinding', startup.installWriterBinding, startup.bindingId);
338
347
  const partsEnumeratorId = declaredHostId('partsEnumerator', startup.partsEnumerator?.enumerate, startup.partsEnumeratorId);
339
348
  const partsEnumeratorVersion = startup.partsEnumerator?.version ?? null;
340
- const session = new JobSession(startup);
341
- async function installBinding(origin: string): Promise<void> {
342
- try {await startup.installWriterBinding?.({...session.writerGrant(), origin});}
343
- catch {throw new JobError('JOB_AUTHORITY_REFUSED', 'Writer binding installation failed');}
349
+ return {readerId, bindingId, partsEnumeratorId, partsEnumeratorVersion};
350
+ }
351
+
352
+ export async function installJobWriterBinding(session: JobSession, startup: JobHostOptions, origin: string): Promise<void> {
353
+ try {await startup.installWriterBinding?.({...session.writerGrant(), origin});}
354
+ catch {throw new JobError('JOB_AUTHORITY_REFUSED', 'Writer binding installation failed');}
355
+ }
356
+
357
+ export function assertJobHostCompatible(record: JobHostRecord, identity: ReturnType<typeof jobHostIdentity>): void {
358
+ for (const [option, actual, requested] of [
359
+ ['readPublished', record.readerId, identity.readerId],
360
+ ['installWriterBinding', record.bindingId, identity.bindingId],
361
+ ['partsEnumerator', record.partsEnumeratorId, identity.partsEnumeratorId],
362
+ ['partsEnumeratorVersion', record.partsEnumeratorVersion, identity.partsEnumeratorVersion],
363
+ ['apiSchema', record.apiSchema, JOB_API_SCHEMA],
364
+ ['actSchema', record.actSchema, JOB_ACT_SCHEMA],
365
+ ] as const) {
366
+ if (actual !== requested) {
367
+ throw new JobHostOptionError('JOB_HOST_REUSE_MISMATCH', option, actual, requested);
368
+ }
344
369
  }
370
+ }
371
+
372
+ /** One live job request context. Its caller owns the listener and session lifetime. */
373
+ export function createJobRequestContext(session: JobSession, startup: JobHostOptions, origin: string,
374
+ identity: ReturnType<typeof jobHostIdentity>, resource = jobWindowResources(), hubIncarnation?: string) {
375
+ const ports = createJobHostPorts(session, origin);
376
+ const record: JobHostRecord = {schema: 'rig-review-job-host/1', apiSchema: JOB_API_SCHEMA, actSchema: JOB_ACT_SCHEMA,
377
+ ...identity, jobId: session.jobId, origin, fingerprint: startup.fingerprint, pid: process.pid};
378
+ const front = createJobFront({origin, ports, resource, hubIncarnation, publication: retainedPublicationRoutes(session)});
379
+ let requests = 0;
380
+ return {
381
+ ports, record,
382
+ get busy() {return requests > 0 || session.busy;},
383
+ async fetch(request: Request): Promise<Response> {
384
+ requests++;
385
+ try {
386
+ const url = new URL(request.url);
387
+ if (url.pathname === `/jobs/${session.jobId}/host`) {
388
+ if (url.origin !== origin || request.method !== 'GET' || url.search ||
389
+ request.headers.get('sec-fetch-site') === 'cross-site' ||
390
+ request.headers.get('origin') !== null && request.headers.get('origin') !== origin) return failure('JOB_REQUEST_INVALID', 403);
391
+ try {session.authorize('ui', request.headers.get('X-Review-Capability'));}
392
+ catch {return failure('JOB_CAPABILITY_REQUIRED', 403);}
393
+ return Response.json(record, {headers});
394
+ }
395
+ return await front.fetch(request) ?? failure('JOB_REQUEST_INVALID', 404);
396
+ } finally {requests--;}
397
+ },
398
+ stop() {front.stop();},
399
+ };
400
+ }
401
+
402
+ /** Full standing owner host. #489 can publish this seam after its own contract review. */
403
+ export async function startJobHost(options: JobHostOptions): Promise<JobOwnerHost> {
404
+ const startup = {...options};
405
+ const identity = jobHostIdentity(startup);
406
+ const session = new JobSession(startup);
407
+ const installBinding = (origin: string) => installJobWriterBinding(session, startup, origin);
345
408
  const credentials = session.hostCredentials();
346
409
  const control = join(canonicalStatePath(startup.stateDir), 'job-ui');
347
410
  await mkdir(control, {recursive: true, mode: 0o700}).catch(error => {session.dispose(); throw error;});
348
411
  const recordPath = join(control, session.jobId + '.json');
349
412
  let previousPort = 0;
350
- function compatible(record: JobHostRecord): void {
351
- for (const [option, actual, requested] of [
352
- ['readPublished', record.readerId, readerId],
353
- ['installWriterBinding', record.bindingId, bindingId],
354
- ['partsEnumerator', record.partsEnumeratorId, partsEnumeratorId],
355
- ['partsEnumeratorVersion', record.partsEnumeratorVersion, partsEnumeratorVersion],
356
- ['apiSchema', record.apiSchema, JOB_API_SCHEMA],
357
- ['actSchema', record.actSchema, JOB_ACT_SCHEMA],
358
- ] as const) {
359
- if (actual !== requested) {
360
- throw new JobHostOptionError('JOB_HOST_REUSE_MISMATCH', option, actual, requested);
361
- }
362
- }
363
- }
364
413
  const reuse = async (): Promise<JobHostRecord | null> => {
365
414
  try {
366
415
  const info = await lstat(recordPath);
@@ -378,8 +427,8 @@ export async function startJobHost(options: JobHostOptions): Promise<JobOwnerHos
378
427
  if (!response?.ok) {void response?.body?.cancel(); return null;}
379
428
  const value = await response.json() as JobHostRecord;
380
429
  if (value.schema !== row.schema || value.jobId !== row.jobId || value.fingerprint !== row.fingerprint) return null;
381
- compatible(row);
382
- compatible(value);
430
+ assertJobHostCompatible(row, identity);
431
+ assertJobHostCompatible(value, identity);
383
432
  return row;
384
433
  } catch (error) {
385
434
  if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
@@ -401,37 +450,21 @@ export async function startJobHost(options: JobHostOptions): Promise<JobOwnerHos
401
450
  reused: true, stop: () => session.dispose()};
402
451
  }
403
452
  claim = acquired.claim;
404
- let front: ReturnType<typeof createJobFront>;
405
- let ports: JobHostPorts;
453
+ let context: ReturnType<typeof createJobRequestContext>;
406
454
  const preferredPort = startup.port ?? previousPort;
407
455
  const server = Bun.serve({hostname: '127.0.0.1', port: preferredPort, idleTimeout: 0,
408
- async fetch(request) {
409
- const url = new URL(request.url);
410
- if (url.pathname === `/jobs/${session.jobId}/host`) {
411
- if (url.origin !== origin || request.method !== 'GET' || url.search ||
412
- request.headers.get('sec-fetch-site') === 'cross-site' ||
413
- request.headers.get('origin') !== null && request.headers.get('origin') !== origin) return failure('JOB_REQUEST_INVALID', 403);
414
- try {session.authorize('ui', request.headers.get('X-Review-Capability'));}
415
- catch {return failure('JOB_CAPABILITY_REQUIRED', 403);}
416
- return Response.json(record, {headers});
417
- }
418
- return await front.fetch(request) ?? failure('JOB_REQUEST_INVALID', 404);
419
- },
456
+ fetch(request) {return context.fetch(request);},
420
457
  });
421
458
  const origin = `http://127.0.0.1:${server.port}`;
422
- const record: JobHostRecord = {schema: 'rig-review-job-host/1', apiSchema: JOB_API_SCHEMA, actSchema: JOB_ACT_SCHEMA,
423
- partsEnumeratorId, partsEnumeratorVersion, jobId: session.jobId, origin,
424
- fingerprint: startup.fingerprint, pid: process.pid, readerId, bindingId};
425
- ports = createJobHostPorts(session, origin);
426
- front = createJobFront({origin, ports, resource: jobWindowResources(),
427
- publication: retainedPublicationRoutes(session)});
459
+ context = createJobRequestContext(session, startup, origin, identity);
460
+ const {ports, record} = context;
428
461
  const closed = new AbortController();
429
462
  let stopped = false;
430
463
  stop = () => {
431
464
  if (stopped) return;
432
465
  stopped = true;
433
466
  closed.abort();
434
- front.stop();
467
+ context.stop();
435
468
  server.stop(true);
436
469
  session.dispose();
437
470
  };
package/src/job-host.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  /** Stable installed managed owner host and semantic A/B contract. See docs/STABILITY.md. */
2
2
  export {startJobHost} from './job-front.ts';
3
+ export {startJobHub} from './job-hub.ts';
4
+ export type {JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub} from './job-hub.ts';
3
5
  export type {JobHostOptions, JobOwnerHost} from './job-front.ts';
4
6
  export type {JobSessionOptions, JobSession} from './job-session.ts';
5
7
  export type {JobWorkerOptions} from './job-worker.ts';