rig-review 2.12.0 → 2.13.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 (89) hide show
  1. package/docs/DESIGN.md +82 -71
  2. package/docs/PANELS.md +20 -12
  3. package/docs/PARTS_VIEW.md +31 -11
  4. package/docs/REVIEW_PACKAGE.md +99 -9
  5. package/docs/STABILITY.md +74 -3
  6. package/docs/WORKFLOWS.md +40 -12
  7. package/package.json +2 -1
  8. package/skills/rig-review/SKILL.md +29 -1
  9. package/src/build.ts +10 -2
  10. package/src/cli.ts +14 -12
  11. package/src/compare-html.ts +22 -24
  12. package/src/compare-server.ts +1 -1
  13. package/src/create-pin-gate.ts +3 -0
  14. package/src/feedback-export.ts +49 -1
  15. package/src/front.ts +10 -16
  16. package/src/interview-routes.ts +1 -1
  17. package/src/job-act.ts +39 -21
  18. package/src/job-api.ts +102 -11
  19. package/src/job-contract.ts +44 -4
  20. package/src/job-front.ts +15 -7
  21. package/src/job-host.ts +4 -3
  22. package/src/job-hub.ts +4 -4
  23. package/src/job-session.ts +5 -2
  24. package/src/job-source.ts +42 -13
  25. package/src/joined-project.ts +61 -4
  26. package/src/open-workspace.ts +12 -12
  27. package/src/open.ts +17 -9
  28. package/src/parts-comment.ts +31 -1
  29. package/src/parts-server.ts +19 -7
  30. package/src/parts-view.ts +71 -20
  31. package/src/server.ts +30 -21
  32. package/src/stage-comment.ts +11 -1
  33. package/src/stage-parts.ts +18 -10
  34. package/web/animation-inspection.ts +1 -1
  35. package/web/bones-panel.ts +1 -3
  36. package/web/catalog-en.ts +76 -12
  37. package/web/catalog-ko.ts +76 -12
  38. package/web/cloth-panel.ts +1 -2
  39. package/web/compare.css +3 -9
  40. package/web/compare.html +3 -3
  41. package/web/compare.ts +69 -64
  42. package/web/cuts-panel.ts +1 -3
  43. package/web/density-strip-panel.ts +1 -2
  44. package/web/i18n.ts +13 -1
  45. package/web/idle-panel.ts +1 -2
  46. package/web/index.html +1 -5
  47. package/web/inspection-persistence.ts +2 -1
  48. package/web/inspector-blocks.ts +144 -39
  49. package/web/instance-access.ts +24 -5
  50. package/web/interview-panel.ts +224 -175
  51. package/web/job-hub.ts +50 -69
  52. package/web/job-rig-capture.ts +103 -10
  53. package/web/job-rig-screen.ts +317 -0
  54. package/web/job-session.ts +927 -1365
  55. package/web/main.ts +535 -129
  56. package/web/mesh-panel.ts +1 -2
  57. package/web/owner-workspace.ts +88 -109
  58. package/web/part-selection.ts +47 -6
  59. package/web/part-thumbnails.ts +20 -6
  60. package/web/parts-viewport-provider.ts +166 -9
  61. package/web/physics-panel.ts +1 -2
  62. package/web/readings-panel.ts +1 -2
  63. package/web/requirements-panel.ts +1 -3
  64. package/web/retained-frame-stage.ts +105 -0
  65. package/web/retarget-panel.ts +2 -3
  66. package/web/rig-fields-panel.ts +1 -2
  67. package/web/rig-host.ts +62 -0
  68. package/web/rig-viewport-provider.ts +63 -16
  69. package/web/stage-comments.ts +29 -26
  70. package/web/styles.css +127 -43
  71. package/web/view-controls.ts +201 -12
  72. package/web/viewport-controller.ts +97 -26
  73. package/web/viewport-pair.ts +2 -1
  74. package/web/workspace-preferences.ts +5 -4
  75. package/web/workspace-ui.ts +152 -19
  76. package/src/interview-server.ts +0 -54
  77. package/web/interview.css +0 -28
  78. package/web/interview.html +0 -17
  79. package/web/interview.ts +0 -40
  80. package/web/job-hub.css +0 -14
  81. package/web/job-hub.html +0 -5
  82. package/web/owner-workspace.css +0 -14
  83. package/web/owner-workspace.html +0 -5
  84. package/web/parts-flags.ts +0 -48
  85. package/web/parts-page.ts +0 -217
  86. package/web/parts.css +0 -116
  87. package/web/parts.html +0 -15
  88. package/web/parts.ts +0 -986
  89. package/web/stage-nav.ts +0 -136
package/src/job-act.ts CHANGED
@@ -1,15 +1,17 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import {
3
- JOB_ACT_SCHEMA, JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RECORD_ACT_KINDS, JOB_RECORD_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, jobStillByteLimit, JOB_ENABLED_ACT_KINDS, JOB_PLAN_BOUND_SIGNOFF_STAGES, JOB_RESERVED_ACT_KINDS,
4
- type ActV3, type JobAct, type JobActValues, type JobApiSchema, type JobPendingAsk, type JobPublicationMode, type JobReviewerBinding,
3
+ JOB_ACT_SCHEMA, JOB_API_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_API_V3_SCHEMA, JOB_RECORD_ACT_KINDS, JOB_RECORD_ACT_SCHEMA, jobStillByteLimit, JOB_ENABLED_ACT_KINDS, JOB_PLAN_BOUND_SIGNOFF_STAGES, JOB_RESERVED_ACT_KINDS,
4
+ type ActV3, type JobAct, 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 PendingAskV3, type RecordAct, type RecordSource, type RecordSubject, type SourceV3, type UISubmissionV3,
7
7
  } from './job-contract.ts';
8
8
  import { parsePartsIssue, type PartsIssue } from './parts-comment.ts';
9
9
  import {
10
10
  isRecordSource, jobHash, jobId, jobInteger, jobObject,
11
- parseRecordAct, parseRecordSource, requestDigest, validateRecordAskSubject,
11
+ parseCommentsAct, parseRecordAct, parseRecordSource, requestDigest, validateRecordAskSubject,
12
12
  } from './job-api.ts';
13
+ import { checkpointNoteComments, feedbackItemComments, noteComments, partsIssueComments } from './feedback-export.ts';
14
+ import type { Feedback } from './session.ts';
13
15
  import { validatePicks } from './interview-picks.ts';
