@rig-c/review 3.7.0 → 4.0.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.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/docs/DESIGN.md +145 -74
  3. package/docs/PANELS.md +20 -12
  4. package/docs/PARTS_VIEW.md +133 -76
  5. package/docs/REVIEW_PACKAGE.md +445 -99
  6. package/docs/STABILITY.md +132 -198
  7. package/docs/WORKFLOWS.md +41 -120
  8. package/package.json +4 -3
  9. package/skills/rig-review/SKILL.md +41 -27
  10. package/src/build.ts +10 -2
  11. package/src/cli.ts +17 -16
  12. package/src/comment-crops.ts +6 -1
  13. package/src/compare-html.ts +22 -24
  14. package/src/compare-server.ts +1 -1
  15. package/src/compare-session.ts +41 -3
  16. package/src/correction-handoff.ts +27 -4
  17. package/src/create-pin-gate.ts +3 -0
  18. package/src/direction-inspection.ts +6 -2
  19. package/src/feedback-export.ts +68 -1
  20. package/src/front.ts +5 -200
  21. package/src/handoff.ts +1 -1
  22. package/src/interview-routes.ts +1 -1
  23. package/src/interview-scene.ts +3 -3
  24. package/src/job-act.ts +77 -73
  25. package/src/job-api.ts +326 -13
  26. package/src/job-checkpoint-evidence.ts +113 -0
  27. package/src/job-cli.ts +27 -14
  28. package/src/job-contract.ts +284 -62
  29. package/src/job-front.ts +157 -58
  30. package/src/job-host.ts +23 -4
  31. package/src/job-session.ts +109 -24
  32. package/src/job-source.ts +209 -57
  33. package/src/job-store.ts +80 -6
  34. package/src/job-worker.ts +1 -47
  35. package/src/joined-project.ts +61 -4
  36. package/src/manifest.ts +32 -4
  37. package/src/open-workspace.ts +12 -12
  38. package/src/open.ts +19 -12
  39. package/src/parts-comment-crops.ts +126 -31
  40. package/src/parts-comment.ts +351 -28
  41. package/src/parts-server.ts +19 -7
  42. package/src/parts-view.ts +588 -109
  43. package/src/scene-inspection.ts +50 -0
  44. package/src/server.ts +31 -22
  45. package/src/session.ts +58 -0
  46. package/src/stage-comment.ts +48 -1
  47. package/src/stage-parts.ts +23 -11
  48. package/web/animation-inspection.ts +1 -1
  49. package/web/bones-panel.ts +1 -3
  50. package/web/catalog-en.ts +175 -39
  51. package/web/catalog-ko.ts +175 -39
  52. package/web/cloth-panel.ts +1 -2
  53. package/web/compare.css +3 -13
  54. package/web/compare.html +3 -3
  55. package/web/compare.ts +69 -64
  56. package/web/cuts-panel.ts +1 -3
  57. package/web/density-strip-panel.ts +1 -2
  58. package/web/direction-panel.ts +22 -6
  59. package/web/i18n.ts +13 -1
  60. package/web/idle-panel.ts +1 -2
  61. package/web/index.html +1 -5
  62. package/web/inspection-persistence.ts +2 -1
  63. package/web/inspector-blocks.ts +149 -40
  64. package/web/instance-access.ts +24 -5
  65. package/web/interview-panel.ts +224 -175
  66. package/web/job-rig-capture.ts +164 -21
  67. package/web/job-rig-screen.ts +337 -0
  68. package/web/job-session.ts +611 -1437
  69. package/web/main.ts +614 -151
  70. package/web/mesh-panel.ts +1 -2
  71. package/web/owner-workspace.ts +88 -109
  72. package/web/part-selection.ts +47 -6
  73. package/web/part-thumbnails.ts +20 -6
  74. package/web/parts-render.ts +26 -19
  75. package/web/parts-viewport-provider.ts +181 -7
  76. package/web/physics-panel.ts +1 -2
  77. package/web/readings-panel.ts +1 -2
  78. package/web/requirements-panel.ts +1 -3
  79. package/web/retained-frame-stage.ts +105 -0
  80. package/web/retarget-panel.ts +2 -3
  81. package/web/rig-fields-panel.ts +1 -2
  82. package/web/rig-host.ts +64 -0
  83. package/web/rig-viewport-provider.ts +65 -16
  84. package/web/scene-plates.ts +57 -4
  85. package/web/stage-comments.ts +103 -46
  86. package/web/styles.css +117 -63
  87. package/web/view-controls.ts +201 -12
  88. package/web/viewport-capture.ts +12 -2
  89. package/web/viewport-controller.ts +107 -27
  90. package/web/viewport-pair.ts +2 -1
  91. package/web/workspace-preferences.ts +5 -4
  92. package/web/workspace-ui.ts +151 -19
  93. package/src/front-worker.ts +0 -2
  94. package/src/interview-server.ts +0 -54
  95. package/src/job-hub.ts +0 -304
  96. package/src/job-image-set.ts +0 -50
  97. package/web/interview.css +0 -28
  98. package/web/interview.html +0 -17
  99. package/web/interview.ts +0 -40
  100. package/web/job-hub.css +0 -14
  101. package/web/job-hub.html +0 -5
  102. package/web/job-hub.ts +0 -179
  103. package/web/owner-workspace.css +0 -14
  104. package/web/owner-workspace.html +0 -5
  105. package/web/parts-flags.ts +0 -48
  106. package/web/parts.css +0 -104
  107. package/web/parts.html +0 -49
  108. package/web/parts.ts +0 -604
  109. package/web/stage-nav.ts +0 -136
