@rig-c/review 1.17.0 → 1.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/docs/DESIGN.md +2 -2
- package/docs/REVIEW_PACKAGE.md +2 -2
- package/docs/STABILITY.md +213 -0
- package/docs/WORKFLOWS.md +2 -2
- package/package.json +5 -3
- package/skills/rig-review/SKILL.md +2 -2
- package/src/job-host.ts +66 -0
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
|
|
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.
|
|
48
48
|
|
|
49
49
|
Example stdout from `open` (instance values vary):
|
|
50
50
|
|
package/docs/DESIGN.md
CHANGED
|
@@ -157,13 +157,13 @@ their missing consumer contracts; no tools are fabricated for them.
|
|
|
157
157
|
|
|
158
158
|
### Standing live job boundary
|
|
159
159
|
|
|
160
|
-
`src/job-contract.ts` freezes the semantic live-job boundary (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session open|publish|ask|next|close` CLI (`src/entry.ts`, `src/job-cli.ts`).
|
|
160
|
+
`src/job-contract.ts` freezes the semantic live-job boundary (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session open|publish|ask|next|close` CLI (`src/entry.ts`, `src/job-cli.ts`). 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). See [Live job contract](REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow).
|
|
161
161
|
|
|
162
162
|
- **One standing window and owner visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media remain internal. A missing required visual (`visual.status` set to `'unavailable'`) is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
|
|
163
163
|
- **Human UI authority vs agent verbs.** People submit finalized acts through the browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`) under a bootstrap-declared `reviewer` (`id` and `role` as `'owner'` or `'delegate'`). That reviewer binding is declared by trusted host bootstrap, cannot be typed or overridden in the browser UI, represents provenance rather than keyboard-user authentication, and maps to Create's existing `by` authority. Agents use `publish`, `ask`, `next` and `close` with `expectedGeneration` CAS and `idempotencyKey`. `publish` requires an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record`) held until acknowledgment as a caller obligation, with no watched-root or automatic-close guarantee. Only explicit `close` ends an active job.
|
|
164
164
|
- **Exact displayed source, cursor replay and draft retention.** Finalized acts and job events replay through durable cursors (`next` and `subscribeJob`). The daemon derives `JobSourceBinding` from validated retained bytes and the page-scoped `displayedNonce` receipt rather than browser-supplied hashes. When a new publication updates the displayed source, old local drafts remain retained for their original source binding and are flagged without rebinding onto the new publication.
|
|
165
165
|
- **Enabled vs reserved act kinds.** Five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`) while `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`). Checkpoint acts carry `pass` or `fail` only (`pending` is UI draft only) and require `words` as a string preserved verbatim including empty or whitespace-only text, with `planStepId` copied by the daemon from the validated ask and stage derived by Create. Signoff acts carry `approved` only with required verbatim `words` (empty or whitespace-only allowed) and remain separate from verdicts and Create stage transitions. Plan-bound signoffs (`plan-approved`, `rigging-interview`, `post-interview`) and checkpoints use step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, parts bindings (`JobPartsIdentity`) are limited to the declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal `parts/*.png` images plus exact `painting_in_rig.png` beside `parts.json` (root or project prefix only) — so `figure_mask` is missing and C3 is not yet a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without a Review field parser. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding while unreferenced stale extras are excluded.
|
|
166
|
-
- **Writer-owned sibling fetch,
|
|
166
|
+
- **Writer-owned sibling fetch, public host seam and legacy file handoffs.** [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads via a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration), never tracked in version control or unstaged project output, never constructed or carried by agents, dead at explicit `close`, and renewed on each job incarnation. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` and `bindingId`; equality governs listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside the active cycle. Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files, and existing `--picks-file`, saved verdict path, reshaped feedback JSON and `--verbatim-file` handoffs are legacy/history bypass findings for the active cycle.
|
|
167
167
|
- **Direction scope.** Direction carriage in `#484` is metadata-only and distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) remains parked.
|
|
168
168
|
|
|
169
169
|
Stage 1 in a single compiled inspection with a producer handoff shows the
|
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -1017,7 +1017,7 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
|
|
|
1017
1017
|
|
|
1018
1018
|
## Live job contract
|
|
1019
1019
|
|
|
1020
|
-
`src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@1`) and `JOB_ACT_SCHEMA` (`rig-review/act@1`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`).
|
|
1020
|
+
`src/job-contract.ts` defines the frozen semantic contract boundary for [Review #484](https://github.com/rig-c/review/issues/484), [Create #182](https://github.com/rig-c/create/issues/182), [Create #184](https://github.com/rig-c/create/issues/184), [Parts #1159](https://github.com/rig-c/parts/issues/1159) and [Parts #1163](https://github.com/rig-c/parts/issues/1163) under `JOB_API_SCHEMA` (`rig-review/job-api@1`) and `JOB_ACT_SCHEMA` (`rig-review/act@1`), implemented across the backend session/store (`src/job-store.ts`, `src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`, `src/job-worker.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). 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.
|
|
1021
1021
|
|
|
1022
1022
|
### Vocabulary, authority, CLI and host ports
|
|
1023
1023
|
|
|
@@ -1030,7 +1030,7 @@ In the standing live-job contract ([Review #484](https://github.com/rig-c/review
|
|
|
1030
1030
|
- `rig-review session close <job-url> --generation <n> --key <id> --reason <words> [--request-id <id>]`
|
|
1031
1031
|
Agent verbs authenticate with `RIG_REVIEW_JOB_AGENT_CAPABILITY` (`Authorization: Bearer …`) against `http://127.0.0.1:<port>/jobs/<jobId>` and refuse `fetch-act` (`JOB_AUTHORITY_REFUSED`). See [Standing live job workflow](WORKFLOWS.md#standing-live-job-workflow) for an ordinary-package launch, bootstrap and explicit close example.
|
|
1032
1032
|
- **Bootstrap-declared reviewer.** `JobReviewerBinding` (`id` and `role` as `'owner'` or `'delegate'` inside `JobHumanAuthority`) is declared by trusted host bootstrap when opening the window. The browser UI cannot type, edit or override this binding. It records bootstrap-declared provenance rather than keyboard-user authentication. Create maps `role` to its existing `by` authority and preserves the declared reviewer identity.
|
|
1033
|
-
- **Trusted host ports and
|
|
1033
|
+
- **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` and `bindingId?: string`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), each present hook (`readPublished`, `installWriterBinding`) requires a nonempty declared ID and a missing hook requires its ID to be absent (`JOB_HOST_OPTION_ID_INVALID`). Equal declared IDs permit listener reuse across processes and newly allocated function objects via `/jobs/<jobId>/host` (`schema: 'rig-review-job-host/1'`); differing IDs, hook-presence differences and unrecorded older listener IDs fail by name (`JOB_HOST_REUSE_MISMATCH`) with the option name and both IDs while preserving the existing listener. No function hashes are used. `installWriterBinding` receives `{jobId, origin, fetchCapability}` after reuse validation and runs on a matching new or reused host.
|
|
1034
1034
|
- **Standing window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line (a job survives zero open owner tabs and reuses the same active job/link on later `session open` until explicit `close`). Internal agent and HQ media stay internal. Each `JobPublication` reports `visual` with `status` set to `'available'` or `'unavailable'` with a named `code`. A missing required visual is an immediate stop plus a Create-filed on-path Review card, never a chat fallback.
|
|
1035
1035
|
|
|
1036
1036
|
### Publication, producer-held freeze and generation CAS
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# Public API stability
|
|
2
|
+
|
|
3
|
+
## Managed owner host
|
|
4
|
+
|
|
5
|
+
`@rig-c/review/job-host` is the installed Bun entry for the full standing owner
|
|
6
|
+
window and the semantic A/B host ports, introduced by Review #489. The CLI and
|
|
7
|
+
`@rig-c/review/package.json` remain supported.
|
|
8
|
+
|
|
9
|
+
The named exports and signatures below are the supported import contract.
|
|
10
|
+
Changes to them require an explicit public-contract review. The facade reexports
|
|
11
|
+
the existing implementation and semantic types directly. The semantic schemas
|
|
12
|
+
and behavior are defined in [Live job contract](REVIEW_PACKAGE.md#live-job-contract).
|
|
13
|
+
The current C3 parts binding and the separately queued C4 work remain governed
|
|
14
|
+
by that reference.
|
|
15
|
+
|
|
16
|
+
At C4 ([Review #501](https://github.com/rig-c/review/issues/501)), `JobPartsManifestPath`, `JobPartImagePath` and `JobPartsIdentity` will change, together with their embedding public types `JobHostOptions`, `JobOwnerHost`, `JobSessionOptions`, `JobSession`, `JobWorkerOptions`, `JobPublicationReader`, `JobPublishedContext`, `JobSourceBinding`, `JobActSources`, `JobAct`, `JobPendingAsk`, `JobPublication`, `JobStatus`, `JobEvent`, `JobNextValue`, `JobResponseValues`, `JobApiResponse`, `JobDisplayPublication` and `JobHostPorts`. This is a declared contract revision that must bump `JOB_API_SCHEMA` and receive HQ sign-off. Current-schema consumers must named-refuse a schema mismatch and must never silently interpret an incompatible payload. The installed smoke control `SMOKE_PUBLIC_HOST_SCHEMA_MISMATCH_REFUSED` sends an unsupported schema through the public host, verifies HTTP 400 with `JOB_REQUEST_INVALID` and the current response schema, and checks that generation remains unchanged, exercising the existing `parseJobRequest` schema guard. [Installed control](https://github.com/rig-c/review/blob/main/scripts/install-smoke.ts#L152), [schema guard](https://github.com/rig-c/review/blob/main/src/job-api.ts#L131).
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import {startJobHost} from '@rig-c/review/job-host';
|
|
20
|
+
import type {
|
|
21
|
+
JobHostOptions, JobOwnerHost, JobHostPorts,
|
|
22
|
+
JobSessionOptions, JobSession, JobWorkerOptions,
|
|
23
|
+
JobPublicationReader, JobPublishedContext,
|
|
24
|
+
} from '@rig-c/review/job-host';
|
|
25
|
+
|
|
26
|
+
function startJobHost(options: JobHostOptions): Promise<JobOwnerHost>;
|
|
27
|
+
|
|
28
|
+
interface JobSessionOptions {
|
|
29
|
+
readonly root: string;
|
|
30
|
+
readonly stateDir: string;
|
|
31
|
+
readonly fingerprint: string;
|
|
32
|
+
readonly reviewer: JobReviewerBinding;
|
|
33
|
+
readonly readPublished?: JobPublicationReader;
|
|
34
|
+
readonly afterSnapshot?: () => void | Promise<void>;
|
|
35
|
+
readonly afterDirectorySync?: (path: string) => void;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
interface JobWorkerOptions extends JobSessionOptions {
|
|
39
|
+
readonly port?: number;
|
|
40
|
+
readonly installWriterBinding?: (binding: {
|
|
41
|
+
readonly jobId: string;
|
|
42
|
+
readonly origin: string;
|
|
43
|
+
readonly fetchCapability: string;
|
|
44
|
+
}) => void | Promise<void>;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
interface JobHostOptions extends JobWorkerOptions {
|
|
48
|
+
readonly readerId?: string;
|
|
49
|
+
readonly bindingId?: string;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
type JobPublicationReader = (input: {
|
|
53
|
+
readonly root: string;
|
|
54
|
+
readonly record: JobFileIdentity;
|
|
55
|
+
readonly result: JobPublishRequest['result'];
|
|
56
|
+
}) => Promise<JobPublishedContext>;
|
|
57
|
+
|
|
58
|
+
interface JobPublishedContext {
|
|
59
|
+
readonly selector: JobSelector | null;
|
|
60
|
+
readonly plan: JobPlanIdentity | null;
|
|
61
|
+
readonly parts: JobPartsIdentity | null;
|
|
62
|
+
readonly subjects: readonly JobSubject[];
|
|
63
|
+
readonly partIds: readonly string[];
|
|
64
|
+
readonly files: readonly JobFileIdentity[];
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
interface JobOwnerHost {
|
|
68
|
+
readonly session: JobSession;
|
|
69
|
+
readonly ports: JobHostPorts;
|
|
70
|
+
readonly origin: string;
|
|
71
|
+
readonly ownerUrl: string;
|
|
72
|
+
readonly reused: boolean;
|
|
73
|
+
stop(): void;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
interface JobHostPorts {
|
|
77
|
+
handleJobApi(request: Request): Promise<Response>;
|
|
78
|
+
subscribeJob(input: {
|
|
79
|
+
readonly jobId: JobId;
|
|
80
|
+
readonly after: JobCursor | null;
|
|
81
|
+
readonly signal: AbortSignal;
|
|
82
|
+
}): AsyncIterable<JobEvent>;
|
|
83
|
+
readPublication(jobId: JobId, publicationId: JobPublicationId): Promise<JobResult<JobDisplayPublication>>;
|
|
84
|
+
commitUIAct(jobId: JobId, request: Request): Promise<JobResult<JobAct>>;
|
|
85
|
+
ackDisplayed(jobId: JobId, request: Request): Promise<JobResult<JobDisplayReceipt>>;
|
|
86
|
+
jobLiveness(jobId: JobId): Promise<JobResult<{
|
|
87
|
+
readonly active: boolean;
|
|
88
|
+
readonly busy: boolean;
|
|
89
|
+
}>>;
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`root` designates the producer work root. `stateDir` must be outside that root.
|
|
94
|
+
`fingerprint` identifies compatible host inputs, and `reviewer` is the trusted
|
|
95
|
+
bootstrap binding. `port` selects a loopback listener port, with `0` selecting an
|
|
96
|
+
available port. `ownerUrl` opens the shipped standing owner page with its private
|
|
97
|
+
UI capability fragment. `origin` and the returned `ports` belong to that host.
|
|
98
|
+
|
|
99
|
+
A present `readPublished` callback requires a nonempty `readerId`. A present
|
|
100
|
+
`installWriterBinding` callback requires a nonempty `bindingId`. Each ID must be
|
|
101
|
+
absent when its callback is absent. Violations reject startup with
|
|
102
|
+
`JOB_HOST_OPTION_ID_INVALID`. Equal declared IDs permit active-listener reuse
|
|
103
|
+
across processes and newly allocated function objects. Changed or unrecorded IDs
|
|
104
|
+
reject with `JOB_HOST_REUSE_MISMATCH`, including the option name, listener ID and
|
|
105
|
+
requested ID. The caller owns the semantic meaning of those IDs.
|
|
106
|
+
|
|
107
|
+
`readPublished` supplies the producer's published semantic context for the exact
|
|
108
|
+
frozen record. `installWriterBinding` receives the private finalized-act fetch
|
|
109
|
+
grant after reuse validation on each successful new or reused startup. The trusted
|
|
110
|
+
writer adapter owns its private binding and storage. A callback failure rejects
|
|
111
|
+
startup with `JOB_AUTHORITY_REFUSED`. `afterSnapshot` and `afterDirectorySync` are
|
|
112
|
+
optional disposable-test boundary hooks inherited from the existing seam.
|
|
113
|
+
|
|
114
|
+
`session` retains its existing trusted-host `JobSession` type, including
|
|
115
|
+
`jobId`, `hostCredentials()` and `status()` for bootstrap and inspection.
|
|
116
|
+
`JobSession` is exported as a type for `host.session`. The host separates agent, owner UI and writer
|
|
117
|
+
credentials through their respective channels. Only explicit semantic `close`
|
|
118
|
+
ends a job and revokes its writer grant. `stop()` disposes this host handle and
|
|
119
|
+
stops its owned listener. A reused handle disposes its local session.
|
|
120
|
+
|
|
121
|
+
The runtime entry starts the full owner host with retained publication routes
|
|
122
|
+
and shipped HTML, JavaScript and CSS. Raw Requests and the existing A/B ports
|
|
123
|
+
preserve capability, origin, size, cancellation and replay checks.
|
|
124
|
+
|
|
125
|
+
## Named export inventory
|
|
126
|
+
|
|
127
|
+
The exact runtime exports are listed below. Constants preserve their literal
|
|
128
|
+
values from the frozen semantic contract.
|
|
129
|
+
|
|
130
|
+
- `startJobHost`
|
|
131
|
+
- `JOB_API_SCHEMA`
|
|
132
|
+
- `JOB_ACT_SCHEMA`
|
|
133
|
+
- `JOB_ENABLED_ACT_KINDS`
|
|
134
|
+
- `JOB_RESERVED_ACT_KINDS`
|
|
135
|
+
- `JOB_PLAN_BOUND_SIGNOFF_STAGES`
|
|
136
|
+
- `JOB_CONSUMER_AUTH_MODE`
|
|
137
|
+
- `JOB_ERROR_CODES`
|
|
138
|
+
|
|
139
|
+
The exact type-only exports follow. Their existing definitions in
|
|
140
|
+
`src/job-contract.ts`, `src/job-source.ts`, `src/job-session.ts`,
|
|
141
|
+
`src/job-worker.ts` and `src/job-front.ts` are reexported
|
|
142
|
+
without aliases or copied wire shapes.
|
|
143
|
+
|
|
144
|
+
- `JobHostOptions`
|
|
145
|
+
- `JobOwnerHost`
|
|
146
|
+
- `JobSessionOptions`
|
|
147
|
+
- `JobSession`
|
|
148
|
+
- `JobWorkerOptions`
|
|
149
|
+
- `JobPublicationReader`
|
|
150
|
+
- `JobPublishedContext`
|
|
151
|
+
- `JobEnabledActKind`
|
|
152
|
+
- `JobReservedActKind`
|
|
153
|
+
- `JobActKind`
|
|
154
|
+
- `JobSha256`
|
|
155
|
+
- `JobId`
|
|
156
|
+
- `JobPublicationId`
|
|
157
|
+
- `JobAskId`
|
|
158
|
+
- `JobActId`
|
|
159
|
+
- `JobCursor`
|
|
160
|
+
- `JobFileIdentity`
|
|
161
|
+
- `JobPlanStepIdentity`
|
|
162
|
+
- `JobPlanIdentity`
|
|
163
|
+
- `JobPartsManifestPath`
|
|
164
|
+
- `JobPartImagePath`
|
|
165
|
+
- `JobPartsIdentity`
|
|
166
|
+
- `JobSelector`
|
|
167
|
+
- `JobSourceBinding`
|
|
168
|
+
- `JobReviewerBinding`
|
|
169
|
+
- `JobHumanAuthority`
|
|
170
|
+
- `JobVerdict`
|
|
171
|
+
- `JobPartOutcome`
|
|
172
|
+
- `JobReviewStage`
|
|
173
|
+
- `JobActValues`
|
|
174
|
+
- `JobUIActValues`
|
|
175
|
+
- `JobActSources`
|
|
176
|
+
- `JobAct`
|
|
177
|
+
- `JobSubject`
|
|
178
|
+
- `JobPendingAsk`
|
|
179
|
+
- `JobPublication`
|
|
180
|
+
- `JobStatus`
|
|
181
|
+
- `JobPublishRequest`
|
|
182
|
+
- `JobAskRequest`
|
|
183
|
+
- `JobNextRequest`
|
|
184
|
+
- `JobCloseRequest`
|
|
185
|
+
- `JobAgentRequest`
|
|
186
|
+
- `JobFetchActRequest`
|
|
187
|
+
- `JobErrorCode`
|
|
188
|
+
- `JobFailure`
|
|
189
|
+
- `JobResult`
|
|
190
|
+
- `JobEvent`
|
|
191
|
+
- `JobNextValue`
|
|
192
|
+
- `JobResponseValues`
|
|
193
|
+
- `JobApiResponse`
|
|
194
|
+
- `JobUISubmission`
|
|
195
|
+
- `JobDisplayAcknowledgment`
|
|
196
|
+
- `JobDisplayReceipt`
|
|
197
|
+
- `JobDisplayPublication`
|
|
198
|
+
- `JobHostPorts`
|
|
199
|
+
- `JobConsumerGrant`
|
|
200
|
+
|
|
201
|
+
## Installed acceptance
|
|
202
|
+
|
|
203
|
+
`bun run smoke` packs the package and installs that tarball into an empty project.
|
|
204
|
+
A consumer imports the runtime and every listed type through
|
|
205
|
+
`@rig-c/review/job-host`. TypeScript checks the installed consumer and the runtime
|
|
206
|
+
checks the full owner resources, retained publication, semantic ports, declared
|
|
207
|
+
hooks, reuse and explicit-close grant lifetime using synthetic host data.
|
|
208
|
+
|
|
209
|
+
The declared export-removal control deletes only `./job-host` from the disposable
|
|
210
|
+
installed manifest and requires the public import to fail for that missing
|
|
211
|
+
subpath. It restores the exact manifest bytes, verifies their SHA-256 and imports
|
|
212
|
+
again. The smoke prints the planned RED's raw exit and diagnostic. This control
|
|
213
|
+
runs inside the ordinary installed smoke, alongside existing CLI coverage.
|
package/docs/WORKFLOWS.md
CHANGED
|
@@ -360,7 +360,7 @@ The managed front forwards only the trusted stage-atlas frame query (`stageEmbed
|
|
|
360
360
|
|
|
361
361
|
## Standing live job workflow
|
|
362
362
|
|
|
363
|
-
The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`).
|
|
363
|
+
The active Create and Parts inspection cycle uses the semantic job contract in `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)) together with the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). 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.
|
|
364
364
|
|
|
365
365
|
Exact CLI usage from `src/entry.ts` and `src/job-cli.ts` (`publish`, `ask`, `next` and `close` also accept optional `--request-id <id>`):
|
|
366
366
|
|
|
@@ -401,7 +401,7 @@ rig-review session close http://127.0.0.1:<port>/jobs/<job-id> \
|
|
|
401
401
|
- **Exact displayed source and retained drafts.** The daemon derives `JobSourceBinding` from validated retained bytes and the actual displayed publication (`ackDisplayed` returning a page-scoped `displayedNonce` receipt, pinned same-origin `routes` with no mutable current alias). All metadata, images, runtime assets, routes and pending form dependencies prepare before the visible swap; paint and the single `displayedNonce` acknowledgment precede retirement of the previous view, and failed preparation or acknowledgment restores the prior view and draft. Clients never supply trusted source hashes or transfer prior approval onto a new binding. When a new publication updates the displayed source, old local drafts remain retained in storage for their original source binding and are flagged without rebinding onto the new publication.
|
|
402
402
|
- **Finalized acts, five enabled kinds and cursor replay.** `next` (`after` cursor and bounded abortable `waitMs` that never consumes an act) and `subscribeJob` replay complete durable `JobEvent` records (`published`, `pending`, `act`, `closed`). Only five act kinds are enabled (`interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict`, `signoff`). `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay reserved and disabled (`JOB_ACT_KIND_DISABLED`).
|
|
403
403
|
- **Checkpoints, signoffs, plan steps and parts PNGs.** In `checkpoint` acts, `outcome` is `'pass'` or `'fail'` only (`'pending'` stays in the UI draft and never produces a finalized act), and required `words` is preserved verbatim as a string including empty or whitespace-only text. The browser sends `checkpointId`, `outcome` and `words` only while the daemon copies resolved `planStepId` from the validated ask, and Create derives execution stage from its authoritative step phase and order without Review stamping a stage. Only `'pass'` is eligible for Create's checkpoint sign-off writer, while `'fail'` is feedback or a named consumer refusal. In `signoff` acts, `decision` is `'approved'` only (changes requested are a verdict) with required `words` preserved verbatim including empty or whitespace-only text. A verdict, a signoff and a Create stage transition are three separate writes, and plan-bound signoff stages (`plan-approved`, `rigging-interview`, `post-interview`) require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) without Review recomputing `stepHash`. In the current C3 runtime, `JobPartsIdentity` is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal images at `parts/*.png` (`parts/${string}.png` or `${string}/parts/${string}.png`) plus exact `painting_in_rig.png` beside `parts.json` at the root or project prefix only (`painting_in_rig.png` or `${string}/painting_in_rig.png`) — so `figure_mask` is missing and C3 does not yet cover a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), so Review verifies producer-enumerated paths and bytes without parsing `parts.json` fields itself. Within the current C3 set, missing or changed referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding, while unreferenced stale extra files are excluded without refusal.
|
|
404
|
-
- **No agent file carriage, writer-owned sibling fetch and
|
|
404
|
+
- **No agent file carriage, writer-owned sibling fetch and public host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and act fetch through a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration). That binding is never tracked in version control or unstaged project output, dies at explicit `close` with a new grant per job incarnation, and grants read-only `fetch-act` over loopback with `Authorization`. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` for `readPublished` and `bindingId` for `installWriterBinding`; missing or invalid IDs refuse with `JOB_HOST_OPTION_ID_INVALID`, and listener reuse requires equal `readerId` and `bindingId` or refuses with `JOB_HOST_REUSE_MISMATCH` (with no function hashes). Future mesh-edit consumption is owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159), where Create fetches a finalized mesh act and passes its typed value in process to Parts' public exported API without Parts reading Review or Create storage.
|
|
405
405
|
- **Direction metadata vs playback.** Direction carriage in `#484` is metadata-only (`source.direction` and `direction-review`) and is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) stays parked.
|
|
406
406
|
|
|
407
407
|
## Create choice interview
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rig-c/review",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.18.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Local human rig inspection and structured feedback export",
|
|
6
6
|
"license": "MIT",
|
|
@@ -21,11 +21,11 @@
|
|
|
21
21
|
"dependencies": {
|
|
22
22
|
"@napi-rs/canvas": "1.0.11",
|
|
23
23
|
"@rig-c/play": "1.23.0",
|
|
24
|
+
"@types/pngjs": "6.0.5",
|
|
24
25
|
"pngjs": "7.0.0"
|
|
25
26
|
},
|
|
26
27
|
"devDependencies": {
|
|
27
28
|
"@types/bun": "^1.3.0",
|
|
28
|
-
"@types/pngjs": "6.0.5",
|
|
29
29
|
"typescript": "^5.9.3"
|
|
30
30
|
},
|
|
31
31
|
"engines": {
|
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
"docs/WORKFLOWS.md",
|
|
43
43
|
"docs/PANELS.md",
|
|
44
44
|
"docs/DESIGN.md",
|
|
45
|
+
"docs/STABILITY.md",
|
|
45
46
|
"docs/ANIMATION_INSPECTION.md",
|
|
46
47
|
"docs/LIVE_FIXTURE.md",
|
|
47
48
|
"docs/PARTS_VIEW.md",
|
|
@@ -50,7 +51,8 @@
|
|
|
50
51
|
"LICENSE"
|
|
51
52
|
],
|
|
52
53
|
"exports": {
|
|
53
|
-
"./package.json": "./package.json"
|
|
54
|
+
"./package.json": "./package.json",
|
|
55
|
+
"./job-host": "./src/job-host.ts"
|
|
54
56
|
},
|
|
55
57
|
"repository": {
|
|
56
58
|
"type": "git",
|
|
@@ -12,7 +12,7 @@ or to read back their submitted review.
|
|
|
12
12
|
|
|
13
13
|
## Active cycle standing live-job contract
|
|
14
14
|
|
|
15
|
-
For the active Create and Parts cycle, the authoritative contract is `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`).
|
|
15
|
+
For the active Create and Parts cycle, the authoritative contract is `src/job-contract.ts` (`JOB_API_SCHEMA` set to `rig-review/job-api@1`, `JOB_ACT_SCHEMA` set to `rig-review/act@1`, [Review #484](https://github.com/rig-c/review/issues/484)), backed by the implemented backend session/store (`src/job-session.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-api.ts`), standing loopback job front and browser window runtime (`src/job-front.ts`, `web/job-session.ts`), and `rig-review session` CLI (`src/entry.ts`, `src/job-cli.ts`). The public installed managed-host entry is `@rig-c/review/job-host` with frozen exports in [Public API stability](https://github.com/rig-c/review/blob/main/docs/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`). Do not invent public export names, producer scene fields or unimplemented flags, and never expose capabilities in reports or logs. See [Live job contract](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md#live-job-contract) and [Standing live job workflow](https://github.com/rig-c/review/blob/main/docs/WORKFLOWS.md#standing-live-job-workflow).
|
|
16
16
|
|
|
17
17
|
Exact CLI namespace (`src/entry.ts`, `src/job-cli.ts`; `publish`, `ask`, `next`, `close` also accept optional `--request-id <id>`):
|
|
18
18
|
|
|
@@ -53,7 +53,7 @@ rig-review session close http://127.0.0.1:<port>/jobs/<job-id> \
|
|
|
53
53
|
- **Exact displayed source, cursor replay and draft retention.** `next` (`after` cursor and bounded abortable `waitMs` that never consumes an act) replays complete durable `JobEvent` items (`published`, `pending`, `act`, `closed`). The daemon derives `JobSourceBinding` from validated retained bytes and the page-scoped `displayedNonce` receipt rather than browser-supplied hashes. When a new publication replaces or updates the displayed source, old local drafts remain retained for their original source binding and are flagged without rebinding onto the new publication.
|
|
54
54
|
- **Five enabled act kinds and two reserved disabled kinds.** Enabled kinds are `interview-picks`, `checkpoint`, `parts-verdict`, `review-verdict` and `signoff`. Reserved kinds `described-correction` (awaiting the joint [Create #182](https://github.com/rig-c/create/issues/182) context allowlist) and `mesh-edit` (awaiting the joint [Parts #1159](https://github.com/rig-c/parts/issues/1159) freeze) stay disabled (`JOB_ACT_KIND_DISABLED`) and cannot be asked or submitted.
|
|
55
55
|
- **Checkpoints, signoffs, plan steps and parts PNGs.** Finalized `checkpoint` acts carry `outcome` `'pass'` or `'fail'` only (`'pending'` stays in the UI draft), require `words` as a string preserved verbatim including empty or whitespace-only text, copy `planStepId` from the validated ask on the daemon while the browser sends `checkpointId`, `outcome` and `words` only, and leave stage derivation to Create (only `'pass'` is eligible for Create's checkpoint sign-off writer). Finalized `signoff` acts carry `decision` `'approved'` only with required `words` preserved verbatim including empty or whitespace-only text, remain separate from verdicts and Create stage transitions, and require `source.plan` with exact displayed step IDs and hashes published by [Create #184](https://github.com/rig-c/create/issues/184) (without Review recomputing `stepHash`) on `plan-approved`, `rigging-interview` and `post-interview`. In the current C3 runtime, `JobPartsIdentity` is limited to its declared four roles (`part`, `alternate`, `depth`, `painting`) and path restriction — normal `parts/*.png` images plus exact `painting_in_rig.png` beside `parts.json` (root or project prefix only) — so `figure_mask` is missing and C3 is not yet a complete manifest-referenced parts PNG inventory. C4 ([Review #501](https://github.com/rig-c/review/issues/501)) is queued to bind the `@rig-c/parts` `2.25.0` `partsFileReferences` result per Parts `STABILITY` at `62208d6` ([Parts #1163](https://github.com/rig-c/parts/issues/1163)) together with [Create #184](https://github.com/rig-c/create/issues/184), which owns the roles without a Review field parser. Within the current C3 set, changed or missing referenced bytes (including a referenced `painting_in_rig.png`) invalidate the binding while unreferenced stale extras are excluded.
|
|
56
|
-
- **No agent file carriage, writer-owned sibling fetch and
|
|
56
|
+
- **No agent file carriage, writer-owned sibling fetch and public host seam.** Agents never build, parse, reshape or carry Review session, picks, verdict or applied-record storage files. [Create #182](https://github.com/rig-c/create/issues/182) and [Create #184](https://github.com/rig-c/create/issues/184) own direct writer publication and `fetch-act` reads using a private writer-owned sibling binding outside `project.json` (`writer-owned-sibling-fetch-capability`, pending Create #184 production reader/writer integration) that is never tracked in version control or unstaged project output, dies at explicit `close` and receives a new grant on each job incarnation. In the public managed-host startup seam (`startJobHost` from `@rig-c/review/job-host`, frozen in [Public API stability](https://github.com/rig-c/review/blob/main/docs/STABILITY.md#managed-owner-host)), hook-bearing host callers declare `readerId` and `bindingId`; equality governs listener reuse and missing or mismatched IDs refuse by name (`JOB_HOST_OPTION_ID_INVALID`, `JOB_HOST_REUSE_MISMATCH`) with no function hashes. Future mesh acts will be fetched by Create and passed in process to Parts' public exported API owned by [Parts #1159](https://github.com/rig-c/parts/issues/1159) without Parts reading Review or Create storage, while standalone `--delta` remains legacy outside this cycle.
|
|
57
57
|
- **Direction metadata vs playback.** Direction carriage in `#484` is metadata-only (`source.direction` and `direction-review`) and is distinct from [Review #482](https://github.com/rig-c/review/issues/482) preview and [Review #483](https://github.com/rig-c/review/issues/483) actual plated take playback, while [Review #373](https://github.com/rig-c/review/issues/373) stays parked.
|
|
58
58
|
|
|
59
59
|
## What an agent drives vs. what the person drives
|
package/src/job-host.ts
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/** Stable installed managed owner host and semantic A/B contract. See docs/STABILITY.md. */
|
|
2
|
+
export {startJobHost} from './job-front.ts';
|
|
3
|
+
export type {JobHostOptions, JobOwnerHost} from './job-front.ts';
|
|
4
|
+
export type {JobSessionOptions, JobSession} from './job-session.ts';
|
|
5
|
+
export type {JobWorkerOptions} from './job-worker.ts';
|
|
6
|
+
export type {JobPublicationReader, JobPublishedContext} from './job-source.ts';
|
|
7
|
+
export {
|
|
8
|
+
JOB_API_SCHEMA,
|
|
9
|
+
JOB_ACT_SCHEMA,
|
|
10
|
+
JOB_ENABLED_ACT_KINDS,
|
|
11
|
+
JOB_RESERVED_ACT_KINDS,
|
|
12
|
+
JOB_PLAN_BOUND_SIGNOFF_STAGES,
|
|
13
|
+
JOB_CONSUMER_AUTH_MODE,
|
|
14
|
+
JOB_ERROR_CODES,
|
|
15
|
+
} from './job-contract.ts';
|
|
16
|
+
export type {
|
|
17
|
+
JobEnabledActKind,
|
|
18
|
+
JobReservedActKind,
|
|
19
|
+
JobActKind,
|
|
20
|
+
JobSha256,
|
|
21
|
+
JobId,
|
|
22
|
+
JobPublicationId,
|
|
23
|
+
JobAskId,
|
|
24
|
+
JobActId,
|
|
25
|
+
JobCursor,
|
|
26
|
+
JobFileIdentity,
|
|
27
|
+
JobPlanStepIdentity,
|
|
28
|
+
JobPlanIdentity,
|
|
29
|
+
JobPartsManifestPath,
|
|
30
|
+
JobPartImagePath,
|
|
31
|
+
JobPartsIdentity,
|
|
32
|
+
JobSelector,
|
|
33
|
+
JobSourceBinding,
|
|
34
|
+
JobReviewerBinding,
|
|
35
|
+
JobHumanAuthority,
|
|
36
|
+
JobVerdict,
|
|
37
|
+
JobPartOutcome,
|
|
38
|
+
JobReviewStage,
|
|
39
|
+
JobActValues,
|
|
40
|
+
JobUIActValues,
|
|
41
|
+
JobActSources,
|
|
42
|
+
JobAct,
|
|
43
|
+
JobSubject,
|
|
44
|
+
JobPendingAsk,
|
|
45
|
+
JobPublication,
|
|
46
|
+
JobStatus,
|
|
47
|
+
JobPublishRequest,
|
|
48
|
+
JobAskRequest,
|
|
49
|
+
JobNextRequest,
|
|
50
|
+
JobCloseRequest,
|
|
51
|
+
JobAgentRequest,
|
|
52
|
+
JobFetchActRequest,
|
|
53
|
+
JobErrorCode,
|
|
54
|
+
JobFailure,
|
|
55
|
+
JobResult,
|
|
56
|
+
JobEvent,
|
|
57
|
+
JobNextValue,
|
|
58
|
+
JobResponseValues,
|
|
59
|
+
JobApiResponse,
|
|
60
|
+
JobUISubmission,
|
|
61
|
+
JobDisplayAcknowledgment,
|
|
62
|
+
JobDisplayReceipt,
|
|
63
|
+
JobDisplayPublication,
|
|
64
|
+
JobHostPorts,
|
|
65
|
+
JobConsumerGrant,
|
|
66
|
+
} from './job-contract.ts';
|