rig-review 2.11.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 (94) hide show
  1. package/docs/DESIGN.md +145 -74
  2. package/docs/PANELS.md +20 -12
  3. package/docs/PARTS_VIEW.md +31 -11
  4. package/docs/REVIEW_PACKAGE.md +215 -0
  5. package/docs/STABILITY.md +98 -2
  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/comment-crops.ts +6 -1
  12. package/src/compare-html.ts +22 -24
  13. package/src/compare-server.ts +1 -1
  14. package/src/compare-session.ts +41 -3
  15. package/src/create-pin-gate.ts +3 -0
  16. package/src/feedback-export.ts +67 -0
  17. package/src/front.ts +10 -16
  18. package/src/interview-routes.ts +1 -1
  19. package/src/job-act.ts +39 -21
  20. package/src/job-api.ts +291 -0
  21. package/src/job-cli.ts +20 -11
  22. package/src/job-contract.ts +91 -3
  23. package/src/job-front.ts +15 -7
  24. package/src/job-host.ts +15 -0
  25. package/src/job-hub.ts +4 -4
  26. package/src/job-image-set.ts +32 -9
  27. package/src/job-session.ts +19 -11
  28. package/src/job-source.ts +74 -30
  29. package/src/joined-project.ts +61 -4
  30. package/src/open-workspace.ts +12 -12
  31. package/src/open.ts +17 -9
  32. package/src/parts-comment.ts +31 -1
  33. package/src/parts-server.ts +19 -7
  34. package/src/parts-view.ts +103 -20
  35. package/src/server.ts +30 -21
  36. package/src/session.ts +58 -0
  37. package/src/stage-comment.ts +39 -0
  38. package/src/stage-parts.ts +18 -10
  39. package/web/animation-inspection.ts +1 -1
  40. package/web/bones-panel.ts +1 -3
  41. package/web/catalog-en.ts +76 -12
  42. package/web/catalog-ko.ts +76 -12
  43. package/web/cloth-panel.ts +1 -2
  44. package/web/compare.css +3 -9
  45. package/web/compare.html +3 -3
  46. package/web/compare.ts +69 -64
  47. package/web/cuts-panel.ts +1 -3
  48. package/web/density-strip-panel.ts +1 -2
  49. package/web/i18n.ts +13 -1
  50. package/web/idle-panel.ts +1 -2
  51. package/web/index.html +1 -5
  52. package/web/inspection-persistence.ts +2 -1
  53. package/web/inspector-blocks.ts +144 -39
  54. package/web/instance-access.ts +24 -5
  55. package/web/interview-panel.ts +224 -175
  56. package/web/job-hub.ts +50 -69
  57. package/web/job-rig-capture.ts +103 -10
  58. package/web/job-rig-screen.ts +317 -0
  59. package/web/job-session.ts +927 -1365
  60. package/web/main.ts +535 -129
  61. package/web/mesh-panel.ts +1 -2
  62. package/web/owner-workspace.ts +88 -109
  63. package/web/part-selection.ts +47 -6
  64. package/web/part-thumbnails.ts +20 -6
  65. package/web/parts-viewport-provider.ts +166 -9
  66. package/web/physics-panel.ts +1 -2
  67. package/web/readings-panel.ts +1 -2
  68. package/web/requirements-panel.ts +1 -3
  69. package/web/retained-frame-stage.ts +105 -0
  70. package/web/retarget-panel.ts +2 -3
  71. package/web/rig-fields-panel.ts +1 -2
  72. package/web/rig-host.ts +62 -0
  73. package/web/rig-viewport-provider.ts +63 -16
  74. package/web/stage-comments.ts +29 -26
  75. package/web/styles.css +127 -43
  76. package/web/view-controls.ts +201 -12
  77. package/web/viewport-controller.ts +97 -26
  78. package/web/viewport-pair.ts +2 -1
  79. package/web/workspace-preferences.ts +5 -4
  80. package/web/workspace-ui.ts +152 -19
  81. package/src/interview-server.ts +0 -54
  82. package/web/interview.css +0 -28
  83. package/web/interview.html +0 -17
  84. package/web/interview.ts +0 -40
  85. package/web/job-hub.css +0 -14
  86. package/web/job-hub.html +0 -5
  87. package/web/owner-workspace.css +0 -14
  88. package/web/owner-workspace.html +0 -5
  89. package/web/parts-flags.ts +0 -48
  90. package/web/parts-page.ts +0 -217
  91. package/web/parts.css +0 -116
  92. package/web/parts.html +0 -15
  93. package/web/parts.ts +0 -986
  94. package/web/stage-nav.ts +0 -136