@@ -1,20 +1,24 @@
1
1
  import { randomBytes, randomUUID } from 'node:crypto';
2
- import { isAbsolute, relative, sep } from 'node:path';
2
+ import { dirname, isAbsolute, join, relative, sep } from 'node:path';
3
3
  import {
4
- JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
4
+ JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, jobActDeliveryLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
5
5
  type ActV3, type AgentRequestV3, type EventV3, type JobPartsEnumerator, type JobAct, type JobAgentRequest, type JobDisplayAcknowledgment,
6
6
  type JobDisplayPublication, type JobDisplayPublicationV3, type JobDisplayReceipt, type JobEvent, type JobFetchActRequest, type JobFetchActRequestV3,
7
7
  type JobNextValue, type JobPendingAsk, type JobPublication, type JobPublicationMode, type JobReviewerBinding,
8
8
  type NextValueV3, type PendingAskV3, type PublicationV3, type RecordPublicationReader, type RecordSubject, type StatusV3,
9
9
  } from './job-contract.ts';
10
10
  import { bindJobAsk, bindJobRecordAsk, finalizeJobAct, parseUISubmission, prepareJobRecordAct, prepareJobStill } from './job-act.ts';
11
- import { jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
11
+ import { isRecordSource, parseRecordSource, parseCommentsAct, jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
12
12
  import {
13
- assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, prepareJobSource, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
13
+ assertStoredCheckpointEvidence, assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, prepareJobSource, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
14
14
  type JobPublicationReader, type JobRetainedSource, type JobRetainedSourceV3, type JobRootIdentity,
15
15
  } from './job-source.ts';
16
- import { JobError, JobStore, type JobSnapshotOwner, type StoredJob } from './job-store.ts';
16
+ import { JobError, JobStore, jobCropReferences, type JobSnapshotOwner, type StoredJob } from './job-store.ts';
17
17
  import { canonicalStatePath } from './state-dir.ts';
18
+ import { loadReview } from './manifest.ts';
19
+ import { loadPartsView } from './parts-view.ts';
20
+ import { validateStoredPartsComment } from './parts-comment-crops.ts';
21
+ import { commentPartsIssues } from './parts-comment.ts';
18
22
 
19
23
  export type { JobDisplayPublicationV3 } from './job-contract.ts';
20
24
 
@@ -74,6 +78,37 @@ function assertStoredSchemas(data: JobData): void {
74
78
  if (data.apiSchema !== JOB_API_SCHEMA || data.actSchema !== JOB_ACT_SCHEMA) {
75
79
  throw new JobError('JOB_SOURCE_UNRETAINABLE', 'JOB_STORED_SCHEMA_MISMATCH');
76
80
  }
81
+ assertStoredEvidence(data);
82
+ }
83
+
84
+ /** Check only the new extension and its durable copies, including committed replay values. */
85
+ function assertStoredEvidence(data: JobData): void {
86
+ for (const stored of Object.values(data.publications)) {
87
+ assertStoredCheckpointEvidence(stored.retained);
88
+ assertStoredEvidenceCopy(stored.publication, data);
89
+ }
90
+ for (const ask of Object.values(data.asks)) assertStoredEvidenceCopy(ask, data);
91
+ for (const act of Object.values(data.acts)) assertStoredEvidenceCopy(act, data);
92
+ for (const event of data.events) {
93
+ if (event.type === 'published') assertStoredEvidenceCopy(event.publication, data);
94
+ if (event.type === 'pending') assertStoredEvidenceCopy(event.ask, data);
95
+ if (event.type === 'act') assertStoredEvidenceCopy(event.act, data);
96
+ }
97
+ for (const replay of Object.values(data.replays)) assertStoredEvidenceCopy(replay.value, data);
98
+ }
99
+
100
+ function assertStoredEvidenceCopy(value: unknown, data: JobData): void {
101
+ if (!value || typeof value !== 'object') return;
102
+ const copy = value as {publicationId: string; source: JobPublication['source'] | PublicationV3['source']};
103
+ const stored = data.publications[copy.publicationId];
104
+ const bound = stored?.retained.source;
105
+ if (!('source' in value) && !(bound && 'checkpointEvidence' in bound)) return;
106
+ if (!copy.source || typeof copy.source !== 'object' || Array.isArray(copy.source)) throw new JobError('JOB_SOURCE_MISMATCH');
107
+ if (!('checkpointEvidence' in copy.source) && !(bound && 'checkpointEvidence' in bound)) return;
108
+ if (!bound || copy.source.sourceHash !== bound.sourceHash ||
109
+ requestDigest(copy.source.checkpointEvidence ?? null) !== requestDigest(bound.checkpointEvidence ?? null) ||
110
+ requestDigest(copy.source.plan) !== requestDigest(bound.plan)) throw new JobError('JOB_SOURCE_MISMATCH');
111
+ if (isRecordSource(copy.source)) parseRecordSource(copy.source);
77
112
  }
78
113
 
79
114
  function within(root: string, path: string): boolean {
@@ -199,11 +234,12 @@ export class JobSession {
199
234
  return { jobId: this.jobId, fetchCapability: current.data.fetchCapability };
200
235
  }
201
236
 
202
- authorize(role: 'agent' | 'ui' | 'consumer', given: string | null): void {
237
+ authorize(role: 'agent' | 'ui' | 'ui-evidence' | 'consumer', given: string | null): void {
203
238
  const current = this.current();
204
239
  if (role === 'consumer' && !current.active) throw new JobError('JOB_CLOSED');
205
- const secret = role === 'agent' ? current.data.agentCapability : role === 'ui' ? current.data.uiCapability : current.data.fetchCapability;
206
- if (!secret || !sameCapability(given, role === 'ui' ? secret : 'Bearer ' + secret)) {
240
+ const ui = role === 'ui' || role === 'ui-evidence';
241
+ const secret = role === 'agent' ? current.data.agentCapability : ui ? current.data.uiCapability : current.data.fetchCapability;
242
+ if (!secret || !sameCapability(given, ui ? secret : 'Bearer ' + secret)) {
207
243
  throw new JobError('JOB_CAPABILITY_REQUIRED');
208
244
  }
209
245
  if (role === 'ui' && !current.active) throw new JobError('JOB_CLOSED');
@@ -356,6 +392,7 @@ export class JobSession {
356
392
  }
357
393
 
358
394
  private replay(data: JobData, key: string, digest: string): Replay | null {
395
+ assertStoredSchemas(data);
359
396
  const previous = data.replays[key];
360
397
  if (previous && previous.digest !== digest) throw new JobError('JOB_IDEMPOTENCY_CONFLICT');
361
398
  return previous ?? null;
@@ -369,7 +406,7 @@ export class JobSession {
369
406
 
370
407
  private event(data: JobData, value: JobEventPayload): EventV3 {
371
408
  const event: EventV3 = { ...value, cursor: randomUUID(), jobId: this.jobId, generation: data.generation };
372
- if (Buffer.byteLength(JSON.stringify(event)) > maximumEventBytes) {
409
+ if (Buffer.byteLength(jobCropReferences(event)) > maximumEventBytes) {
373
410
  throw new JobError('JOB_BODY_LIMIT', 'Job event exceeds its delivery bound');
374
411
  }
375
412
  data.events.push(event);
@@ -421,7 +458,7 @@ export class JobSession {
421
458
  jobId: this.jobId,
422
459
  generation: fresh.data.generation,
423
460
  };
424
- if (Buffer.byteLength(JSON.stringify(event)) > maximumEventBytes) {
461
+ if (Buffer.byteLength(jobCropReferences(event)) > maximumEventBytes) {
425
462
  throw new JobError('JOB_BODY_LIMIT', 'Job event exceeds its delivery bound');
426
463
  }
427
464
  fresh.data.events.push(event);
@@ -487,7 +524,7 @@ export class JobSession {
487
524
  switch (input.verb) {
488
525
  case 'publish': {
489
526
  assertJobSourceCurrent(candidate!);
490
- if (isRetainedRecordSource(candidate!)) {
527
+ if (isRetainedRecordSource(candidate!) || candidate!.source.checkpointEvidence) {
491
528
  assertRetainedSnapshotIntact(
492
529
  candidate!.snapshotRoot,
493
530
  candidate!.seals,
@@ -515,7 +552,7 @@ export class JobSession {
515
552
  if (data.head !== input.publicationId) throw new JobError('JOB_ACT_SOURCE_STALE');
516
553
  const retained = data.publications[input.publicationId].retained;
517
554
  assertJobSourceCurrent(retained);
518
- if (isRetainedRecordSource(retained)) {
555
+ if (isRetainedRecordSource(retained) || retained.source.checkpointEvidence) {
519
556
  assertRetainedSnapshotIntact(
520
557
  retained.snapshotRoot,
521
558
  retained.seals,
@@ -567,22 +604,37 @@ export class JobSession {
567
604
  readActExport(actId: string, png: boolean): Buffer {
568
605
  const current = this.current();
569
606
  if (!current.active) throw new JobError('JOB_CLOSED');
570
- const act = current.data.acts[actId];
571
- if (!act) throw new JobError('JOB_ACT_UNKNOWN');
572
- if (act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA) {
607
+ const storedAct = current.data.acts[actId];
608
+ if (!storedAct) throw new JobError('JOB_ACT_UNKNOWN');
609
+ // Validation must not replace the stored representation or reorder its keys.
610
+ if ((storedAct as {schema: string}).schema === JOB_COMMENTS_ACT_SCHEMA) parseCommentsAct(storedAct);
611
+ const still = 'still' in storedAct ? storedAct.still : undefined;
612
+ const actBytes = Buffer.from(JSON.stringify(storedAct));
613
+ if (storedAct.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && !still) {
573
614
  if (png) throw new JobError('JOB_STILL_UNAVAILABLE');
574
- return Buffer.from(JSON.stringify(act));
615
+ return actBytes;
575
616
  }
617
+ if (!still) throw new JobError('JOB_STILL_CAPTURE_FAILED');
576
618
  const stored = this.store.readStill(this.jobId, actId);
577
- if (!stored || stored.png.byteLength > jobStillByteLimit || stored.actBytes.byteLength > maximumEventBytes ||
578
- stored.sha256 !== act.still.sha256 || jobHash(stored.png) !== act.still.sha256 ||
579
- act.still.path !== act.still.sha256 + '.png' ||
580
- !Buffer.from(stored.actBytes).equals(Buffer.from(JSON.stringify(act)))) {
619
+ if (!stored || stored.png.byteLength > jobStillByteLimit || stored.actBytes.byteLength > jobActDeliveryLimit ||
620
+ stored.sha256 !== still.sha256 || jobHash(stored.png) !== still.sha256 ||
621
+ still.path !== still.sha256 + '.png' ||
622
+ !Buffer.from(stored.actBytes).equals(actBytes)) {
581
623
  throw new JobError('JOB_STILL_CAPTURE_FAILED');
582
624
  }
583
625
  return Buffer.from(png ? stored.png : stored.actBytes);
584
626
  }
585
627
 
628
+ readCommentCrop(sha256: string): Buffer {
629
+ const current = this.current();
630
+ let referenced = false;
631
+ jobCropReferences(current.data.events, hash => { if (hash === sha256) referenced = true; });
632
+ if (!/^[a-f0-9]{64}$/.test(sha256) || !referenced) {
633
+ throw new JobError('JOB_ACT_UNKNOWN');
634
+ }
635
+ return this.store.readCrop(sha256);
636
+ }
637
+
586
638
  ackDisplayed(input: JobDisplayAcknowledgment): JobDisplayReceipt {
587
639
  const current = this.current();
588
640
  let receipt: JobDisplayReceipt;
@@ -600,7 +652,9 @@ export class JobSession {
600
652
  }
601
653
 
602
654
  async commitUIAct(raw: unknown): Promise<ActV3> {
603
- const input = parseUISubmission(raw, this.publicationMode), digest = requestDigest(input), key = `ui:${input.pageId}:${input.submissionId}`;
655
+ const parsed = parseUISubmission(raw, this.publicationMode);
656
+ const input = parsed.kind === 'parts-verdict' ? {...parsed, value: structuredClone(parsed.value)} : parsed;
657
+ const digest = requestDigest(input), key = `ui:${input.pageId}:${input.submissionId}`;
604
658
  const current = this.current();
605
659
  const previous = this.replay(current.data, key, digest);
606
660
  if (previous) return previous.value as ActV3;
@@ -627,6 +681,36 @@ export class JobSession {
627
681
  phase: 'finalize',
628
682
  subject: ask.subject as RecordSubject,
629
683
  });
684
+ } else if (ask && stored && input.kind === 'parts-verdict') {
685
+ assertJobSourceCurrent(stored.retained);
686
+ const candidate = finalizeJobAct({jobId: this.jobId, submission: input, ask,
687
+ retained: stored.retained, reviewer: current.data.reviewer});
688
+ const issues = candidate.kind !== 'parts-verdict' ? [] : candidate.schema === JOB_COMMENTS_ACT_SCHEMA ?
689
+ commentPartsIssues(candidate.value.comments) : candidate.schema === JOB_PARTS_VERDICT_ACT_SCHEMA ? candidate.value.issues : [];
690
+ if (issues.length) {
691
+ await this.readPublicationResponse(input.publicationId, async retained => {
692
+ if (isRetainedRecordSource(retained) || !retained.source.parts) throw new JobError('JOB_ACT_SOURCE_STALE');
693
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals,
694
+ retained.snapshotIdentity, 'JOB_ACT_SOURCE_STALE');
695
+ try {
696
+ const review = await loadReview(retained.manifestPath);
697
+ const painting = review.handoff?.source;
698
+ const sealedPainting = painting && retained.seals.some(file =>
699
+ file.path === relative(retained.snapshotRoot, painting).split(sep).join('/')) ? painting : undefined;
700
+ const pkg = await loadPartsView(dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)),
701
+ {painting: sealedPainting, paintingRoot: retained.snapshotRoot});
702
+ for (const issue of issues) {
703
+ await validateStoredPartsComment(pkg, issue, false, {sourceHash: retained.source.sourceHash});
704
+ }
705
+ } catch (error) {
706
+ if (error instanceof JobError) throw error;
707
+ throw new JobError('JOB_ACT_INVALID');
708
+ }
709
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals,
710
+ retained.snapshotIdentity, 'JOB_ACT_SOURCE_STALE');
711
+ return new Response(null, {status: 204});
712
+ });
713
+ }
630
714
  }
631
715
  }
632
716
  }
@@ -646,7 +730,7 @@ export class JobSession {
646
730
  if (!ask) throw new JobError('JOB_ASK_INVALID');
647
731
  const retained = fresh.data.publications[input.publicationId].retained;
648
732
  assertJobSourceCurrent(retained);
649
- if (isRetainedRecordSource(retained)) {
733
+ if (isRetainedRecordSource(retained) || retained.source.checkpointEvidence || input.kind === 'parts-verdict') {
650
734
  assertRetainedSnapshotIntact(
651
735
  retained.snapshotRoot,
652
736
  retained.seals,
@@ -686,8 +770,9 @@ export class JobSession {
686
770
  let size = 0;
687
771
  for (const event of events.slice(index + 1, index + 65)) {
688
772
  const bytes = Buffer.byteLength(JSON.stringify(event));
689
- if (bytes > maximumEventBytes) throw new JobError('JOB_BODY_LIMIT', 'Stored job event exceeds its delivery bound');
690
- if (size + bytes > maximumEventBytes) break;
773
+ const metadataBytes = Buffer.byteLength(jobCropReferences(event));
774
+ if (metadataBytes > maximumEventBytes || bytes > jobActDeliveryLimit) throw new JobError('JOB_BODY_LIMIT', 'Stored job event exceeds its delivery bound');
775
+ if (batch.length && size + bytes > jobActDeliveryLimit) break;
691
776
  size += bytes;
692
777
  batch.push(event);
693
778
  }