@rig-c/review 4.7.0 → 4.9.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.
@@ -1233,9 +1233,7 @@ except for the limit refusal.
1233
1233
  The publisher emits this field only when installed Review exports
1234
1234
  `JOB_PREVIOUS_DRAFT_SCHEMA` with value `rig-review-previous-draft/1` from
1235
1235
  `@rig-c/review/job-host`. This is the publisher-to-Review capability rule.
1236
- Both new act keys require an admitted `previousDraft`. That admission is
1237
- their emission gate. The existing pin gate in `src/create-pin-gate.ts`
1238
- governs Review-to-publisher emission separately. An older Review ignores
1236
+ Both act keys require an admitted `previousDraft`. An older Review ignores
1239
1237
  the extra context key and treats the composite `files` rows as ordinary
1240
1238
  seals. On the pre-feature main
1241
1239
  `d82aff4`, the in-process `readPublished` seam is in
@@ -1298,7 +1296,7 @@ A post-interview option set with a `rig` context can also show the accepted rig
1298
1296
 
1299
1297
  <a id="ask-batch"></a>
1300
1298
 
1301
- `ask-batch` asks several subjects of the head record publication in one request ([Review #963](https://github.com/rig-c/review/issues/963)). Each subject is parsed exactly like the single `ask` subject, and a repeated subject refuses the batch. A package head refuses `JOB_REQUEST_INVALID`, a non-head publication refuses `JOB_ACT_SOURCE_STALE`, and zero or more than 64 subjects refuse `JOB_REQUEST_INVALID`. The existing 256 KiB body limit still applies. Review binds every subject, runs `verifyJobRecordSourceFresh` once for the batch (one `inventory` and one `retained` reader call) and validates each subject against that one fresh source. One immediate transaction then re-checks the head, the work root and the retained snapshot once and creates every ask. Each ask writes its own `pending` event and moves the generation by 1, so a batch of N moves it by N. The batch is all or none: any refusal creates no ask, no event and no generation change. A subject's refusal keeps its existing code and prefixes the message with `subjects[<i>]: `. A freshness refusal carries no index. One idempotency key replays the whole batch without reading the publisher again. Single `ask` and finalize are unchanged. A Create detects support through `capabilities.askBatch` in `next`, never by sending `ask-batch` and reading the refusal: an older Review answers the unknown verb with `JOB_REQUEST_INVALID`.
1299
+ `ask-batch` asks several subjects of the head record publication in one request ([Review #963](https://github.com/rig-c/review/issues/963)). Each subject is parsed exactly like the single `ask` subject, and a repeated subject refuses the batch. A package head refuses `JOB_REQUEST_INVALID`, a non-head publication refuses `JOB_ACT_SOURCE_STALE`, and zero or more than 64 subjects refuse `JOB_REQUEST_INVALID`. The existing 256 KiB body limit still applies. Review binds every subject, runs `verifyJobRecordSourceFresh` once for the batch (one `inventory` and one `retained` reader call) and validates each subject against that one fresh source. One immediate transaction then re-checks the head, the work root and the retained snapshot once and creates every ask. Each ask writes its own `pending` event and moves the generation by 1, so a batch of N moves it by N. The batch is all or none: any refusal creates no ask, no event and no generation change. A subject's refusal keeps its existing code and prefixes the message with `subjects[<i>]: `. A freshness refusal carries no index. One idempotency key replays the whole batch without reading the publisher again. Single `ask` and finalize are unchanged. A Create detects support through `capabilities.askBatch` in `next`, never by sending `ask-batch` and reading the refusal: an older Review answers the unknown verb with `JOB_REQUEST_INVALID`. In `JobCapabilitiesV3`, `recordPublication`, `recordActSchema` and `askBatch` describe the host rather than the current head: `ask-batch` applies only to a record-retained head publication and a package head refuses `JOB_REQUEST_INVALID`, so a consumer checks the publication's mode as well as the flag.
1302
1300
 
1303
1301
  The read-only official reader returns the six-key `RecordPublishedContext` with producer-sealed `parts`. `prepareJobRecordSource` runs `phase: 'inventory'` on the immutable source root (re-verifying `project.json` identity before and after each reader phase and before mapping generic reader failures so mid-read record movement reports `JOB_RECORD_MOVED` / `JOB_SOURCE_MISMATCH` rather than `JOB_RECORD_INCOMPLETE`) 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; synchronous `store.update` commit re-verifies source and retained snapshot integrity before persisting. 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.
1304
1302
 
@@ -1506,9 +1504,10 @@ strings and readers. There is no interview-picks arm or question/ask anchor in
1506
1504
  this extension. Technical configuration and search controls are outside it.
1507
1505
 
1508
1506
  The decoders and consumer projections are read-only. Since [Review #713](https://github.com/rig-c/review/issues/713)
1509
- (HQ contract ruling), the UI finalizers write fresh checkpoint, parts-verdict,
1510
- rig and direction review-verdict and signoff acts as act@6. The UI submission
1511
- keeps its existing `words` and `issues` fields. [Review #746](https://github.com/rig-c/review/issues/746)
1507
+ (HQ contract ruling), the UI finalizers use act@6 as the base format for
1508
+ fresh checkpoint, parts-verdict, rig and direction review-verdict and signoff
1509
+ acts. The UI submission keeps its existing `words` and `issues` fields.
1510
+ [Review #746](https://github.com/rig-c/review/issues/746)
1512
1511
  adds optional `feedback: Feedback[]` beside required `words` only for the
1513
1512
  `rig-review` verdict submission. When present, including an empty list,
1514
1513
  `feedback` supplies the pinned comments and suppresses the `words` fallback.
@@ -1518,8 +1517,7 @@ malformed or blank rows. The act bar sends a detached feedback list when there
1518
1517
  are pinned comments and keeps `words` as their projection. It omits `feedback`
1519
1518
  when there are no pinned comments. With `feedback` absent, nonblank `words`
1520
1519
  still supplies one general comment. Direction and image verdict submissions
1521
- keep their existing closed shapes. The comments mapping by itself keeps the
1522
- act@6 format.
1520
+ keep their existing closed shapes.
1523
1521
 
1524
1522
  Only the `rig-review` verdict and `parts-verdict` accept optional
1525
1523
  `general: readonly string[]` in their UI submission values. Each string becomes
@@ -1528,12 +1526,13 @@ produced by the existing fields. For parts verdicts, nonblank `words` still
1528
1526
  produces a comment after the pinned `issues` and before `general`. Parts Request
1529
1527
  changes still requires a pinned issue, and approval still requires zero issues. The existing decoder
1530
1528
  validates the combined comment count, text, evidence and signed projection.
1531
- Omitting `general` preserves the existing written bytes. By itself, `general`
1532
- keeps the writer at act@6, and historical words-only acts retain their readers. [Review #831](https://github.com/rig-c/review/issues/831).
1529
+ Omitting `general` preserves the existing written bytes. Adding `general` by
1530
+ itself keeps the existing schema selection. Historical words-only acts retain
1531
+ their readers. [Review #831](https://github.com/rig-c/review/issues/831).
1533
1532
 
1534
1533
  Pointed marks, inline crops, bookmarks and valid time-only null frames remain
1535
- inside the existing `anchor.context`. This is distinct from act@7's top-level
1536
- `comment.context`, which remains disabled by `EMIT_UNPINNED_CREATE_FIELDS`.
1534
+ inside the existing `anchor.context`. [Comment context (act@7)](#comment-context-act7)
1535
+ defines the separate top-level `comment.context` field.
1537
1536
 
1538
1537
  For the words-only mapping, the daemon maps a nonblank note
1539
1538
  to one comment: anchored to the checkpoint for a checkpoint, general otherwise.
@@ -1609,9 +1608,8 @@ Anchors use existing source-bound fields without a new kind discriminator:
1609
1608
  `view.visibleLayers: {name, imageHash}[]` retains the complete visible set in
1610
1609
  source item order, bound to `sourceHash` and each loaded source image. Entries
1611
1610
  must be unique and source-bound before restoration replaces the hidden set.
1612
- Absent fields retain the historical restore branch and recorded bytes. Readers
1613
- accept both forms; fresh capture writes this field only when the shared
1614
- `EMIT_UNPINNED_CREATE_FIELDS` gate is enabled after Create confirms its parser pin.
1611
+ Starting in 4.8.0, fresh assembled capture writes this field. Readers accept
1612
+ both forms. Absence retains the historical restore branch and recorded bytes.
1615
1613
  - Named image: `name`, optionally the complete existing-field composition
1616
1614
  `imageRegion, crop, nativeCrop`. Names resolve in the sealed image set. Regions
1617
1615
  use nonnegative native-pixel integer origins, positive extents and at most
@@ -1690,10 +1688,11 @@ existing pin or restore path already carries:
1690
1688
  Each key reuses the decoder of the shape it copies. A `reopen` act has no ask
1691
1689
  subject, so its comments cannot carry `context.subject`.
1692
1690
 
1693
- Create refuses unknown fields, so Review emits @7 only when
1694
- `EMIT_UNPINNED_CREATE_FIELDS` (`src/create-pin-gate.ts`) is true. It is false
1695
- until the create tower confirms Create has pinned the Review version that reads
1696
- @7. While it is false, writers drop every `context` and emit @6.
1691
+ Starting in 4.8.0, the rig verdict writer takes top-level `context` from pinned
1692
+ stage-comment evidence and the bound ask and source. It uses @7 when at least
1693
+ one comment carries that context and @6 when none does. A rig verdict carrying
1694
+ mesh edits uses @8 as described below.
1695
+ See [Create compatibility](STABILITY.md#mesh-edit-act-compatibility).
1697
1696
 
1698
1697
  ### Mesh edits on Request changes (act@8)
1699
1698
 
@@ -1765,18 +1764,15 @@ escaping and serialize numbers as ECMAScript `Number.prototype.toString`
1765
1764
  shortest round-trip text. The value contains no integer-like keys, negative
1766
1765
  zero or non-finite numbers. For this value domain the rule is RFC 8785 (JCS).
1767
1766
 
1768
- **Review refusals and rollout.** Before writing the act, Review refuses with
1767
+ **Review refusals.** Before writing the act, Review refuses with
1769
1768
  `JOB_ACT_INVALID` for invalid shape, digest mismatch, invalid ordering or
1770
1769
  duplicate identity, ineligible kind, stage or verdict, counts that differ from
1771
1770
  the stored entry, or an op that cannot replay over the stored topology. An
1772
1771
  attachment hash that differs from the retained displayed model refuses
1773
1772
  `JOB_ACT_SOURCE_STALE`. Existing browser `MESH_EDIT_*` refusals still apply.
1774
- Review ships the decoder with act@8 emission off behind
1775
- `EMIT_UNPINNED_CREATE_FIELDS` in `src/create-pin-gate.ts`.
1776
- An edited submission while emission is off refuses `JOB_ACT_KIND_DISABLED`.
1777
- Create must pin a Review release that reads @8 and build its relay before
1778
- emission opens. The release that opens the gate will be recorded here when it
1779
- is known. Older decoders refuse act@8 with `JOB_ACT_INVALID`.
1773
+ Starting in 4.8.0, eligible submissions carrying edits emit act@8. Review
1774
+ decoders older than 4.7.0 refuse act@8 with `JOB_ACT_INVALID`. See
1775
+ [Create compatibility](STABILITY.md#mesh-edit-act-compatibility).
1780
1776
  Review refuses `JOB_BODY_LIMIT` if the canonical UTF-8 JSON of
1781
1777
  `value.meshEdits` exceeds 256 KiB. Rig stills and inline comment images
1782
1778
  retain their existing request allowances. Finalized-act delivery retains its
package/docs/STABILITY.md CHANGED
@@ -420,18 +420,18 @@ preserve capability, origin, size, cancellation and replay checks.
420
420
  narrow on `schema`. @8 uses the @7 envelope and comment rules, with optional
421
421
  `value.meshEdits` restricted to a `review-verdict` at `stage: "rig-review"` with
422
422
  `verdict: "changes-requested"`. An edited request may carry an empty comments
423
- array. Acts without edits keep their existing emission and validation rules.
423
+ array. Rig verdicts without edits use @7 when a comment carries top-level
424
+ `context` and @6 otherwise.
424
425
  Existing @2–@7 decoder entry points, accepted shapes and historical bytes
425
426
  retain their contracts. The API version, reviewer and consumer grant, and
426
427
  reserved standalone `mesh-edit` kind keep their current contracts. The legacy
427
428
  `rig-review-mesh-edit/1` export and `--delta` input keep their existing formats.
428
429
 
429
- Review ships the @8 decoder with emission disabled. Create pins a Review
430
- release that can decode @8 and builds its relay before Review opens the
431
- emission gate. A live submission carrying edits while the gate is closed
432
- refuses `JOB_ACT_KIND_DISABLED`. Older decoders refuse the new schema with
433
- `JOB_ACT_INVALID`. The rollout and the consumer's required hash, frame and
434
- position checks are part of the [act@8 wire contract](REVIEW_PACKAGE.md#mesh-edits-on-request-changes-act8).
430
+ Starting in 4.8.0, Review emits @8 for eligible submissions carrying edits.
431
+ Create versions below 1.13.0 must not run with Review 4.8.0. Create's exact Review
432
+ dependency pin normally prevents this pairing. Review decoders older than 4.7.0
433
+ refuse @8 with `JOB_ACT_INVALID`. The consumer's required hash, frame and position
434
+ checks are part of the [act@8 wire contract](REVIEW_PACKAGE.md#mesh-edits-on-request-changes-act8).
435
435
  The host facade adds `parseMeshEditsAct`, `JOB_MESH_EDITS_ACT_SCHEMA` and
436
436
  the three mesh edit types listed below.
437
437
 
@@ -448,14 +448,14 @@ See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
448
448
  (`rig-review/act@7`), for thirty runtime exports total, plus the type-only
449
449
  `JobCommentContext`, `JobContextComment` and `JobContextCommentsAct`. The change
450
450
  is additive: `parseCommentsAct`, `JobComment` and `JobCommentsAct` keep their @6
451
- shapes, and @2–@6 decode unchanged. Review does not emit @7 until Create pins a
452
- Review version that reads it. See [Comment context (act@7)](REVIEW_PACKAGE.md#comment-context-act7).
451
+ shapes, and @2–@6 decode unchanged. Starting in 4.8.0, the comments writer
452
+ uses @7 when a comment carries top-level `context`. See [Comment context (act@7)](REVIEW_PACKAGE.md#comment-context-act7).
453
453
 
454
454
  [Review #713](https://github.com/rig-c/review/issues/713) turns on the act@6
455
455
  writers. `JobAct` widens to `JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct |
456
456
  JobCommentsAct`, so `JobActV3`, `JobEvent`, `JobEventV3`, `JobNextValue`,
457
457
  `JobNextValueV3` and `JobHostPorts.commitUIAct` admit fresh act@6 values. No
458
- export is added or removed, and `JobComment` is unchanged. Fresh UI checkpoint,
458
+ export is added or removed, and `JobComment` is unchanged. With that change, fresh UI checkpoint,
459
459
  parts-verdict, rig and direction review-verdict and signoff acts are
460
460
  `rig-review/act@6`. Image-review verdicts and interview picks stay at act@2, and
461
461
  record acts stay at act@4. Consumers narrow on `schema`. A consumer's
@@ -471,10 +471,11 @@ existing `feedbackItemComments` mapper and act@6 decoder. It preserves entry
471
471
  order, text, IDs, frames, target, category and `anchor.context` (including point,
472
472
  crop, bookmark and valid time-only null-frame evidence). `words` supplies the
473
473
  legacy general comment only when `feedback` is absent.
474
- Direction and image submissions retain their previous closed shapes. The
475
- written act stays act@6, historical words-only acts still parse, and the
476
- act@7 top-level `comment.context` emission gate remains off. There are no new
477
- exports or schemas. See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
474
+ Direction and image submissions retain their previous closed shapes. Review
475
+ originally wrote this mapping as act@6. Starting in 4.8.0, pinned rig stage
476
+ comments can also carry the top-level context described above. Historical
477
+ words-only acts still parse.
478
+ See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
478
479
 
479
480
  The `rig-review` verdict and `parts-verdict` accept optional
480
481
  `general: readonly string[]` on their UI submission values. The writer appends
@@ -486,7 +487,12 @@ Request changes verdict still requires a pinned issue, and approval still
486
487
  requires zero issues.
487
488
  The existing act@6 decoder checks the combined comment count, text and signed
488
489
  projection. Omitting `general` preserves the existing mapping and serialized
489
- act bytes. The finalized act schema and exports are unchanged. [Review #831](https://github.com/rig-c/review/issues/831).
490
+ act bytes. Adding `general` by itself keeps the existing schema selection.
491
+ [Review #831](https://github.com/rig-c/review/issues/831).
492
+
493
+ Starting in 4.8.0, fresh assembled Parts issues carry `view.visibleLayers`
494
+ with the complete source-bound visible set. Readers still accept historical
495
+ anchors without that field. See [Comments decoder contract](REVIEW_PACKAGE.md#comments-decoder-contract).
490
496
 
491
497
  [Review #914](https://github.com/rig-c/review/issues/914) adds
492
498
  `JOB_PREVIOUS_DRAFT_SCHEMA` (`rig-review-previous-draft/1`) and the
@@ -502,6 +508,54 @@ with the keys absent keep their existing contract. The Review-to-publisher
502
508
  pin gate applies in its existing direction. See
503
509
  [Previous accepted draft Difference](REVIEW_PACKAGE.md#previous-accepted-draft-difference).
504
510
 
511
+ [Review #914](https://github.com/rig-c/review/issues/914) adds the previous-draft
512
+ constant `JOB_PREVIOUS_DRAFT_SCHEMA` (`rig-review-previous-draft/1`), for twenty-nine runtime exports total after the 4.0.0 removal of `startJobHub` and `assertJobImageSetCapability`, plus the type-only `JobPreviousDraft`.
513
+
514
+ [Review #952](https://github.com/rig-c/review/issues/952) adds the act@8 decoder
515
+ `parseMeshEditsAct` and its constant `JOB_MESH_EDITS_ACT_SCHEMA`
516
+ (`rig-review/act@8`), for thirty-one runtime exports total, plus the type-only
517
+ `JobMeshEditValue`, `JobMeshEdit` and `JobMeshEditsAct`.
518
+
519
+ ### Host-bound act wait
520
+
521
+ [Review #1005](https://github.com/rig-c/review/issues/1005) adds the host-bound
522
+ finalized-act waiter `waitForJobAct`, for thirty-two runtime exports total, plus
523
+ the type-only `JobActWaitOptions` and `JobActWaitOutcome`.
524
+
525
+ ```ts
526
+ function waitForJobAct(host: JobOwnerHost, options: JobActWaitOptions): Promise<JobActWaitOutcome>;
527
+ // options: {after: JobCursor | null; deadlineMs: number; signal?: AbortSignal}
528
+ // outcome: {kind: 'act' | 'closed'; next: JobNextValue | JobNextValueV3; cursor}
529
+ // | {kind: 'timeout'; code: 'JOB_NEXT_TIMEOUT'; next: JobNextValue | JobNextValueV3 | null; cursor}
530
+ ```
531
+
532
+ The wait sends the host's own API schema. A package-only host gets
533
+ `rig-review/job-api@2` and answers `JobNextValue` batches. A
534
+ record-and-package host gets `rig-review/job-api@3`, as Create's agents send,
535
+ and answers `JobNextValueV3` batches. An act row there may be a
536
+ `rig-review/act@4` record act (`JobRecordAct`, checked with `parseRecordAct`)
537
+ as well as a package act. The act's own `schema` picks the decoder, so
538
+ `rig-review session next --until act` also accepts record acts from a record
539
+ host. Its output and exit codes are unchanged.
540
+
541
+ It is the `rig-review session next --until act` loop, shared code rather than a
542
+ copy, sent through `host.ports.handleJobApi` with the host's existing agent
543
+ capability. `deadlineMs` is an integer from 1 to 600000. Each server `next`
544
+ stays bounded to 30000 ms, and the wait advances the cursor through unrelated
545
+ publication and ask events. `cursor` is the cursor to resume from. An invalid
546
+ deadline refuses `JOB_REQUEST_INVALID` before any request. A refused `next`
547
+ throws its `JobError` code. Abort rejects with the signal's reason and clears
548
+ the wait's timers. When an empty server window ends less than a millisecond
549
+ before the deadline, the wait sends no zero-wait repeat and sits out the
550
+ remainder. The CLI shares this.
551
+
552
+ A strict `reuseOnly` attachment opens its own read-only session, which the
553
+ live host's in-process notifications never reach. Its `next` therefore watches
554
+ the shared store's revision with the existing 250 ms subscribe watcher, so a
555
+ finalized act the live host commits wakes it. A write that adds no deliverable
556
+ event, such as a display receipt, keeps the wait open, and a refused save
557
+ commits nothing. No API verb, act field or capability changes.
558
+
505
559
  The exact runtime exports are listed below. Constants preserve their literal
506
560
  values from the frozen semantic contract.
507
561
 
@@ -536,6 +590,7 @@ values from the frozen semantic contract.
536
590
  - `JOB_PLAN_BOUND_SIGNOFF_STAGES`
537
591
  - `JOB_CONSUMER_AUTH_MODE`
538
592
  - `JOB_ERROR_CODES`
593
+ - `waitForJobAct`
539
594
 
540
595
  The exact type-only exports follow. Their existing definitions in
541
596
  `src/job-contract.ts`, `src/job-source.ts`, `src/job-act.ts`, `src/job-session.ts`,
@@ -552,6 +607,8 @@ without aliases or copied wire shapes.
552
607
  - `JobSessionOptions`
553
608
  - `JobSession`
554
609
  - `JobWorkerOptions`
610
+ - `JobActWaitOptions`
611
+ - `JobActWaitOutcome`
555
612
  - `JobPublicationReader`
556
613
  - `JobPublishedContext`
557
614
  - `JobEnabledActKind`
@@ -709,14 +766,18 @@ Rows are capped at 4096, roles at 128 UTF-16 code units and literal paths at 409
709
766
  ## Installed acceptance
710
767
 
711
768
  `bun run smoke` packs the package and installs that tarball into an empty project.
712
- A consumer checks the thirty runtime exports and every listed type, including
769
+ A consumer checks the thirty-two runtime exports and every listed type, including
713
770
  `JobHostListenerIncarnation`, `JobHostReuseBinding`, `JobHostReuseExpectation`,
714
771
  `JobHostAttachField`, `JobHostAttachFailure`, `JobInterviewJson`,
715
772
  `JobInterviewRecord`, `JobInterviewDiagnostic`, `JobInterviewDiagnostics` and
716
773
  the comments decoder types and the record-mode `JobRecordAct` / `JobActV3` / `JobPlanSource` /
717
774
  `JobFetchActRequestV3` / `JobRecordHostHooks` / `JobCapabilitiesV3` / `JobAskBatchRequestV3` /
718
775
  `JobAskBatchValueV3` surface, through `@rig-c/review/job-host`. The consumer also
719
- proves that `JobCapabilitiesV3` carries `askBatch: true`.
776
+ proves that `JobCapabilitiesV3` carries `askBatch: true`. In `JobCapabilitiesV3`,
777
+ `recordPublication`, `recordActSchema` and `askBatch` describe the host rather
778
+ than the current head: `ask-batch` applies only to a record-retained head
779
+ publication and a package head refuses `JOB_REQUEST_INVALID`, so a consumer
780
+ checks the publication's mode as well as the flag.
720
781
  TypeScript checks the installed consumer and the runtime checks the full owner
721
782
  resources, retained publication, semantic ports, declared hooks, enumerator
722
783
  version/row carriage, ordinary reuse, strict `reuseOnly: {expected}` attachment
package/docs/WORKFLOWS.md CHANGED
@@ -571,6 +571,16 @@ file-only Save has the separate [save-notification contract](PARTS_VIEW.md#durab
571
571
  Waking this act wait requires a real finalized job act. Consumers use writer-owned `fetch-act` for
572
572
  the source-bound result and deduplicate by `actId`.
573
573
 
574
+ An in-process agent holding a started or strict `reuseOnly` host runs the same wait with
575
+ `waitForJobAct(host, {after, deadlineMs, signal})` from `@rig-c/review/job-host`. It resolves
576
+ `{kind: 'act' | 'closed', next, cursor}` or `{kind: 'timeout', code: 'JOB_NEXT_TIMEOUT', next, cursor}`,
577
+ where `next` is the last accepted batch or `null`, and throws a refused `next` by its `JobError` code.
578
+ On a record-and-package host it speaks `rig-review/job-api@3`, and act rows may be `rig-review/act@4`
579
+ record acts, which this CLI wait also accepts.
580
+ A strict attachment's `next` watches the shared job store, so a finalized act committed by the live
581
+ owner host wakes it within about 250 ms. A write that adds no event, such as a display receipt,
582
+ keeps the wait open. See [Public API stability](STABILITY.md#host-bound-act-wait).
583
+
574
584
  - **One standing window and visual gate.** Every owner visual, question, choice, correction and verdict goes through one standing Review window/link plus one what-to-look-at line. Internal agent and HQ media stay internal and are never substituted for the owner handoff. When a required visual is missing (`visual.status` set to `'unavailable'` with a named `code`), the agent stops immediately and files a Create on-path Review card rather than falling back to chat text or images.
575
585
  - **Human UI vs agent verbs.** People submit through the Review browser UI (`actor` set to `'human'`, `channel` set to `'review-ui'`). Trusted host bootstrap declares `reviewer` (`id` and `role` as `'owner'` or `'delegate'`), which the browser UI cannot type or override. This binding records bootstrap-declared provenance rather than keyboard-user authentication, and Create maps `role` to its existing `by` authority. Agents use only `publish`, `ask`, `next` and `close` (`JobAgentRequest`), with `expectedGeneration` compare-and-swap (CAS) and `idempotencyKey` on mutations.
576
586
  - **Explicit producer-held freeze and explicit close.** Every `publish` request designates a root-relative `result` (`path` and `selector`, never a command) and carries an explicit producer-held freeze (`freeze.kind` set to `'producer-held'`, `holdId`, `record` as `JobFileIdentity` or `null` for a declared non-Create root) held until acknowledgment. Review validates retained bytes, detects a moved record (`JOB_RECORD_MOVED`, `JOB_RECORD_INCOMPLETE`, `JOB_FREEZE_REQUIRED`, `JOB_SOURCE_MISMATCH`, `JOB_SOURCE_UNRETAINABLE`, `JOB_ROOT_REPLACED`) and commits local generation CAS (`JOB_GENERATION_STALE`, `JOB_IDEMPOTENCY_CONFLICT`). The freeze assertion is a caller obligation rather than a lock Review can impose on independent writers. Review offers no watched-root or automatic-close guarantee, and only explicit `close` ends an active job.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "4.7.0",
3
+ "version": "4.9.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -26,7 +26,7 @@
26
26
  "pngjs": "7.0.0"
27
27
  },
28
28
  "devDependencies": {
29
- "@rig-c/parts": "2.38.1",
29
+ "@rig-c/parts": "2.46.0",
30
30
  "@types/bun": "^1.3.0",
31
31
  "typescript": "^5.9.3"
32
32
  },
package/src/baseline.ts CHANGED
@@ -6,8 +6,10 @@
6
6
  * rebuilds the whole rig may run; otherwise the first differing path is named. Nothing is written into the package.
7
7
  */
8
8
  import { createHash } from 'node:crypto';
9
- import { lstat, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
10
- import { join } from 'node:path';
9
+ import { lstat, mkdir, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
10
+ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
11
+ import { isDeepStrictEqual } from 'node:util';
12
+ import { object } from './manifest.ts';
11
13
  import type { Handoff } from './handoff.ts';
12
14
  import { isProducerFile, PRODUCER_DOCUMENTS, PRODUCER_IMAGES_DIR } from './producer-files.ts';
13
15
  import { firstRefusal, runTool, type InstalledTool } from './producer.ts';
@@ -29,6 +31,8 @@ export interface BaselineResult {
29
31
  line: string; exitCode: number | null; wallMs: number | null;
30
32
  }
31
33
  const sha256 = (bytes: Uint8Array | string) => createHash('sha256').update(bytes).digest('hex');
34
+ const RIG_RUN_RECEIPT = 'run.json';
35
+ const RUN_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
32
36
  async function present(path: string): Promise<boolean> { try { await lstat(path); return true; } catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return false; throw e; } }
33
37
 
34
38
  /** A rig directory as {relative path: sha256}: its regular files and images/* (fixed places, not a search). */
@@ -45,9 +49,12 @@ export const treeHash = (tree: Record<string, string>) => sha256(JSON.stringify(
45
49
  * file the baseline wrote, and on the inspected side the producer's documents and images (`isProducerFile`; a file there
46
50
  * that rig never writes, such as a note, is not the producer's to reproduce).
47
51
  */
48
- export function firstDifference(baseline: Record<string, string>, inspected: Record<string, string>): string | null {
49
- const own = Object.keys(inspected).filter(isProducerFile);
50
- for (const path of [...new Set([...Object.keys(baseline), ...own])].sort()) if (baseline[path] !== inspected[path]) return path;
52
+ export function firstDifference(baseline: Record<string, string>, inspected: Record<string, string>, runReceiptMatches?: boolean): string | null {
53
+ const own = Object.keys(inspected).filter(path => isProducerFile(path) || path === RIG_RUN_RECEIPT);
54
+ for (const path of [...new Set([...Object.keys(baseline), ...own])].sort()) {
55
+ const matches = path === RIG_RUN_RECEIPT && runReceiptMatches !== undefined ? runReceiptMatches : baseline[path] === inspected[path];
56
+ if (!matches) return path;
57
+ }
51
58
  if (!Object.keys(baseline).length) return 'rig.json';
52
59
  return null;
53
60
  }
@@ -96,9 +103,31 @@ export function assertWholeRigBaseline(result: BaselineResult | null): void {
96
103
  export const baselineKey = (sourceHash: string, handoff: Handoff, producer: InstalledTool, compiler: InstalledTool) =>
97
104
  sha256(JSON.stringify([BASELINE_SCHEMA, sourceHash, handoff.record, `${producer.package}@${producer.version}`, `${compiler.package}@${compiler.version}`]));
98
105
 
106
+ /** A rig stamp's clock varies per run. Its config path is relative to the output directory. */
107
+ async function runReceiptIdentity(dir: string, rawHash: string): Promise<unknown> {
108
+ try {
109
+ const bytes = await readFile(join(dir, RIG_RUN_RECEIPT));
110
+ if (sha256(bytes) !== rawHash) return null;
111
+ const { started_at, finished_at, ...receipt } = object(JSON.parse(bytes.toString('utf8')), RIG_RUN_RECEIPT);
112
+ if (receipt.spec !== 'rig-run/1' || receipt.command !== 'rig') return null;
113
+ if (![started_at, finished_at].every(time => typeof time === 'string' && RUN_TIMESTAMP.test(time))) return null;
114
+ const { path, ...config } = object(receipt.config, `${RIG_RUN_RECEIPT}.config`);
115
+ if (typeof path !== 'string' || !path || isAbsolute(path)) return null;
116
+ const outputDir = await realpath(dir), configPath = resolve(outputDir, path);
117
+ if (relative(outputDir, configPath).split(sep).join('/') !== path) return null;
118
+ return { ...receipt, config: { ...config, path: configPath } };
119
+ } catch { return null; }
120
+ }
121
+
99
122
  /** Compare a finished `<dir>/baseline` with the inspected rig; `show` turns a rig-relative path into the package-relative one. */
100
123
  export async function compareBaseline(out: string, inspectedRig: string, show: (rel: string) => string, producerVersion: string | null = null): Promise<Pick<BaselineResult, 'status' | 'firstDifference' | 'hashes' | 'reach'>> {
101
- const baseline = await rigTree(out), inspected = await rigTree(inspectedRig), first = firstDifference(baseline, inspected);
124
+ const [baseline, inspected] = await Promise.all([rigTree(out), rigTree(inspectedRig)]);
125
+ let runReceiptMatches: boolean | undefined;
126
+ if (baseline[RIG_RUN_RECEIPT] && inspected[RIG_RUN_RECEIPT]) {
127
+ const [a, b] = await Promise.all([runReceiptIdentity(out, baseline[RIG_RUN_RECEIPT]), runReceiptIdentity(inspectedRig, inspected[RIG_RUN_RECEIPT])]);
128
+ runReceiptMatches = a !== null && b !== null && isDeepStrictEqual(a, b);
129
+ }
130
+ const first = firstDifference(baseline, inspected, runReceiptMatches);
102
131
  // #148: a build the config does not reproduce says, per op, what the producer will still take.
103
132
  const reach = first === null ? null : await baselineReach(out, inspectedRig, baseline, inspected, show, reachOps(producerVersion));
104
133
  return { status: first === null ? 'reproduced' : 'not-reproduced', firstDifference: first === null ? null : show(first), hashes: { baseline: { rigJson: baseline['rig.json'] ?? null, tree: treeHash(baseline) }, inspected: { rigJson: inspected['rig.json'] ?? null, tree: treeHash(inspected) } }, reach };
@@ -135,8 +164,8 @@ export async function runBaseline(dir: string, key: string, handoff: Handoff, pr
135
164
 
136
165
  /**
137
166
  * The inspected build's own check (#108, HQ ruling): once the baseline reproduces the inspected rig, `rig-parts check`
138
- * runs on that baseline output — byte-identical to the inspected rig, so nothing reads or writes the package — into
139
- * `<baseline dir>/inspected-check/`, with Apply's default pack flags (`--page-edges free --pack-shape polygon`). The
167
+ * reads the baseline in scratch and writes to `<baseline dir>/inspected-check/` with Apply's default pack flags
168
+ * (`--page-edges free --pack-shape polygon`). The
140
169
  * summary is stored beside the baseline record (`inspected-check.json`) so a reload reads it instead of re-running.
141
170
  * It is what the physics readout's BEFORE line quotes while the inspected build is on the stage.
142
171
  */
@@ -13,7 +13,7 @@ import {parseCommentsSession} from './session.ts';
13
13
  import {projectComments} from './stage-comment.ts';
14
14
  import type {ReviewCommentsSession, JobCommentFeedbackAnchor, JobCommentPartsAnchor} from './job-contract.ts';
15
15
  import type {PartsIssue} from './parts-comment.ts';
16
- import type {JobComment, JobActValues, ActV3, JobCommentsAct, JobMeshEditsAct} from './job-contract.ts';
16
+ import type {JobComment, JobActValues, ActV3, JobCommentsAct, JobContextCommentsAct, JobMeshEditsAct} from './job-contract.ts';
17
17
  import type {CompareFeedback} from './compare-session.ts';
18
18
  import {parseRecordAct} from './job-api.ts';
19
19
 
@@ -51,7 +51,7 @@ export function legacyRecordActComments(raw: unknown): {text: string}[] {
51
51
  }
52
52
 
53
53
  /** Display projection of already-decoded @2–@5 acts, without upgrading their envelopes. */
54
- export function legacyActComments(act: Exclude<ActV3, JobCommentsAct | JobMeshEditsAct>): {text: string}[] {
54
+ export function legacyActComments(act: Exclude<ActV3, JobCommentsAct | JobContextCommentsAct | JobMeshEditsAct>): {text: string}[] {
55
55
  if (act.kind === 'interview-picks') return [];
56
56
  const value = act.value;
57
57
  const fields = [value.words];
@@ -0,0 +1,54 @@
1
+ import {randomUUID} from 'node:crypto';
2
+ import {type JobCursor, type JobErrorCode, type JobNextValue, type JobNextValueV3} from './job-contract.ts';
3
+ import {jobActWaitLimitMs, waitForActBatch} from './job-cli.ts';
4
+ import type {JobOwnerHost} from './job-front.ts';
5
+ import {JobError} from './job-store.ts';
6
+
7
+ export interface JobActWaitOptions {
8
+ /** Start after this accepted cursor; `null` reads from the first retained event. */
9
+ readonly after: JobCursor | null;
10
+ /** Whole-wait bound in milliseconds, an integer from 1 to 600000 like `job next --until act --wait-ms`. */
11
+ readonly deadlineMs: number;
12
+ /** Caller cancellation. An abort rejects with the signal's reason and clears every timer. */
13
+ readonly signal?: AbortSignal;
14
+ }
15
+
16
+ /**
17
+ * The batch carrying the finalized act or the closure, and its cursor to resume from. A
18
+ * package-only host answers `rig-review/job-api@2` batches (`JobNextValue`, package acts);
19
+ * a record-and-package host answers `@3` batches (`JobNextValueV3`), whose act rows may be
20
+ * `rig-review/act@4` record acts (`JobRecordAct`) as well as package acts.
21
+ */
22
+ type JobActWaitBatch = JobNextValue | JobNextValueV3;
23
+ export type JobActWaitOutcome =
24
+ | {readonly kind: 'act'; readonly next: JobActWaitBatch; readonly cursor: JobCursor | null}
25
+ | {readonly kind: 'closed'; readonly next: JobActWaitBatch; readonly cursor: JobCursor | null}
26
+ | {readonly kind: 'timeout'; readonly code: 'JOB_NEXT_TIMEOUT'; readonly next: JobActWaitBatch | null; readonly cursor: JobCursor | null};
27
+
28
+ /**
29
+ * Wait on a started or strictly attached owner host until a finalized act, a closure or the
30
+ * deadline. It is the `job next --until act` loop over the host's own ports with the host's
31
+ * agent capability; a refused `next` throws its `JobError` code.
32
+ */
33
+ export async function waitForJobAct(host: JobOwnerHost, options: JobActWaitOptions): Promise<JobActWaitOutcome> {
34
+ const {after, deadlineMs, signal} = options;
35
+ if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 1 || deadlineMs > jobActWaitLimitMs ||
36
+ (after !== null && typeof after !== 'string')) throw new JobError('JOB_REQUEST_INVALID');
37
+ const jobId = host.session.jobId, endpoint = `${host.origin}/jobs/${jobId}/api`;
38
+ const capability = host.session.hostCredentials().agent;
39
+ // The host's own API schema: job-api@3 on a record-and-package host, as Create's agents send.
40
+ const result = await waitForActBatch((request, requestSignal) => host.ports.handleJobApi(new Request(endpoint, {
41
+ method: 'POST', signal: requestSignal,
42
+ headers: {'Content-Type': 'application/json', Authorization: 'Bearer ' + capability},
43
+ body: JSON.stringify(request),
44
+ })), {schema: host.session.apiSchema, verb: 'next', jobId, requestId: randomUUID(), after, waitMs: 0}, deadlineMs, signal);
45
+ switch (result.kind) {
46
+ case 'act': case 'closed': return {kind: result.kind, next: result.batch, cursor: result.batch.cursor};
47
+ case 'timeout': return {kind: 'timeout', code: 'JOB_NEXT_TIMEOUT', next: result.batch, cursor: result.cursor};
48
+ case 'refused': {
49
+ const error = (result.value as {error?: {code?: unknown; message?: unknown}}).error;
50
+ throw new JobError((typeof error?.code === 'string' ? error.code : 'JOB_REQUEST_INVALID') as JobErrorCode,
51
+ typeof error?.message === 'string' ? error.message : undefined);
52
+ }
53
+ }
54
+ }
package/src/job-act.ts CHANGED
@@ -4,13 +4,15 @@ import {
4
4
  type ActV3, type JobAct, type JobComment, type JobCommentsAct, type JobApiSchema, type JobPendingAsk, type JobPublicationMode, type JobReviewerBinding,
5
5
  type JobSourceBinding, type JobSubject, type JobUISubmission, type JobRigCapture, type JobRigStill,
6
6
  type JobMeshEdit, type PendingAskV3, type RecordAct, type RecordSource, type RecordSubject, type SourceV3, type UISubmissionV3,
7
+ type JobCommentContext, type JobContextComment,
7
8
  } from './job-contract.ts';
8
9
  import { parsePartsIssue, type PartsIssue } from './parts-comment.ts';
9
10
  import {
10
11
  isRecordSource, jobHash, jobId, jobInteger, jobObject,
11
- meshEditsActForEmission, parseCommentsAct, parseMeshEdits, parseRecordAct, parseRecordSource, requestDigest, validateRecordAskSubject,
12
+ commentsActForEmission, meshEditsActForEmission, parseCommentsAct, parseMeshEdits, parseRecordAct, parseRecordSource, requestDigest, validateRecordAskSubject,
12
13
  } from './job-api.ts';
13
14
  import { checkpointNoteComments, feedbackItemComments, noteComments, partsIssueComments } from './feedback-export.ts';
15
+ import { hasStageComment, parseStageComment } from './stage-comment.ts';
14
16
  import type { Feedback } from './session.ts';
15
17
  import { validatePicks } from './interview-picks.ts';
16
18
  import {
@@ -22,7 +24,6 @@ import {
22
24
  import { JobError } from './job-store.ts';
23
25
  import { checkedPath, readRegular } from './interview-project.ts';
24
26
  import {validatePngBytes} from './comment-crops.ts';
25
- import {EMIT_UNPINNED_CREATE_FIELDS} from './create-pin-gate.ts';
26
27
  import {applyMeshOps, attachmentHashText, MESH_EDIT_CODES} from './mesh-edit.ts';
27
28
  import {readStoredSetupMesh} from './setup-mesh.ts';
28
29
 
@@ -37,6 +38,20 @@ function commentsAct(act: JobCommentsAct): JobCommentsAct {
37
38
  return act;
38
39
  }
39
40
 
41
+ function rigVerdictFeedbackComments(feedback: readonly Feedback[], subject: NonNullable<JobCommentContext['subject']>): JobContextComment[] {
42
+ return feedbackItemComments(feedback).map(comment => {
43
+ const rawMark = (comment.anchor.context as {comment?: unknown} | undefined)?.comment;
44
+ if (!hasStageComment(rawMark)) return comment;
45
+ const mark = parseStageComment(rawMark);
46
+ const selection = (mark.bookmark as {
47
+ selection: {inspector: JobCommentContext['tab']; part?: JobCommentContext['part'] | null};
48
+ }).selection;
49
+ return {...comment, context: {subject, mode: mark.mode, tab: selection.inspector,
50
+ ...(selection.part ? {part: selection.part} : {}), region: mark.world, camera: mark.camera,
51
+ ...(mark.frame ? {frame: mark.frame} : {})}};
52
+ });
53
+ }
54
+
40
55
  function hasMeshSubmission(kind: unknown, value: unknown): boolean {
41
56
  if (value === null || typeof value !== 'object' || !Object.hasOwn(value, 'meshEdits')) return false;
42
57
  const {stage, verdict} = value as {stage?: unknown; verdict?: unknown};
@@ -210,9 +225,6 @@ export function parseUISubmission(
210
225
  if (!allowed) {
211
226
  throw new JobError('JOB_ACT_INVALID');
212
227
  }
213
- if (hasMeshSubmission(item.kind, item.value) && !EMIT_UNPINNED_CREATE_FIELDS) {
214
- throw new JobError('JOB_ACT_KIND_DISABLED');
215
- }
216
228
  if (item.capture !== undefined && (item.kind !== 'review-verdict' ||
217
229
  (item.value as {stage?: unknown} | null)?.stage !== 'rig-review')) throw new JobError('JOB_REQUEST_INVALID');
218
230
  return item as unknown as UISubmissionV3;
@@ -513,7 +525,6 @@ export function finalizeJobAct(options: {
513
525
  readonly still?: JobRigStill;
514
526
  readonly actId?: string;
515
527
  readonly at?: string;
516
- readonly emitUnpinned?: boolean;
517
528
  }): ActV3;
518
529
  export function finalizeJobAct(options: {
519
530
  readonly jobId: string;
@@ -524,15 +535,12 @@ export function finalizeJobAct(options: {
524
535
  readonly still?: JobRigStill;
525
536
  readonly actId?: string;
526
537
  readonly at?: string;
527
- readonly emitUnpinned?: boolean;
528
538
  }): ActV3 {
529
539
  const meshSubmission = hasMeshSubmission(options.submission.kind, options.submission.value);
530
540
  if (meshSubmission && (isRetainedRecordSource(options.retained) ||
531
541
  options.ask.subject.kind !== 'review-verdict' || options.ask.subject.stage !== 'rig-review')) {
532
542
  throw new JobError('JOB_ACT_INVALID');
533
543
  }
534
- const emitUnpinned = options.emitUnpinned ?? EMIT_UNPINNED_CREATE_FIELDS;
535
- if (meshSubmission && !emitUnpinned) throw new JobError('JOB_ACT_KIND_DISABLED');
536
544
  if (isRetainedRecordSource(options.retained)) {
537
545
  return prepareJobRecordAct({
538
546
  jobId: options.jobId,
@@ -662,15 +670,18 @@ export function finalizeJobAct(options: {
662
670
  if (!options.still) throw new JobError('JOB_STILL_CAPTURE_FAILED');
663
671
  const note = words(value.words);
664
672
  if (value.feedback !== undefined && !Array.isArray(value.feedback)) throw new JobError('JOB_ACT_INVALID');
665
- let verdictComments: ReturnType<typeof noteComments>;
673
+ const selector = source.selector as Extract<NonNullable<JobSourceBinding['selector']>, {kind: 'rig'}>;
674
+ let verdictComments: readonly JobContextComment[];
666
675
  try {
667
- verdictComments = value.feedback === undefined ? noteComments(note) : feedbackItemComments(value.feedback as Feedback[]);
676
+ verdictComments = value.feedback === undefined ? noteComments(note) : rigVerdictFeedbackComments(value.feedback as Feedback[],
677
+ {ask: ask.subject, sourceHash: source.sourceHash, selector});
668
678
  } catch { throw new JobError('JOB_ACT_INVALID'); }
669
679
  const act = {...comments, kind: 'review-verdict' as const,
670
- source: {...source, model: source.model!, selector: source.selector as Extract<NonNullable<JobSourceBinding['selector']>, {kind: 'rig'}>},
680
+ source: {...source, model: source.model!, selector},
671
681
  value: {stage: 'rig-review' as const, verdict, comments: [...verdictComments, ...generalComments(value.general)]},
672
682
  still: options.still};
673
- if (meshEdits) return meshEditsActForEmission({...act, value: {...act.value, meshEdits}}, emitUnpinned);
683
+ if (meshEdits) return meshEditsActForEmission({...act, value: {...act.value, meshEdits}});
684
+ if (verdictComments.some(comment => Object.hasOwn(comment, 'context'))) return commentsActForEmission(act);
674
685
  return commentsAct(act);
675
686
  }
676
687
  return commentsAct({ ...comments, kind: 'review-verdict', source: { ...source, model: source.model!,