package/src/job-cli.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import {closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync} from 'node:fs';
3
3
  import {join} from 'node:path';
4
- import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit,
5
- type JobAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
- import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest } from './job-api.ts';
4
+ import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit,
5
+ type JobAct, type JobCommentsAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
+ import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest, parseCommentsAct } from './job-api.ts';
7
7
  import { JobError } from './job-store.ts';
8
8
  import {validatePngBytes} from './comment-crops.ts';
9
9
  import {destinationDirectory} from './destination-directory.ts';
@@ -145,11 +145,18 @@ async function consumerBytes(stream: ReadableStream<Uint8Array> | null, maximum:
145
145
  }
146
146
  }
147
147
 
148
- function parseConsumerAct(bytes: Buffer, job: string, actId: string): JobAct {
148
+ type ConsumerAct = JobAct | JobCommentsAct;
149
+
150
+ function parseConsumerAct(bytes: Buffer, job: string, actId: string): ConsumerAct {
149
151
  let value: unknown;
150
152
  try { value = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes)); }
151
153
  catch { throw new JobError('JOB_REQUEST_INVALID'); }
152
154
  const act = jobObject(value, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value', 'still']);
155
+ if (act.schema === JOB_COMMENTS_ACT_SCHEMA) {
156
+ const comments = parseCommentsAct(act);
157
+ if (comments.jobId !== job || comments.actId !== actId) throw new JobError('JOB_ACT_INVALID');
158
+ return comments;
159
+ }
153
160
  if (act.jobId !== job || act.actId !== actId ||
154
161
  (act.schema !== JOB_ACT_SCHEMA && act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && act.schema !== JOB_PARTS_VERDICT_ACT_SCHEMA)) {
155
162
  throw new JobError('JOB_ACT_INVALID');
@@ -178,7 +185,8 @@ function unlinkOwned(path: string, identity: {dev: number; ino: number}): void {
178
185
  }
179
186
  }
180
187
 
181
- function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAct, destination: string | undefined, options: JobCLIOptions): void {
188
+ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: ConsumerAct, destination: string | undefined, options: JobCLIOptions): void {
189
+ const still = 'still' in act ? act.still : undefined;
182
190
  let temporary: string | undefined;
183
191
  let temporaryIdentity: {dev: number; ino: number} | undefined;
184
192
  let installed: string | undefined;
@@ -188,7 +196,7 @@ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAc
188
196
  let lockDescriptor: number | undefined;
189
197
  let emitted = 0;
190
198
  try {
191
- if (png && destination && act.schema === JOB_RIG_REVIEW_ACT_SCHEMA) {
199
+ if (png && destination && still) {
192
200
  const directory = destinationDirectory(destination, 'JOB_STILL_OUTPUT_FAILED', false);
193
201
  const directoryDescriptor = openSync(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | constants.O_NOFOLLOW);
194
202
  try {
@@ -204,13 +212,13 @@ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAc
204
212
  }
205
213
  throw error;
206
214
  }
207
- const target = join(directory, act.still.path);
215
+ const target = join(directory, still.path);
208
216
  let existing = false;
209
217
  try {
210
218
  const descriptor = openSync(target, constants.O_RDONLY | constants.O_NOFOLLOW);
211
219
  try {
212
220
  const info = fstatSync(descriptor);
213
- if (!info.isFile() || info.size > jobStillByteLimit || jobHash(readFileSync(descriptor)) !== act.still.sha256) {
221
+ if (!info.isFile() || info.size > jobStillByteLimit || jobHash(readFileSync(descriptor)) !== still.sha256) {
214
222
  throw new JobError('JOB_STILL_OUTPUT_FAILED');
215
223
  }
216
224
  existing = true;
@@ -307,14 +315,15 @@ async function fetchActCommand(args: readonly string[], options: JobCLIOptions):
307
315
  }
308
316
  const bytes = await read(jobRawActMediaType, 512 * 1024);
309
317
  const act = parseConsumerAct(bytes, job, actId);
318
+ const still = 'still' in act ? act.still : undefined;
310
319
  const destination = values.get('still-out');
311
- if (act.schema === JOB_RIG_REVIEW_ACT_SCHEMA && destination === undefined) throw new JobError('JOB_STILL_OUTPUT_FAILED');
320
+ if (still && destination === undefined) throw new JobError('JOB_STILL_OUTPUT_FAILED');
312
321
  let png: Buffer | undefined;
313
322
  if (destination !== undefined) {
314
- if (act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA) throw new JobError('JOB_STILL_UNAVAILABLE');
323
+ if (!still) throw new JobError('JOB_STILL_UNAVAILABLE');
315
324
  png = await read('image/png', jobStillByteLimit);
316
325
  try {
317
- if (png.length < 33 || jobHash(png) !== act.still.sha256) throw new Error('hash');
326
+ if (png.length < 33 || jobHash(png) !== still.sha256) throw new Error('hash');
318
327
  validatePngBytes(png, png.readUInt32BE(16), png.readUInt32BE(20));
319
328
  } catch { throw new JobError('JOB_STILL_CAPTURE_FAILED'); }
320
329
  }
@@ -13,6 +13,11 @@
13
13
 
14
14
  import type { JobPublicationReader } from './job-source.ts';
15
15
  import type { PartsIssue } from './parts-comment.ts';
16
+ import type { Feedback, ReviewSession } from './session.ts';
17
+ import type { CompareFeedback, CompareSession } from './compare-session.ts';
18
+ import type { MarkRegion } from './stage-comment.ts';
19
+ import type { PartsVerdict } from './parts-view.ts';
20
+ import type { ControlNumericCamera, ControlPart } from './control.ts';
16
21
 
17
22
  export const JOB_API_SCHEMA = 'rig-review/job-api@2' as const;
18
23
  export const JOB_API_V3_SCHEMA = 'rig-review/job-api@3' as const;
@@ -23,6 +28,85 @@ export const JOB_RIG_REVIEW_ACT_SCHEMA = 'rig-review/act@3' as const;
23
28
  export const JOB_RECORD_ACT_SCHEMA = 'rig-review/act@4' as const;
24
29
  /** New parts verdicts only. Historical @2 parts-verdict acts remain readable. */
25
30
  export const JOB_PARTS_VERDICT_ACT_SCHEMA = 'rig-review/act@5' as const;
31
+ /** Fresh checkpoint, parts-verdict, rig/post review-verdict and signoff writers. Image-review and interview-picks stay @2; record acts stay @4. */
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;
35
+ export const REVIEW_COMMENTS_SESSION_SCHEMA = 'rig-review-session/2' as const;
36
+ export const REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA = 'rig-review-compare-session/2' as const;
37
+ export const PARTS_COMMENTS_VERDICT_SCHEMA = 'rig-review-parts-verdict/5' as const;
38
+
39
+ export type JobCommentFeedbackAnchor = Omit<Feedback, 'summary'> | Omit<CompareFeedback, 'summary'>;
40
+ export type JobCommentPartsAnchor = Omit<PartsIssue, 'summary'>;
41
+ export type JobCommentImageAnchor = { readonly name: string } | {
42
+ readonly name: string;
43
+ readonly imageRegion: MarkRegion;
44
+ readonly crop: PartsIssue['crop'];
45
+ readonly nativeCrop: NonNullable<PartsIssue['nativeCrop']>;
46
+ };
47
+ export type JobCommentAnchor = JobCommentFeedbackAnchor | JobCommentPartsAnchor | JobCommentImageAnchor
48
+ | { readonly checkpointId: string; readonly planStepId: string };
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 }
76
+ export interface JobCommentsActValues {
77
+ readonly checkpoint: { readonly checkpointId: string; readonly planStepId: string;
78
+ readonly outcome: 'pass' | 'fail'; readonly comments: readonly JobComment[] };
79
+ readonly 'parts-verdict': { readonly verdict: 'approved' | 'changes-requested'; readonly comments: readonly JobComment[] };
80
+ readonly 'review-verdict': { readonly stage: JobReviewStage; readonly verdict: JobVerdict; readonly comments: readonly JobComment[] };
81
+ readonly signoff: { readonly stage: string; readonly decision: 'approved'; readonly comments: readonly JobComment[] };
82
+ readonly reopen: { readonly stage: string; readonly comments: readonly JobComment[] };
83
+ }
84
+ export type JobCommentsAct = {
85
+ [Kind in keyof JobCommentsActValues]: {
86
+ readonly schema: typeof JOB_COMMENTS_ACT_SCHEMA;
87
+ readonly actId: string; readonly jobId: string; readonly askId: string; readonly publicationId: string;
88
+ readonly kind: Kind; readonly authority: JobHumanAuthority; readonly at: string;
89
+ readonly source: Exclude<SourceV3, OptionSource>; readonly value: JobCommentsActValues[Kind]; readonly still?: JobRigStill;
90
+ }
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];
99
+ export type ReviewCommentsSession = Omit<ReviewSession, 'schema' | 'feedback' | 'checkpoints'> & {
100
+ schema: typeof REVIEW_COMMENTS_SESSION_SCHEMA;
101
+ checkpoints: Record<string, { outcome: 'pending' | 'pass' | 'fail' }>;
102
+ comments: JobComment[];
103
+ };
104
+ export type CompareCommentsSession = Omit<CompareSession, 'schema' | 'feedback'> & {
105
+ schema: typeof REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA; comments: JobComment[];
106
+ };
107
+ export type PartsCommentsVerdict = Omit<PartsVerdict, 'schema' | 'issues'> & {
108
+ schema: typeof PARTS_COMMENTS_VERDICT_SCHEMA; comments: JobComment[];
109
+ };
26
110
  export const JOB_PANEL_COMPOSITION_SCHEMA = 'rig-review/panels@1' as const;
27
111
 
28
112
  export type PanelSlot = 'left' | 'stage' | 'toolbar' | 'side';
@@ -440,8 +524,11 @@ export interface JobActValues {
440
524
  * supplies checkpoint ID, outcome and words only. Create derives execution
441
525
  * stage from its authoritative step phase/order. Review never stamps a stage.
442
526
  */
443
- export type JobUIActValues = Omit<JobActValues, 'checkpoint'> & {
527
+ export type JobUIActValues = Omit<JobActValues, 'checkpoint' | 'review-verdict'> & {
444
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[]});
445
532
  };
446
533
 
447
534
  export interface JobActSources {
@@ -509,8 +596,9 @@ export type JobPartsVerdictAct = Omit<Extract<JobLegacyAct, {kind: 'parts-verdic
509
596
  readonly value: PartsVerdictValue;
510
597
  };
511
598
 
512
- /** Historical @2 acts remain readable without being backfilled or relabelled. */
513
- 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;
514
602
 
515
603
  /** Authenticated browser provenance. The daemon validates identity and hashes PNG bytes. */
516
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,6 +23,21 @@ export type {
23
23
  JobRootIdentity,
24
24
  } from './job-source.ts';
25
25
  export {parseRecordAct} from './job-api.ts';
26
+ export {parseCommentsAct, parseContextCommentsAct} from './job-api.ts';
27
+ export {projectComments} from './stage-comment.ts';
28
+ export {parseCommentsSession} from './session.ts';
29
+ export {parseCommentsCompareSession} from './compare-session.ts';
30
+ export {parseCommentsPartsVerdict} from './parts-view.ts';
31
+ export {projectSelectedCommentsFeedback} from './feedback-export.ts';
32
+ export {
33
+ JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
34
+ REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA, PARTS_COMMENTS_VERDICT_SCHEMA,
35
+ } from './job-contract.ts';
36
+ export type {
37
+ JobComment, JobCommentAnchor, JobCommentFeedbackAnchor, JobCommentPartsAnchor, JobCommentImageAnchor,
38
+ JobCommentsAct, JobCommentsActValues, ReviewCommentsSession,
39
+ JobCommentContext, JobContextComment, JobContextCommentsAct, CompareCommentsSession, PartsCommentsVerdict,
40
+ } from './job-contract.ts';
26
41
  export {prepareJobRecordAct} from './job-act.ts';
27
42
  export {
28
43
  JOB_CAPABILITIES,
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,
@@ -1,5 +1,5 @@
1
1
  import type {JobImageSetInput, JobImageSourceBinding} from './job-contract.ts';
2
- import {jobHash, jobObject, jobPath, jobSha, jobText} from './job-api.ts';
2
+ import {exactObject, jobHash, jobObject, jobPath, jobSha, jobText, requestDigest} from './job-api.ts';
3
3
  import {JobError} from './job-store.ts';
4
4
 
5
5
  /** Check discovery before sending an image ask, including against older hubs. */
@@ -10,9 +10,11 @@ export function assertJobImageSetCapability(capabilities: unknown): void {
10
10
  }
11
11
  }
12
12
 
13
- /** Hash the actual bytes. Array order and exact Unicode strings are significant. */
14
- export function prepareJobImageSet(input: JobImageSetInput,
15
- readBytes: (path: string) => Uint8Array): Pick<JobImageSourceBinding, 'imageSet' | 'imageSetDigest' | 'duplicateHashes'> {
13
+ type ImageSetBinding = Pick<JobImageSourceBinding, 'imageSet' | 'imageSetDigest' | 'duplicateHashes'>;
14
+ type ImageSetRead = {kind: 'bytes'; readBytes: (path: string) => Uint8Array} | {kind: 'sealed'};
15
+
16
+ /** One declared-shape/digest codec; only byte preparation reads and hashes assets. */
17
+ function imageSetBinding(input: JobImageSetInput, read: ImageSetRead): ImageSetBinding {
16
18
  try { jobObject(input, ['purpose', 'images']); }
17
19
  catch { throw new JobError('JOB_IMAGE_SET_INVALID'); }
18
20
  if (input.purpose !== 'plate-adoption' || !Array.isArray(input.images) ||
@@ -33,11 +35,17 @@ export function prepareJobImageSet(input: JobImageSetInput,
33
35
  if (names.has(name)) throw new JobError('JOB_IMAGE_SET_DUPLICATE_NAME');
34
36
  if (paths.has(path)) throw new JobError('JOB_IMAGE_SET_DUPLICATE_PATH');
35
37
  names.add(name); paths.add(path);
36
- let bytes: Uint8Array;
37
- try { bytes = readBytes(path); }
38
- catch { throw new JobError('JOB_IMAGE_SET_PATH_REFUSED'); }
39
- const sha256 = jobHash(bytes);
40
- if (raw.sha256 !== undefined && raw.sha256 !== sha256) throw new JobError('JOB_SOURCE_MISMATCH');
38
+ let sha256: string;
39
+ if (read.kind === 'bytes') {
40
+ let bytes: Uint8Array;
41
+ try { bytes = read.readBytes(path); }
42
+ catch { throw new JobError('JOB_IMAGE_SET_PATH_REFUSED'); }
43
+ sha256 = jobHash(bytes);
44
+ if (raw.sha256 !== undefined && raw.sha256 !== sha256) throw new JobError('JOB_SOURCE_MISMATCH');
45
+ } else {
46
+ try { sha256 = jobSha(raw.sha256); }
47
+ catch { throw new JobError('JOB_IMAGE_SET_INVALID'); }
48
+ }
41
49
  const group = hashes.get(sha256) ?? [];
42
50
  group.push(name); hashes.set(sha256, group);
43
51
  return {role: raw.role, name, path, sha256};
@@ -48,3 +56,18 @@ export function prepareJobImageSet(input: JobImageSetInput,
48
56
  return {imageSet: {purpose: input.purpose, images}, imageSetDigest: jobHash(JSON.stringify(canonical)),
49
57
  duplicateHashes: [...hashes].filter(([, names]) => names.length > 1).map(([sha256, names]) => ({names, sha256}))};
50
58
  }
59
+
60
+ /** Hash the actual bytes. Array order and exact Unicode strings are significant. */
61
+ export function prepareJobImageSet(input: JobImageSetInput,
62
+ readBytes: (path: string) => Uint8Array): ImageSetBinding {
63
+ return imageSetBinding(input, {kind: 'bytes', readBytes});
64
+ }
65
+
66
+ /** Decode declared sealed identities without a byte reader or a native freshness claim. */
67
+ export function parseJobImageSetBinding(value: unknown): ImageSetBinding {
68
+ const raw = exactObject(value, ['imageSet', 'imageSetDigest', 'duplicateHashes'], 'JOB_IMAGE_SET_INVALID');
69
+ const binding = imageSetBinding(raw.imageSet as JobImageSetInput, {kind: 'sealed'});
70
+ if (jobSha(raw.imageSetDigest) !== binding.imageSetDigest ||
71
+ requestDigest(raw.duplicateHashes) !== requestDigest(binding.duplicateHashes)) throw new JobError('JOB_IMAGE_SET_INVALID');
72
+ return binding;
73
+ }
@@ -1,14 +1,14 @@
1
1
  import { randomBytes, randomUUID } from 'node:crypto';
2
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_PARTS_VERDICT_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, 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 { isRecordSource, parseRecordSource, 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
13
  assertStoredCheckpointEvidence, assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, prepareJobSource, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
14
14
  type JobPublicationReader, type JobRetainedSource, type JobRetainedSourceV3, type JobRootIdentity,
@@ -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
 
@@ -602,17 +603,22 @@ export class JobSession {
602
603
  readActExport(actId: string, png: boolean): Buffer {
603
604
  const current = this.current();
604
605
  if (!current.active) throw new JobError('JOB_CLOSED');
605
- const act = current.data.acts[actId];
606
- if (!act) throw new JobError('JOB_ACT_UNKNOWN');
607
- if (act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA) {
606
+ const storedAct = current.data.acts[actId];
607
+ if (!storedAct) throw new JobError('JOB_ACT_UNKNOWN');
608
+ // Validation must not replace the stored representation or reorder its keys.
609
+ if ((storedAct as {schema: string}).schema === JOB_COMMENTS_ACT_SCHEMA) parseCommentsAct(storedAct);
610
+ const still = 'still' in storedAct ? storedAct.still : undefined;
611
+ const actBytes = Buffer.from(JSON.stringify(storedAct));
612
+ if (storedAct.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && !still) {
608
613
  if (png) throw new JobError('JOB_STILL_UNAVAILABLE');
609
- return Buffer.from(JSON.stringify(act));
614
+ return actBytes;
610
615
  }
616
+ if (!still) throw new JobError('JOB_STILL_CAPTURE_FAILED');
611
617
  const stored = this.store.readStill(this.jobId, actId);
612
618
  if (!stored || stored.png.byteLength > jobStillByteLimit || stored.actBytes.byteLength > maximumEventBytes ||
613
- stored.sha256 !== act.still.sha256 || jobHash(stored.png) !== act.still.sha256 ||
614
- act.still.path !== act.still.sha256 + '.png' ||
615
- !Buffer.from(stored.actBytes).equals(Buffer.from(JSON.stringify(act)))) {
619
+ stored.sha256 !== still.sha256 || jobHash(stored.png) !== still.sha256 ||
620
+ still.path !== still.sha256 + '.png' ||
621
+ !Buffer.from(stored.actBytes).equals(actBytes)) {
616
622
  throw new JobError('JOB_STILL_CAPTURE_FAILED');
617
623
  }
618
624
  return Buffer.from(png ? stored.png : stored.actBytes);
@@ -668,7 +674,9 @@ export class JobSession {
668
674
  assertJobSourceCurrent(stored.retained);
669
675
  const candidate = finalizeJobAct({jobId: this.jobId, submission: input, ask,
670
676
  retained: stored.retained, reviewer: current.data.reviewer});
671
- 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) {
672
680
  await this.readPublicationResponse(input.publicationId, async retained => {
673
681
  if (isRetainedRecordSource(retained) || !retained.source.parts) throw new JobError('JOB_ACT_SOURCE_STALE');
674
682
  assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals,
@@ -680,7 +688,7 @@ export class JobSession {
680
688
  file.path === relative(retained.snapshotRoot, painting).split(sep).join('/')) ? painting : undefined;
681
689
  const pkg = await loadPartsView(dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)),
682
690
  {painting: sealedPainting, paintingRoot: retained.snapshotRoot});
683
- for (const issue of candidate.value.issues) {
691
+ for (const issue of issues) {
684
692
  await validateStoredPartsComment(pkg, issue, false, {sourceHash: retained.source.sourceHash});
685
693
  }
686
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,30 +235,63 @@ 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
+
253
+ function partsIdentityHeader(value: unknown): {raw: Record<string, unknown>; version: string} {
254
+ const raw = jobObject(value, ['enumeratorVersion', 'manifest', 'images']);
255
+ return {raw, version: jobPartsEnumeratorVersion(raw.enumeratorVersion)};
256
+ }
257
+
258
+ function partsManifest(value: unknown): JobFileIdentity {
259
+ try {
260
+ const raw = jobObject(value, ['path', 'sha256']);
261
+ const path = jobPath(raw.path);
262
+ if (posix.basename(path) !== 'parts.json') throw new Error('Manifest directory API');
263
+ return {path, sha256: jobSha(raw.sha256)};
264
+ } catch { throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_PATH_REFUSED manifest'); }
265
+ }
266
+
267
+ function partsReferenceList(value: unknown): unknown[] {
268
+ if (!Array.isArray(value) || value.length > maxSourceFiles) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
269
+ return value;
270
+ }
271
+
272
+ /** Pure declared identity decoder; official enumeration and native bytes remain preparation checks. */
273
+ export function parseJobPartsIdentity(value: unknown): JobPartsIdentity {
274
+ const {raw, version} = partsIdentityHeader(value);
275
+ const manifest = partsManifest(raw.manifest);
276
+ const images = partsReferenceList(raw.images).map((row, index) => referenceRow(row, index, true));
277
+ return {enumeratorVersion: version, manifest, images: images as JobPartsIdentity['images']};
278
+ }
279
+
237
280
  /** Membership, order and duplicate semantics belong solely to the trusted public
238
281
  * enumerator. Review compares its exact array and validates byte boundaries.
239
282
  */
240
283
  async function prepareParts(root: string, snapshotRoot: string, claimed: JobPartsIdentity | null,
241
- enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
284
+ declared: readonly JobFileIdentity[], enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
242
285
  const bytes = new Map<string, Buffer>();
243
286
  if (claimed === null) return {identity: null, bytes};
244
287
  if (!enumerator) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_ENUMERATOR_UNAVAILABLE');
245
- jobObject(claimed, ['enumeratorVersion', 'manifest', 'images']);
246
- const version = jobPartsEnumeratorVersion(claimed.enumeratorVersion);
288
+ const {version} = partsIdentityHeader(claimed);
247
289
  if (version !== jobPartsEnumeratorVersion(enumerator.version)) {
248
290
  throw new JobError('JOB_SOURCE_UNRETAINABLE',
249
291
  `PARTS_ENUMERATOR_VERSION_MISMATCH range="${JOB_PARTS_ENUMERATOR_RANGE}" received="${version}" installed="${enumerator.version}"`);
250
292
  }
251
- let manifestPath: string;
252
- try {
253
- jobObject(claimed.manifest, ['path', 'sha256']);
254
- manifestPath = jobPath(claimed.manifest.path);
255
- if (posix.basename(manifestPath) !== 'parts.json') throw new Error('Manifest directory API');
256
- jobSha(claimed.manifest.sha256);
257
- } catch { throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_PATH_REFUSED manifest'); }
258
- if (!Array.isArray(claimed.images) || claimed.images.length > maxSourceFiles) {
259
- throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
260
- }
293
+ const {path: manifestPath} = partsManifest(claimed.manifest);
294
+ const claimedImages = partsReferenceList(claimed.images);
261
295
  let manifestBytes: Buffer;
262
296
  try { manifestBytes = sourceBytes(root, manifestPath); }
263
297
  catch (error) {
@@ -282,11 +316,8 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
282
316
  throw new JobError('JOB_SOURCE_MISMATCH', 'PARTS_ENUMERATION_REFUSED' + rule);
283
317
  }
284
318
  } finally { await rm(enumerationRoot, {recursive: true, force: true}); }
285
- if (!Array.isArray(references) || references.length > maxSourceFiles) {
286
- throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
287
- }
288
- const official = references.map((raw, row) => referenceRow(raw, row, false));
289
- const supplied = claimed.images.map((raw, row) => referenceRow(raw, row, true));
319
+ const official = partsReferenceList(references).map((raw, row) => referenceRow(raw, row, false));
320
+ const supplied = claimedImages.map((raw, row) => referenceRow(raw, row, true));
290
321
  const difference = official.findIndex((row, i) => row.path !== supplied[i]?.path || row.role !== supplied[i]?.role);
291
322
  if (difference !== -1 || official.length !== supplied.length) {
292
323
  throw new JobError('JOB_SOURCE_MISMATCH',
@@ -319,17 +350,7 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
319
350
  }
320
351
  }
321
352
  if (!decoded.has(path)) {
322
- if (data.length < 33 || !data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
323
- data.readUInt32BE(8) !== 13 || data.toString('ascii', 12, 16) !== 'IHDR') {
324
- throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
325
- }
326
- const width = data.readUInt32BE(16), height = data.readUInt32BE(20);
327
- if (!width || !height) throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
328
- if (width > Math.floor(maxFileBytes / 4 / height)) {
329
- throw new JobError('JOB_SOURCE_UNRETAINABLE', `PARTS_REFERENCE_LIMIT ${detail}`);
330
- }
331
- try { PNG.sync.read(data); }
332
- catch { throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`); }
353
+ assertPartsReferencePng(data, detail);
333
354
  bytes.set(path, data);
334
355
  decoded.add(path);
335
356
  }
@@ -339,6 +360,29 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
339
360
  }
340
361
  images.push({path: reference.path, role: reference.role, sha256});
341
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
+ }
342
386
  return {identity: {enumeratorVersion: version, manifest: {path: manifestPath, sha256: jobHash(manifestBytes)}, images}, bytes};
343
387
  }
344
388
 
@@ -1302,7 +1346,7 @@ export async function prepareJobSource(options: {
1302
1346
  const imageSet = context.imageSet === undefined ? null : prepareJobImageSet(context.imageSet,
1303
1347
  path => sourceBytes(root.path, path));
1304
1348
  for (const image of imageSet?.imageSet.images ?? []) add(image.path, image.sha256);
1305
- const parts = await prepareParts(root.path, snapshotRoot, context.parts, options.partsEnumerator);
1349
+ const parts = await prepareParts(root.path, snapshotRoot, context.parts, declared, options.partsEnumerator);
1306
1350
  for (const [path, bytes] of parts.bytes) add(path, jobHash(bytes));
1307
1351
  if (wanted.size > maxSourceFiles) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
1308
1352
  let size = 0;