14
16
  import {
15
17
  isRetainedRecordSource,
@@ -27,6 +29,12 @@ function words(value: unknown): string {
27
29
  return value;
28
30
  }
29
31
 
32
+ /** The writer's output must decode through the public @6 decoder; its refusal is JOB_ACT_INVALID. */
33
+ function commentsAct(act: JobCommentsAct): JobCommentsAct {
34
+ parseCommentsAct(act);
35
+ return act;
36
+ }
37
+
30
38
  function choice<Value extends string>(value: unknown, allowed: readonly Value[]): Value {
31
39
  if (!allowed.includes(value as Value)) throw new JobError('JOB_ACT_INVALID');
32
40
  return value as Value;
@@ -504,6 +512,8 @@ export function finalizeJobAct(options: {
504
512
  authority: { actor: 'human' as const, channel: 'review-ui' as const, reviewer: structuredClone(reviewer) },
505
513
  at,
506
514
  };
515
+ // Image-review and interview-picks keep act@2: Create refuses both under act@6.
516
+ const comments = {...envelope, schema: JOB_COMMENTS_ACT_SCHEMA};
507
517
  if (source.subject === 'image-set') {
508
518
  if (submission.kind !== 'review-verdict' || ask.subject.kind !== 'review-verdict' ||
509
519
  ask.subject.stage !== 'image-review') throw new JobError('JOB_ACT_INVALID');
@@ -553,10 +563,12 @@ export function finalizeJobAct(options: {
553
563
  const value = jobObject(submission.value, ['checkpointId', 'outcome', 'words']);
554
564
  const subject = ask.subject;
555
565
  if (subject.kind !== 'checkpoint' || value.checkpointId !== subject.checkpointId) throw new JobError('JOB_ACT_INVALID');
556
- return { ...envelope, kind: 'checkpoint', source: { ...source, plan: source.plan! }, value: {
557
- checkpointId: subject.checkpointId, planStepId: subject.planStepId ?? subject.checkpointId,
558
- outcome: choice(value.outcome, ['pass', 'fail'] as const), words: words(value.words),
559
- } };
566
+ const planStepId = subject.planStepId ?? subject.checkpointId, note = words(value.words);
567
+ return commentsAct({ ...comments, kind: 'checkpoint', source: { ...source, plan: source.plan! }, value: {
568
+ checkpointId: subject.checkpointId, planStepId,
569
+ outcome: choice(value.outcome, ['pass', 'fail'] as const),
570
+ comments: note.trim() ? checkpointNoteComments({checkpointId: subject.checkpointId, planStepId, note}) : [],
571
+ } });
560
572
  }
561
573
  case 'parts-verdict': {
562
574
  const value = jobObject(submission.value, ['verdict', 'issues', 'words']);
@@ -590,9 +602,8 @@ export function finalizeJobAct(options: {
590
602
  }
591
603
  return structuredClone(issue);
592
604
  });
593
- return {
594
- ...envelope,
595
- schema: JOB_PARTS_VERDICT_ACT_SCHEMA,
605
+ return commentsAct({
606
+ ...comments,
596
607
  kind: 'parts-verdict',
597
608
  source: {
598
609
  ...source,
@@ -600,31 +611,38 @@ export function finalizeJobAct(options: {
600
611
  selector: source.selector as Extract<NonNullable<JobSourceBinding['selector']>, { kind: 'draft' }>,
601
612
  parts: source.parts!,
602
613
  },
603
- value: { verdict, issues, words: words(value.words) },
604
- };
614
+ value: { verdict, comments: [...partsIssueComments(issues), ...noteComments(words(value.words))] },
615
+ });
605
616
  }
606
617
  case 'review-verdict': {
607
- const value = jobObject(submission.value, ['stage', 'verdict', 'words']);
618
+ const value = jobObject(submission.value, ['stage', 'verdict', 'words',
619
+ ...(ask.subject.kind === 'review-verdict' && ask.subject.stage === 'rig-review' ? ['feedback'] : [])]);
608
620
  if (ask.subject.kind !== 'review-verdict' || ask.subject.stage === 'image-review' || value.stage !== ask.subject.stage) throw new JobError('JOB_ACT_INVALID');
609
621
  if (ask.subject.stage === 'rig-review') {
610
622
  if (!options.still) throw new JobError('JOB_STILL_CAPTURE_FAILED');
611
- return {...envelope, schema: JOB_RIG_REVIEW_ACT_SCHEMA, kind: 'review-verdict',
623
+ const note = words(value.words);
624
+ if (value.feedback !== undefined && !Array.isArray(value.feedback)) throw new JobError('JOB_ACT_INVALID');
625
+ let verdictComments: ReturnType<typeof noteComments>;
626
+ try {
627
+ verdictComments = value.feedback === undefined ? noteComments(note) : feedbackItemComments(value.feedback as Feedback[]);
628
+ } catch { throw new JobError('JOB_ACT_INVALID'); }
629
+ return commentsAct({...comments, kind: 'review-verdict',
612
630
  source: {...source, model: source.model!, selector: source.selector as Extract<NonNullable<JobSourceBinding['selector']>, {kind: 'rig'}>},
613
- value: {stage: 'rig-review', verdict: choice(value.verdict, ['pending', 'approved', 'changes-requested'] as const), words: words(value.words)},
614
- still: options.still};
631
+ value: {stage: 'rig-review', verdict: choice(value.verdict, ['pending', 'approved', 'changes-requested'] as const), comments: verdictComments},
632
+ still: options.still});
615
633
  }
616
- return { ...envelope, kind: 'review-verdict', source: { ...source, model: source.model!,
634
+ return commentsAct({ ...comments, kind: 'review-verdict', source: { ...source, model: source.model!,
617
635
  selector: source.selector as Extract<NonNullable<JobSourceBinding['selector']>, { kind: 'rig' | 'post' }> }, value: {
618
- stage: ask.subject.stage, verdict: choice(value.verdict, ['pending', 'approved', 'changes-requested'] as const), words: words(value.words),
619
- } };
636
+ stage: ask.subject.stage, verdict: choice(value.verdict, ['pending', 'approved', 'changes-requested'] as const), comments: noteComments(words(value.words)),
637
+ } });
620
638
  }
621
639
  case 'signoff': {
622
640
  const value = jobObject(submission.value, ['stage', 'decision', 'words']);
623
641
  if (ask.subject.kind !== 'signoff' || value.stage !== ask.subject.stage || value.decision !== 'approved') {
624
642
  throw new JobError('JOB_ACT_INVALID');
625
643
  }
626
- const result: JobActValues['signoff'] = { stage: ask.subject.stage, decision: 'approved', words: words(value.words) };
627
- return { ...envelope, kind: 'signoff', source, value: result };
644
+ return commentsAct({ ...comments, kind: 'signoff', source,
645
+ value: { stage: ask.subject.stage, decision: 'approved', comments: noteComments(words(value.words)) } });
628
646
  }
629
647
  }
630
648
  }
package/src/job-api.ts CHANGED
@@ -17,14 +17,17 @@ import {
17
17
  } from './job-contract.ts';
18
18
  import { JobError } from './job-store.ts';
19
19
  import type { JobSession } from './job-session.ts';
20
- import { JOB_COMMENTS_ACT_SCHEMA, type JobComment, type JobCommentAnchor, type JobCommentsAct,
20
+ import { JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, type JobCommentContext, type JobContextComment,
21
+ type JobContextCommentsAct, type JobComment, type JobCommentAnchor, type JobCommentsAct,
21
22
  type SourceV3, type JobRigStill } from './job-contract.ts';
22
23
  import { parseFeedback } from './session.ts';
23
24
  import { parsePartsIssue } from './parts-comment.ts';
24
- import { parseStageComment, hasStageComment, projectComments } from './stage-comment.ts';
25
+ import { parseStageComment, hasStageComment, projectComments, commentModes } from './stage-comment.ts';
25
26
  import { validatePngCrop, validatePngCropMetadata } from './comment-crops.ts';
26
27
  import {parseJobImageSetBinding} from './job-image-set.ts';
27
28
  import {parseJobPartsIdentity} from './job-source.ts';
29
+ import {parseControlPart, parseControlView} from './control.ts';
30
+ import {EMIT_UNPINNED_CREATE_FIELDS} from './create-pin-gate.ts';
28
31
 
29
32
  export type {
30
33
  JobInterviewJson,
@@ -1269,26 +1272,93 @@ function parseCommentAnchor(raw: unknown, text: string, source?: SourceV3 | stri
1269
1272
 
1270
1273
  /** Structural/source-identity decoding only. Original asset freshness remains with the retained-source owner. */
1271
1274
  export function parseComments(value: unknown, source?: SourceV3 | string): JobComment[] {
1275
+ return decodeComments(value, source, false);
1276
+ }
1277
+
1278
+ function decodeComments(value: unknown, source: SourceV3 | string | undefined, withContext: false): JobComment[];
1279
+ function decodeComments(value: unknown, source: SourceV3 | string | undefined, withContext: true): JobContextComment[];
1280
+ function decodeComments(value: unknown, source: SourceV3 | string | undefined, withContext: boolean): JobContextComment[] {
1272
1281
  return asCode(() => {
1273
1282
  if (!Array.isArray(value) || value.length > 1000) throw new JobError('JOB_ACT_INVALID');
1274
1283
  const ids = new Set<string>();
1275
- const comments = value.map(raw => {
1276
- const item = commentsObject(raw, ['text'], ['anchor']);
1284
+ const comments: JobContextComment[] = value.map(raw => {
1285
+ const item = commentsObject(raw, ['text'], withContext ? ['anchor', 'context'] : ['anchor']);
1277
1286
  const text = parseActWords(item.text, 'JOB_ACT_INVALID');
1278
1287
  if (!text.trim()) throw new JobError('JOB_ACT_INVALID');
1279
- if (!Object.hasOwn(item, 'anchor')) return {text};
1288
+ const context = Object.hasOwn(item, 'context') ? {context: parseCommentContext(item.context, source)} : {};
1289
+ if (!Object.hasOwn(item, 'anchor')) return {text, ...context};
1280
1290
  const anchor = parseCommentAnchor(item.anchor, text, source);
1281
1291
  if ('id' in anchor) {
1282
1292
  if (ids.has(anchor.id)) throw new JobError('JOB_ACT_INVALID');
1283
1293
  ids.add(anchor.id);
1284
1294
  }
1285
- return {text, anchor};
1295
+ return {text, anchor, ...context};
1286
1296
  });
1287
- projectComments(comments);
1297
+ // The signed projection covers text and anchor only; context restores a view and is not signed text.
1298
+ projectComments(comments.map(({text, anchor}) => anchor === undefined ? {text} : {text, anchor}));
1288
1299
  return comments;
1289
1300
  }, 'JOB_ACT_INVALID');
1290
1301
  }
1291
1302
 
1303
+ /** act@7 comment context. Each field reuses the decoder of the pin or restore path it copies. */
1304
+ function parseCommentContext(raw: unknown, source?: SourceV3 | string): JobCommentContext {
1305
+ const item = commentsObject(raw, [], ['subject', 'mode', 'tab', 'part', 'region', 'viewMode', 'camera', 'frame']);
1306
+ if (!Object.keys(item).length) throw new JobError('JOB_ACT_INVALID');
1307
+ const out: Record<string, unknown> = {};
1308
+ if ('subject' in item) {
1309
+ const subject = commentsObject(item.subject, ['ask', 'sourceHash'], ['selector']);
1310
+ const ask = parseJobSubject(subject.ask), sourceHash = jobSha(subject.sourceHash);
1311
+ const selector = 'selector' in subject ? parseJobSelector(subject.selector) : undefined;
1312
+ if (selector === null) throw new JobError('JOB_ACT_INVALID');
1313
+ const bound = typeof source === 'string' ? source : source?.sourceHash;
1314
+ if (bound && sourceHash !== bound) throw new JobError('JOB_ACT_SOURCE_STALE');
1315
+ if (selector && source && typeof source !== 'string' && !('record' in source) && source.subject !== 'image-set' &&
1316
+ JSON.stringify(selector) !== JSON.stringify(source.selector)) throw new JobError('JOB_ACT_SOURCE_STALE');
1317
+ out.subject = {ask, sourceHash, ...(selector ? {selector} : {})};
1318
+ }
1319
+ if ('mode' in item) {
1320
+ if (!(commentModes as readonly unknown[]).includes(item.mode)) throw new JobError('JOB_ACT_INVALID');
1321
+ out.mode = item.mode;
1322
+ }
1323
+ if ('tab' in item) {
1324
+ // The inspector values parseBookmark accepts (web/inspection-persistence.ts).
1325
+ if (!['view', 'rig', 'playback', 'feedback'].includes(item.tab as string)) throw new JobError('JOB_ACT_INVALID');
1326
+ out.tab = item.tab;
1327
+ }
1328
+ if ('part' in item) {
1329
+ const part = parseControlPart(item.part);
1330
+ if (!part) throw new JobError('JOB_ACT_INVALID');
1331
+ out.part = part;
1332
+ }
1333
+ if ('region' in item) {
1334
+ const region = commentsObject(item.region, ['x', 'y', 'width', 'height']);
1335
+ for (const axis of ['x', 'y', 'width', 'height']) {
1336
+ const n = region[axis];
1337
+ if (typeof n !== 'number' || !Number.isFinite(n) || Math.abs(n) > Number.MAX_SAFE_INTEGER) throw new JobError('JOB_ACT_INVALID');
1338
+ }
1339
+ if ((region.width as number) < 0 || (region.height as number) < 0) throw new JobError('JOB_ACT_INVALID');
1340
+ out.region = {x: region.x, y: region.y, width: region.width, height: region.height};
1341
+ }
1342
+ if ('viewMode' in item) {
1343
+ if (item.viewMode !== 'item' && item.viewMode !== 'assembled') throw new JobError('JOB_ACT_INVALID');
1344
+ out.viewMode = item.viewMode;
1345
+ }
1346
+ if ('camera' in item) {
1347
+ const space = (item.camera as {space?: unknown} | null)?.space;
1348
+ if (space !== 'world' && space !== 'image') throw new JobError('JOB_ACT_INVALID');
1349
+ const cameras = {rig: null, a: null, b: null, reference: null, [space === 'world' ? 'rig' : 'reference']: item.camera};
1350
+ const view = parseControlView({schema: 'rig-review-view/1', cameras});
1351
+ out.camera = space === 'world' ? view.cameras.rig : view.cameras.reference;
1352
+ }
1353
+ if ('frame' in item) {
1354
+ const frame = commentsObject(item.frame, ['index', 'basis']);
1355
+ if (!Number.isSafeInteger(frame.index) || (frame.index as number) < 0 ||
1356
+ (frame.basis !== 'producer' && frame.basis !== 'reference')) throw new JobError('JOB_ACT_INVALID');
1357
+ out.frame = {index: frame.index, basis: frame.basis};
1358
+ }
1359
+ return out as JobCommentContext;
1360
+ }
1361
+
1292
1362
  function commentsSource(raw: unknown): Exclude<SourceV3, OptionSource> {
1293
1363
  if (isRecordSource(raw)) {
1294
1364
  const record = parseRecordSource(raw);
@@ -1329,11 +1399,30 @@ function commentsSource(raw: unknown): Exclude<SourceV3, OptionSource> {
1329
1399
  return structuredClone(item) as unknown as Exclude<SourceV3, OptionSource>;
1330
1400
  }
1331
1401
 
1332
- /** Public @6 decoder. Current UI finalizers continue to emit their existing versions. */
1402
+ /** Public @6 decoder. The UI finalizers write checkpoint, parts, rig/post verdict and signoff acts at @6 (#713). */
1333
1403
  export function parseCommentsAct(raw: unknown): JobCommentsAct {
1404
+ return decodeCommentsAct(raw, false) as JobCommentsAct;
1405
+ }
1406
+
1407
+ /** Public @7 decoder: the @6 rules plus an optional `context` on each comment. @6 input refuses. */
1408
+ export function parseContextCommentsAct(raw: unknown): JobContextCommentsAct {
1409
+ return decodeCommentsAct(raw, true) as JobContextCommentsAct;
1410
+ }
1411
+
1412
+ /** The comments act a writer sends. With EMIT_UNPINNED_CREATE_FIELDS off, contexts are dropped and @6 goes out. */
1413
+ export function commentsActForEmission(act: JobCommentsAct | JobContextCommentsAct,
1414
+ emitUnpinned: boolean = EMIT_UNPINNED_CREATE_FIELDS): JobCommentsAct | JobContextCommentsAct {
1415
+ const value = act.value as {comments: readonly JobContextComment[]};
1416
+ const comments = value.comments.map(({context, ...comment}) => emitUnpinned && context ? {...comment, context} : comment);
1417
+ const schema = emitUnpinned && comments.some(comment => 'context' in comment) ? JOB_COMMENT_CONTEXT_ACT_SCHEMA : JOB_COMMENTS_ACT_SCHEMA;
1418
+ const next = {...structuredClone(act), schema, value: {...structuredClone(act.value), comments: structuredClone(comments)}};
1419
+ return schema === JOB_COMMENTS_ACT_SCHEMA ? parseCommentsAct(next) : parseContextCommentsAct(next);
1420
+ }
1421
+
1422
+ function decodeCommentsAct(raw: unknown, withContext: boolean): JobCommentsAct | JobContextCommentsAct {
1334
1423
  return asCode(() => {
1335
1424
  const item = commentsObject(raw, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value'], ['still']);
1336
- if (item.schema !== JOB_COMMENTS_ACT_SCHEMA) throw new JobError('JOB_ACT_INVALID');
1425
+ if (item.schema !== (withContext ? JOB_COMMENT_CONTEXT_ACT_SCHEMA : JOB_COMMENTS_ACT_SCHEMA)) throw new JobError('JOB_ACT_INVALID');
1337
1426
  for (const key of ['actId', 'jobId', 'askId', 'publicationId']) jobId(item[key]);
1338
1427
  parseHumanAuthority(item.authority, 'JOB_ACT_INVALID');
1339
1428
  if (typeof item.at !== 'string' || !Number.isFinite(Date.parse(item.at))) throw new JobError('JOB_ACT_INVALID');
@@ -1347,8 +1436,10 @@ export function parseCommentsAct(raw: unknown): JobCommentsAct {
1347
1436
  if (!keys) throw new JobError('JOB_ACT_INVALID');
1348
1437
  if (source.subject === 'image-set' && item.kind !== 'review-verdict') throw new JobError('JOB_ACT_INVALID');
1349
1438
  const value = commentsObject(item.value, keys);
1350
- const comments = parseComments(value.comments, source);
1439
+ const comments = withContext ? decodeComments(value.comments, source, true) : parseComments(value.comments, source);
1351
1440
  if (comments.some(comment => comment.anchor && 'side' in comment.anchor)) throw new JobError('JOB_ACT_INVALID');
1441
+ if ((comments as readonly JobContextComment[]).some(comment => comment.context?.subject &&
1442
+ comment.context.subject.ask.kind !== item.kind)) throw new JobError('JOB_ACT_INVALID');
1352
1443
  if (item.kind === 'checkpoint') {
1353
1444
  const checkpointId = jobId(value.checkpointId), planStepId = jobId(value.planStepId);
1354
1445
  if (typeof value.outcome !== 'string' || !['pass', 'fail'].includes(value.outcome)) throw new JobError('JOB_ACT_INVALID');
@@ -1377,7 +1468,7 @@ export function parseCommentsAct(raw: unknown): JobCommentsAct {
1377
1468
  (still.frame === 'setup' ? 'animation' in still : typeof still.frame !== 'number' || !Number.isFinite(still.frame) ||
1378
1469
  still.frame < 0 || typeof still.animation !== 'string' || !still.animation)) throw new JobError('JOB_ACT_INVALID');
1379
1470
  } else if ('still' in item) throw new JobError('JOB_ACT_INVALID');
1380
- return {...structuredClone(item), source, value: {...value, comments}} as unknown as JobCommentsAct;
1471
+ return {...structuredClone(item), source, value: {...value, comments}} as unknown as JobCommentsAct | JobContextCommentsAct;
1381
1472
  }, 'JOB_ACT_INVALID');
1382
1473
  }
1383
1474
 
@@ -17,6 +17,7 @@ import type { Feedback, ReviewSession } from './session.ts';
17
17
  import type { CompareFeedback, CompareSession } from './compare-session.ts';
18
18
  import type { MarkRegion } from './stage-comment.ts';
19
19
  import type { PartsVerdict } from './parts-view.ts';
20
+ import type { ControlNumericCamera, ControlPart } from './control.ts';
20
21
 
21
22
  export const JOB_API_SCHEMA = 'rig-review/job-api@2' as const;
22
23
  export const JOB_API_V3_SCHEMA = 'rig-review/job-api@3' as const;
@@ -27,8 +28,10 @@ export const JOB_RIG_REVIEW_ACT_SCHEMA = 'rig-review/act@3' as const;
27
28
  export const JOB_RECORD_ACT_SCHEMA = 'rig-review/act@4' as const;
28
29
  /** New parts verdicts only. Historical @2 parts-verdict acts remain readable. */
29
30
  export const JOB_PARTS_VERDICT_ACT_SCHEMA = 'rig-review/act@5' as const;
30
- /** Read/parse contract only until the Create comments consumer is published. */
31
+ /** Fresh checkpoint, parts-verdict, rig/post review-verdict and signoff writers. Image-review and interview-picks stay @2; record acts stay @4. */
31
32
  export const JOB_COMMENTS_ACT_SCHEMA = 'rig-review/act@6' as const;
33
+ /** @6 plus an optional per-comment `context`. Emitted only behind EMIT_UNPINNED_CREATE_FIELDS (#714). */
34
+ export const JOB_COMMENT_CONTEXT_ACT_SCHEMA = 'rig-review/act@7' as const;
32
35
  export const REVIEW_COMMENTS_SESSION_SCHEMA = 'rig-review-session/2' as const;
33
36
  export const REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA = 'rig-review-compare-session/2' as const;
34
37
  export const PARTS_COMMENTS_VERDICT_SCHEMA = 'rig-review-parts-verdict/5' as const;
@@ -44,6 +47,32 @@ export type JobCommentImageAnchor = { readonly name: string } | {
44
47
  export type JobCommentAnchor = JobCommentFeedbackAnchor | JobCommentPartsAnchor | JobCommentImageAnchor
45
48
  | { readonly checkpointId: string; readonly planStepId: string };
46
49
  export interface JobComment { readonly text: string; readonly anchor?: JobCommentAnchor }
50
+ /** Where a comment was made, so opening it can restore that view (#714, act@7).
51
+ * Every field is optional and copies a value an existing pin or restore path already carries.
52
+ */
53
+ export interface JobCommentContext {
54
+ /** The ask subject, its source hash and its version selector, bound to the act's own source. */
55
+ readonly subject?: {
56
+ readonly ask: JobSubject;
57
+ readonly sourceHash: JobSha256;
58
+ readonly selector?: JobSelector;
59
+ };
60
+ /** Workspace mode: StageComment.mode and InspectionSelection.mode. */
61
+ readonly mode?: 'setup' | 'animate' | 'compare';
62
+ /** Inspector tab: InspectionSelection.inspector. */
63
+ readonly tab?: 'view' | 'rig' | 'playback' | 'feedback';
64
+ /** Selected part: InspectionSelection.part. */
65
+ readonly part?: ControlPart;
66
+ /** Marked region in world space: StageComment.world and PartsIssue.rigRegion. */
67
+ readonly region?: MarkRegion;
68
+ /** Parts view mode: PartsIssue.view.mode. */
69
+ readonly viewMode?: 'item' | 'assembled';
70
+ /** Numeric camera: StageComment.camera. */
71
+ readonly camera?: ControlNumericCamera;
72
+ /** Explicit frame: StageComment.frame. */
73
+ readonly frame?: { readonly index: number; readonly basis: 'producer' | 'reference' };
74
+ }
75
+ export interface JobContextComment extends JobComment { readonly context?: JobCommentContext }
47
76
  export interface JobCommentsActValues {
48
77
  readonly checkpoint: { readonly checkpointId: string; readonly planStepId: string;
49
78
  readonly outcome: 'pass' | 'fail'; readonly comments: readonly JobComment[] };
@@ -60,6 +89,13 @@ export type JobCommentsAct = {
60
89
  readonly source: Exclude<SourceV3, OptionSource>; readonly value: JobCommentsActValues[Kind]; readonly still?: JobRigStill;
61
90
  }
62
91
  }[keyof JobCommentsActValues];
92
+ /** act@7: the @6 envelope whose comments may carry `context`. */
93
+ export type JobContextCommentsAct = {
94
+ [Kind in keyof JobCommentsActValues]: Omit<Extract<JobCommentsAct, { readonly kind: Kind }>, 'schema' | 'value'> & {
95
+ readonly schema: typeof JOB_COMMENT_CONTEXT_ACT_SCHEMA;
96
+ readonly value: Omit<JobCommentsActValues[Kind], 'comments'> & { readonly comments: readonly JobContextComment[] };
97
+ }
98
+ }[keyof JobCommentsActValues];
63
99
  export type ReviewCommentsSession = Omit<ReviewSession, 'schema' | 'feedback' | 'checkpoints'> & {
64
100
  schema: typeof REVIEW_COMMENTS_SESSION_SCHEMA;
65
101
  checkpoints: Record<string, { outcome: 'pending' | 'pass' | 'fail' }>;
@@ -488,8 +524,11 @@ export interface JobActValues {
488
524
  * supplies checkpoint ID, outcome and words only. Create derives execution
489
525
  * stage from its authoritative step phase/order. Review never stamps a stage.
490
526
  */
491
- export type JobUIActValues = Omit<JobActValues, 'checkpoint'> & {
527
+ export type JobUIActValues = Omit<JobActValues, 'checkpoint' | 'review-verdict'> & {
492
528
  readonly checkpoint: Omit<JobActValues['checkpoint'], 'planStepId'>;
529
+ readonly 'review-verdict': JobImageReviewValue
530
+ | (JobModelReviewValue & {readonly stage: 'direction-review'})
531
+ | (JobModelReviewValue & {readonly stage: 'rig-review'; readonly feedback?: readonly Feedback[]});
493
532
  };
494
533
 
495
534
  export interface JobActSources {
@@ -557,8 +596,9 @@ export type JobPartsVerdictAct = Omit<Extract<JobLegacyAct, {kind: 'parts-verdic
557
596
  readonly value: PartsVerdictValue;
558
597
  };
559
598
 
560
- /** Historical @2 acts remain readable without being backfilled or relabelled. */
561
- export type JobAct = JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct;
599
+ /** Historical @2 acts remain readable without being backfilled or relabelled.
600
+ * Fresh checkpoint, parts, rig/post verdict and signoff acts are written as act@6. */
601
+ export type JobAct = JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct | JobCommentsAct;
562
602
 
563
603
  /** Authenticated browser provenance. The daemon validates identity and hashes PNG bytes. */
564
604
  export interface JobRigCapture {
package/src/job-front.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import {PNG} from 'pngjs';
1
2
  import {checkpointEvidenceMetadata, readCheckpointEvidenceBytes} from './job-checkpoint-evidence.ts';
2
3
  /** Disjoint live-job routes. The backend receives the original authenticated Request. */
3
4
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobHostPorts, type JobId, type JobPublicationMode, type JobResult, type JobReviewerBinding } from './job-contract.ts';
@@ -9,9 +10,9 @@ import { JobError, JobStore } from './job-store.ts';
9
10
  import { loadReview, safeFile, packagePath, type ReviewPackage } from './manifest.ts';
10
11
  import { serveReference, assertReviewUnchanged } from './reference.ts';
11
12
  import {preparePartsComment} from './parts-comment-crops.ts';
12
- import { loadPartsView, partsViewJson, servedImage, type PartsViewPackage } from './parts-view.ts';
13
+ import { loadPartsView, partsViewJson, partsDifference, servedImage, type PartsViewPackage } from './parts-view.ts';
13
14
  import { destinationDirectory, DestinationDirectoryError } from './destination-directory.ts';
14
- import { dirname, isAbsolute, join, relative, sep } from 'node:path';
15
+ import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
15
16
  import { constants, openSync, closeSync, readSync, fstatSync, lstatSync, statSync, type Stats } from 'node:fs';
16
17
  import { lstat, mkdir, rename, writeFile } from 'node:fs/promises';
17
18
  import { randomUUID } from 'node:crypto';
@@ -228,10 +229,7 @@ export function jobWindowResources() {
228
229
  '<title>rig-review</title><link rel="stylesheet" href="styles.css"></head>' +
229
230
  '<body data-job-window><script type="module" src="job.js"></script></body></html>';
230
231
  }
231
- if (name === 'styles.css')
232
- return (await Bun.file(new URL('../web/styles.css', import.meta.url)).text()) +
233
- '\n@scope (.job-inspection[data-job-parts-workspace]) {\n' +
234
- (await Bun.file(new URL('../web/parts.css', import.meta.url)).text()) + '\n}';
232
+ if (name === 'styles.css')return await Bun.file(new URL('../web/styles.css', import.meta.url)).text();
235
233
  bundle ??= buildJobWindow();
236
234
  return bundle;
237
235
  };
@@ -333,7 +331,10 @@ export function retainedPublicationRoutes(session: JobSession) {
333
331
  const parts = partsRoot ? await loadPartsView(partsRoot, {
334
332
  rig: rigRoot ? retainedFile(join(rigRoot, 'rig.json')) : undefined,
335
333
  meshReport: rigRoot ? retainedFile(join(rigRoot, 'mesh_report.json')) : undefined,
336
- painting: review.handoff?.source ? retainedFile(review.handoff.source) : undefined,
334
+ // The original SVG stays a sealed Review reference; Parts' optional
335
+ // native-pixel comparison accepts PNG bytes, not vector artwork.
336
+ painting: review.handoff?.source && extname(review.handoff.source).toLowerCase() !== '.svg'
337
+ ? retainedFile(review.handoff.source) : undefined,
337
338
  paintingRoot: retained.snapshotRoot,
338
339
  }) : null;
339
340
  if (parts) {
@@ -426,6 +427,13 @@ export function retainedPublicationRoutes(session: JobSession) {
426
427
  return json({...partsViewJson(parts, {verdict: null, stale: null}), sourceHash: retained.source.sourceHash,
427
428
  inspectionSourceHash: retained.source.sourceHash, readOnly: true});
428
429
  }
430
+ const difference=/^api\/stage-parts\/difference\/(0|[1-9]\d*)$/.exec(path);
431
+ if(difference&&parts){
432
+ const url=new URL(request.url),threshold=url.searchParams.get('threshold'),footprints=url.searchParams.get('footprints');
433
+ if(!threshold||!/^\d{1,3}$/.test(threshold)||!['true','false'].includes(footprints??''))return failure('JOB_REQUEST_INVALID',400);
434
+ const raster=await partsDifference(parts,Number(difference[1]),Number(threshold),footprints==='true'),png=new PNG({width:raster.width,height:raster.height});png.data=Buffer.from(raster.data);
435
+ return new Response(request.method==='HEAD'?null:new Uint8Array(PNG.sync.write(png)),{headers:{...headers,'Content-Type':'image/png','X-Difference-Count':String(raster.count),'X-Difference-Covered':String(raster.covered),'X-Difference-Compared':String(raster.compared)}});
436
+ }
429
437
  const part = /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.exec(path);
430
438
  if (part && parts) {
431
439
  const file = servedImage(parts, part[1] as 'image' | 'page', Number(part[2]));
package/src/job-host.ts CHANGED
@@ -23,19 +23,20 @@ export type {
23
23
  JobRootIdentity,
24
24
  } from './job-source.ts';
25
25
  export {parseRecordAct} from './job-api.ts';
26
- export {parseCommentsAct} from './job-api.ts';
26
+ export {parseCommentsAct, parseContextCommentsAct} from './job-api.ts';
27
27
  export {projectComments} from './stage-comment.ts';
28
28
  export {parseCommentsSession} from './session.ts';
29
29
  export {parseCommentsCompareSession} from './compare-session.ts';
30
30
  export {parseCommentsPartsVerdict} from './parts-view.ts';
31
31
  export {projectSelectedCommentsFeedback} from './feedback-export.ts';
32
32
  export {
33
- JOB_COMMENTS_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
33
+ JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
34
34
  REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA, PARTS_COMMENTS_VERDICT_SCHEMA,
35
35
  } from './job-contract.ts';
36
36
  export type {
37
37
  JobComment, JobCommentAnchor, JobCommentFeedbackAnchor, JobCommentPartsAnchor, JobCommentImageAnchor,
38
- JobCommentsAct, JobCommentsActValues, ReviewCommentsSession, CompareCommentsSession, PartsCommentsVerdict,
38
+ JobCommentsAct, JobCommentsActValues, ReviewCommentsSession,
39
+ JobCommentContext, JobContextComment, JobContextCommentsAct, CompareCommentsSession, PartsCommentsVerdict,
39
40
  } from './job-contract.ts';
40
41
  export {prepareJobRecordAct} from './job-act.ts';
41
42
  export {
package/src/job-hub.ts CHANGED
@@ -154,20 +154,20 @@ export async function startJobHub(options: JobHubOptions): Promise<JobOwnerHub>
154
154
  try {
155
155
  const url = new URL(request.url);
156
156
  if (url.origin !== origin) return refused('JOB_LOOPBACK_REQUIRED', 403);
157
- const resource = url.pathname === '/hub/' ? 'job-hub.html' : url.pathname === '/hub/job-hub.js' ? 'job-hub.js'
158
- : url.pathname === '/hub/job-hub.css' ? 'job-hub.css' : url.pathname === '/hub/styles.css' ? 'styles.css' : null;
157
+ const resource = url.pathname === '/hub/' ? 'index.html' : url.pathname === '/hub/main.js' ? 'main.js'
158
+ : url.pathname === '/hub/styles.css' ? 'styles.css' : null;
159
159
  if (resource) {
160
160
  if (!['GET', 'HEAD'].includes(request.method)) return refused('JOB_REQUEST_INVALID', 405);
161
161
  if (request.headers.get('sec-fetch-site') === 'cross-site' ||
162
162
  request.headers.get('origin') !== null && request.headers.get('origin') !== origin) return refused('JOB_SAME_ORIGIN_REQUIRED', 403);
163
- if (resource === 'job-hub.html') {
163
+ if (resource === 'index.html') {
164
164
  if (url.searchParams.get('workspace') !== incarnation ||
165
165
  [...url.searchParams.keys()].some(key => !['workspace', 'lang'].includes(key) || url.searchParams.getAll(key).length !== 1) ||
166
166
  url.searchParams.has('lang') && !['en', 'ko'].includes(url.searchParams.get('lang')!)) return refused('JOB_REQUEST_INVALID', 400);
167
167
  } else if (url.search) return refused('JOB_REQUEST_INVALID', 400);
168
168
  let body: BodyInit | null = null;
169
169
  if (request.method !== 'HEAD') {
170
- if (resource === 'job-hub.js') body = await (hubBundle ??= buildWeb('job-hub'));
170
+ if (resource === 'main.js') body = await (hubBundle ??= buildWeb('job-hub'));
171
171
  else body = Bun.file(new URL('../web/' + resource, import.meta.url));
172
172
  }
173
173
  return new Response(body, {headers: {...responseHeaders,
@@ -18,6 +18,7 @@ import { canonicalStatePath } from './state-dir.ts';
18
18
  import { loadReview } from './manifest.ts';
19
19
  import { loadPartsView } from './parts-view.ts';
20
20
  import { validateStoredPartsComment } from './parts-comment-crops.ts';
21
+ import { commentPartsIssues } from './parts-comment.ts';
21
22
 
22
23
  export type { JobDisplayPublicationV3 } from './job-contract.ts';
23
24
 
@@ -673,7 +674,9 @@ export class JobSession {
673
674
  assertJobSourceCurrent(stored.retained);
674
675
  const candidate = finalizeJobAct({jobId: this.jobId, submission: input, ask,
675
676
  retained: stored.retained, reviewer: current.data.reviewer});
676
- if (candidate.schema === JOB_PARTS_VERDICT_ACT_SCHEMA && candidate.value.issues.length) {
677
+ const issues = candidate.kind !== 'parts-verdict' ? [] : candidate.schema === JOB_COMMENTS_ACT_SCHEMA ?
678
+ commentPartsIssues(candidate.value.comments) : candidate.schema === JOB_PARTS_VERDICT_ACT_SCHEMA ? candidate.value.issues : [];
679
+ if (issues.length) {
677
680
  await this.readPublicationResponse(input.publicationId, async retained => {
678
681
  if (isRetainedRecordSource(retained) || !retained.source.parts) throw new JobError('JOB_ACT_SOURCE_STALE');
679
682
  assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals,
@@ -685,7 +688,7 @@ export class JobSession {
685
688
  file.path === relative(retained.snapshotRoot, painting).split(sep).join('/')) ? painting : undefined;
686
689
  const pkg = await loadPartsView(dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)),
687
690
  {painting: sealedPainting, paintingRoot: retained.snapshotRoot});
688
- for (const issue of candidate.value.issues) {
691
+ for (const issue of issues) {
689
692
  await validateStoredPartsComment(pkg, issue, false, {sourceHash: retained.source.sourceHash});
690
693
  }
691
694
  } catch (error) {
package/src/job-source.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import {resolvePartsPaintingInRig} from './parts-view.ts';
1
2
  import {checkpointEvidenceFields, checkpointEvidenceMetadata} from './job-checkpoint-evidence.ts';
2
3
  import { randomUUID } from 'node:crypto';
3
4
  import { type Dirent, lstatSync, readdirSync, realpathSync, type Stats } from 'node:fs';
@@ -234,6 +235,21 @@ function referenceRow(raw: unknown, row: number, hashed: boolean): JobPartsFileR
234
235
  return {path, role, ...(hashed ? {sha256: item.sha256 as string} : {})};
235
236
  }
236
237
 
238
+ /** Reuse the official-reference PNG admission and decoded-size bound for generic sidecar operands. */
239
+ function assertPartsReferencePng(data: Buffer, detail: string): void {
240
+ if (data.length < 33 || !data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
241
+ data.readUInt32BE(8) !== 13 || data.toString('ascii', 12, 16) !== 'IHDR') {
242
+ throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
243
+ }
244
+ const width = data.readUInt32BE(16), height = data.readUInt32BE(20);
245
+ if (!width || !height) throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
246
+ if (width > Math.floor(maxFileBytes / 4 / height)) {
247
+ throw new JobError('JOB_SOURCE_UNRETAINABLE', `PARTS_REFERENCE_LIMIT ${detail}`);
248
+ }
249
+ try { PNG.sync.read(data); }
250
+ catch { throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`); }
251
+ }
252
+
237
253
  function partsIdentityHeader(value: unknown): {raw: Record<string, unknown>; version: string} {
238
254
  const raw = jobObject(value, ['enumeratorVersion', 'manifest', 'images']);
239
255
  return {raw, version: jobPartsEnumeratorVersion(raw.enumeratorVersion)};
@@ -265,7 +281,7 @@ export function parseJobPartsIdentity(value: unknown): JobPartsIdentity {
265
281
  * enumerator. Review compares its exact array and validates byte boundaries.
266
282
  */
267
283
  async function prepareParts(root: string, snapshotRoot: string, claimed: JobPartsIdentity | null,
268
- enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
284
+ declared: readonly JobFileIdentity[], enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
269
285
  const bytes = new Map<string, Buffer>();
270
286
  if (claimed === null) return {identity: null, bytes};
271
287
  if (!enumerator) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_ENUMERATOR_UNAVAILABLE');
@@ -334,17 +350,7 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
334
350
  }
335
351
  }
336
352
  if (!decoded.has(path)) {
337
- if (data.length < 33 || !data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
338
- data.readUInt32BE(8) !== 13 || data.toString('ascii', 12, 16) !== 'IHDR') {
339
- throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
340
- }
341
- const width = data.readUInt32BE(16), height = data.readUInt32BE(20);
342
- if (!width || !height) throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
343
- if (width > Math.floor(maxFileBytes / 4 / height)) {
344
- throw new JobError('JOB_SOURCE_UNRETAINABLE', `PARTS_REFERENCE_LIMIT ${detail}`);
345
- }
346
- try { PNG.sync.read(data); }
347
- catch { throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`); }
353
+ assertPartsReferencePng(data, detail);
348
354
  bytes.set(path, data);
349
355
  decoded.add(path);
350
356
  }
@@ -354,6 +360,29 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
354
360
  }
355
361
  images.push({path: reference.path, role: reference.role, sha256});
356
362
  }
363
+ // Inline declarations retain their historical admission behavior; fallback is never a rescue.
364
+ if (!Object.hasOwn(JSON.parse(manifestBytes.toString('utf8')), 'painting_in_rig')) {
365
+ try {
366
+ const resolved = await resolvePartsPaintingInRig(dirname(join(root, manifestPath)), manifestBytes,
367
+ async (absolute, kind) => {
368
+ const data = sourceBytes(root, rootRelative(root, absolute));
369
+ if (kind === 'painting') assertPartsReferencePng(data, 'painting_in_rig');
370
+ return data;
371
+ });
372
+ if (resolved.sidecar) for (const file of resolved.files) {
373
+ const path = rootRelative(root, file.declaredPath ?? file.abs);
374
+ if (!declared.some(row => row.path === path && row.sha256 === file.sha256)) {
375
+ throw new JobError('JOB_SOURCE_MISMATCH', 'PARTS_DIFFERENCE_PROVENANCE: sidecar and painting require generic file identities');
376
+ }
377
+ const data = sourceBytes(root, path);
378
+ if (jobHash(data) !== file.sha256) throw new JobError('JOB_SOURCE_MISMATCH');
379
+ bytes.set(path, data);
380
+ }
381
+ } catch (error) {
382
+ if (error instanceof JobError) throw error;
383
+ throw new JobError('JOB_SOURCE_MISMATCH', error instanceof Error ? error.message : 'PARTS_DIFFERENCE_PROVENANCE');
384
+ }
385
+ }
357
386
  return {identity: {enumeratorVersion: version, manifest: {path: manifestPath, sha256: jobHash(manifestBytes)}, images}, bytes};
358
387
  }
359
388
 
@@ -1317,7 +1346,7 @@ export async function prepareJobSource(options: {
1317
1346
  const imageSet = context.imageSet === undefined ? null : prepareJobImageSet(context.imageSet,
1318
1347
  path => sourceBytes(root.path, path));
1319
1348
  for (const image of imageSet?.imageSet.images ?? []) add(image.path, image.sha256);
1320
- const parts = await prepareParts(root.path, snapshotRoot, context.parts, options.partsEnumerator);
1349
+ const parts = await prepareParts(root.path, snapshotRoot, context.parts, declared, options.partsEnumerator);
1321
1350
  for (const [path, bytes] of parts.bytes) add(path, jobHash(bytes));
1322
1351
  if (wanted.size > maxSourceFiles) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
1323
1352
  let size = 0;