@rig-c/review 3.7.0 → 4.0.1

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 +3 -3
  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 +446 -100
  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 +192 -61
  30. package/src/job-host.ts +23 -4
  31. package/src/job-session.ts +109 -24
  32. package/src/job-source.ts +227 -58
  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 +344 -0
  68. package/web/job-session.ts +611 -1443
  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
package/src/job-front.ts CHANGED
@@ -1,15 +1,19 @@
1
+ import {buildWeb} from './build.ts';
2
+ import {PNG} from 'pngjs';
3
+ import {checkpointEvidenceMetadata, readCheckpointEvidenceBytes} from './job-checkpoint-evidence.ts';
1
4
  /** Disjoint live-job routes. The backend receives the original authenticated Request. */
2
5
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobHostPorts, type JobId, type JobPublicationMode, type JobResult, type JobReviewerBinding } from './job-contract.ts';
3
6
  import { createJobHostPorts, jobBody, jobHash, jobId, jobObject, jobPartsEnumeratorVersion } from './job-api.ts';
4
7
  import { JobSession } from './job-session.ts';
5
- import { assertJobRoot, captureJobRoot, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
8
+ import { assertJobRoot, assertRetainedSnapshotIntact, captureJobRoot, planTextMetadata, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
6
9
  import type { JobWorkerOptions } from './job-worker.ts';
7
- import { JobError, JobStore } from './job-store.ts';
10
+ import { JobError, JobStore, jobCropReferences } from './job-store.ts';
8
11
  import { loadReview, safeFile, packagePath, type ReviewPackage } from './manifest.ts';
9
12
  import { serveReference, assertReviewUnchanged } from './reference.ts';
10
- import { loadPartsView, partsViewJson, servedImage, type PartsViewPackage } from './parts-view.ts';
13
+ import {preparePartsComment} from './parts-comment-crops.ts';
14
+ import { loadPartsView, partsViewJson, partsDifference, servedImage, type PartsViewPackage } from './parts-view.ts';
11
15
  import { destinationDirectory, DestinationDirectoryError } from './destination-directory.ts';
12
- import { dirname, isAbsolute, join, relative, sep } from 'node:path';
16
+ import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
13
17
  import { constants, openSync, closeSync, readSync, fstatSync, lstatSync, statSync, type Stats } from 'node:fs';
14
18
  import { lstat, mkdir, rename, writeFile } from 'node:fs/promises';
15
19
  import { randomUUID } from 'node:crypto';
@@ -22,8 +26,60 @@ const headers = {
22
26
  'Referrer-Policy': 'no-referrer',
23
27
  'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self' blob:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
24
28
  };
25
- function failure(code: string, status: number): Response {
26
- return Response.json({ ok: false, error: { code, message: code } }, { status, headers });
29
+ interface CropFailureDiagnostic {
30
+ field: string;
31
+ expected: string | number[];
32
+ received: string | number[];
33
+ }
34
+ function failure(code: string, status: number, diagnostic?: CropFailureDiagnostic, message = code): Response {
35
+ return Response.json({ ok: false, error: { code, message, ...(diagnostic ? {diagnostic} : {}) } }, { status, headers });
36
+ }
37
+
38
+ /** Explain an existing rejection without returning body text, filesystem paths or PNG bytes. */
39
+ function cropFailureDiagnostic(error: unknown, raw: unknown): CropFailureDiagnostic {
40
+ const message = error instanceof Error ? error.message : '';
41
+ const invariants: Record<string, [string, string]> = {
42
+ 'PARTS_COMMENT_RIG_REGION: rig region must be exact placement plus image region': ['rigRegion', 'exact placement plus imageRegion'],
43
+ 'PARTS_COMMENT_OUT_OF_BOUNDS: region exceeds original image': ['imageRegion', 'inside original image bounds'],
44
+ 'PARTS_COMMENT_OUT_OF_BOUNDS: region exceeds union of issue parts': ['rigRegion', 'inside union of bound parts'],
45
+ 'PARTS_CAMERA_RANGE: native zoom below fit/1 minimum': ['view.camera.zoom', 'at least min(fit, 1)'],
46
+ 'PARTS_CAMERA_RANGE: native scale or camera extent': ['view.camera', 'bounded positive zoom and viewport'],
47
+ 'PARTS_COMMENT_IMAGE_SIZE: original dimensions differ from placement': ['part.image.dimensions', 'equal retained placement dimensions'],
48
+ 'PARTS_COMMENT_CROP_INVALID: bounded content-addressed crop': ['crop', 'bounded content-addressed PNG metadata'],
49
+ 'COMMENT_CROP_INVALID: bounded content-addressed PNG required': ['crop', 'bounded content-addressed PNG'],
50
+ 'COMMENT_CROP_INVALID: expected noninterlaced 8-bit RGB/RGBA': ['crop.png.format', 'noninterlaced 8-bit RGB/RGBA'],
51
+ 'COMMENT_CROP_INVALID: truncated PNG chunk': ['crop.png.chunks', 'complete chunks'],
52
+ 'COMMENT_CROP_INVALID: PNG chunk length': ['crop.png.chunk.length', 'inside PNG byte bounds'],
53
+ 'COMMENT_CROP_INVALID: PNG chunk CRC': ['crop.png.chunk.crc', 'matching CRC'],
54
+ 'COMMENT_CROP_INVALID: static PNG required': ['crop.png.animation', 'static PNG'],
55
+ 'COMMENT_CROP_INVALID: PNG end': ['crop.png.end', 'final empty IEND'],
56
+ 'COMMENT_CROP_INVALID: PNG data/end missing': ['crop.png.data', 'IDAT and IEND present'],
57
+ 'COMMENT_CROP_INVALID: bounded PNG data decode': ['crop.png.data', 'bounded decodable scanlines'],
58
+ 'COMMENT_CROP_INVALID: PNG scanlines': ['crop.png.scanlines', 'exact dimensions and valid filters'],
59
+ 'COMMENT_CROP_PATH: existing crop is not the bound regular PNG': ['crop.storage', 'regular file with matching SHA-256'],
60
+ 'COMMENT_CROP_PATH: regular state directory required': ['crop.storage', 'regular state directory'],
61
+ };
62
+ // Inspect metadata only after the existing validator reports this exact invariant.
63
+ if (message === 'COMMENT_CROP_INVALID: PNG signature, dimensions or SHA-256 differ' &&
64
+ raw && typeof raw === 'object' && 'crop' in raw) {
65
+ const crop = raw.crop as {png?: unknown; sha256?: unknown; width?: unknown; height?: unknown} | null;
66
+ if (crop && typeof crop.png === 'string' && crop.png.length <= 200000 &&
67
+ typeof crop.sha256 === 'string' && /^[a-f0-9]{64}$/.test(crop.sha256)) {
68
+ const bytes = Buffer.from(crop.png.slice('data:image/png;base64,'.length), 'base64');
69
+ const hash = jobHash(bytes);
70
+ if (hash !== crop.sha256) return {field: 'crop.sha256', expected: crop.sha256, received: hash};
71
+ if (bytes.length >= 24 && bytes.subarray(0, 8).toString('hex') === '89504e470d0a1a0a' &&
72
+ typeof crop.width === 'number' && typeof crop.height === 'number' &&
73
+ (crop.width !== bytes.readUInt32BE(16) || crop.height !== bytes.readUInt32BE(20))) {
74
+ return {field: 'crop.dimensions', expected: [crop.width, crop.height],
75
+ received: [bytes.readUInt32BE(16), bytes.readUInt32BE(20)]};
76
+ }
77
+ }
78
+ return {field: 'crop.png.signature', expected: 'PNG signature and IHDR', received: 'invalid'};
79
+ }
80
+ const invariant = Object.hasOwn(invariants, message) ? invariants[message] : undefined;
81
+ return invariant ? {field: invariant[0], expected: invariant[1], received: 'rejected by existing validator'} :
82
+ {field: 'partsComment.prepare', expected: 'valid source-bound crop and writable evidence state', received: 'unclassified rejection'};
27
83
  }
28
84
  const errorStatus: Partial<Record<JobErrorCode, number>> = {
29
85
  JOB_REQUEST_INVALID: 400,
@@ -44,8 +100,7 @@ function result<Value>(value: JobResult<Value>): Response {
44
100
  export function createJobFront(options: {
45
101
  origin: string;
46
102
  ports: JobHostPorts;
47
- hubIncarnation?: string;
48
- resource: (name: 'index.html' | 'job.js' | 'styles.css') => Promise<BodyInit>;
103
+ resource: (name: 'index.html' | 'main.js' | 'styles.css') => Promise<BodyInit>;
49
104
  publication?: (jobId: string, publicationId: string, instanceKey: string, path: string, request: Request) => Promise<Response>;
50
105
  }) {
51
106
  const origin = new URL(options.origin);
@@ -83,11 +138,15 @@ export function createJobFront(options: {
83
138
  return result(await options.ports.ackDisplayed(jobId, request));
84
139
  return result(await options.ports.commitUIAct(jobId, request));
85
140
  }
86
- if (!read)
141
+ const partsCrop = request.method === 'POST' &&
142
+ /^publications\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\/instances\/[a-f0-9]{64}\/api\/stage-parts\/comment$/.test(route);
143
+ if (!read && !partsCrop)
87
144
  return failure('JOB_REQUEST_INVALID', 405);
145
+ if (partsCrop && sentOrigin !== origin.origin) return failure('JOB_SAME_ORIGIN_REQUIRED', 403);
88
146
  const liveness = await options.ports.jobLiveness(jobId);
89
147
  if (!liveness.ok)
90
148
  return result(liveness);
149
+ if (/^comment-crops\/[a-f0-9]{64}\.png$/.test(route) && request.method === 'GET') return options.ports.handleJobApi(request);
91
150
  if (route === 'events' && request.method === 'GET') {
92
151
  const keys = [...url.searchParams.keys()];
93
152
  if (keys.length > 1 || keys.some(key => key !== 'after'))
@@ -112,7 +171,7 @@ export function createJobFront(options: {
112
171
  controller.close();
113
172
  }
114
173
  else {
115
- controller.enqueue(encoder.encode(JSON.stringify(next.value) + '\n'));
174
+ controller.enqueue(encoder.encode(jobCropReferences(next.value) + '\n'));
116
175
  if (next.value.type === 'closed') {
117
176
  stop();
118
177
  controller.close();
@@ -129,14 +188,7 @@ export function createJobFront(options: {
129
188
  });
130
189
  return new Response(body, { headers: { ...headers, 'Content-Type': 'application/x-ndjson' } });
131
190
  }
132
- const embedded = route === '' && url.searchParams.has('hub');
133
- if (embedded) {
134
- if (!options.hubIncarnation || url.searchParams.get('hub') !== options.hubIncarnation ||
135
- [...url.searchParams.keys()].some(key => !['hub', 'lang'].includes(key) || url.searchParams.getAll(key).length !== 1) ||
136
- url.searchParams.has('lang') && !['en', 'ko'].includes(url.searchParams.get('lang')!)) {
137
- return failure('JOB_REQUEST_INVALID', 400);
138
- }
139
- } else if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search))) {
191
+ if (url.search && !(route === '' && ['?lang=en', '?lang=ko'].includes(url.search))) {
140
192
  return failure('JOB_REQUEST_INVALID', 400);
141
193
  }
142
194
  const instance = /^publications\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/instances\/([a-f0-9]{64})\/(.*)$/.exec(route);
@@ -146,14 +198,12 @@ export function createJobFront(options: {
146
198
  const publication = /^publications\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(route);
147
199
  if (publication)
148
200
  return result(await options.ports.readPublication(jobId, publication[1]!));
149
- const name = route === '' ? 'index.html' : route === 'job.js' ? 'job.js' : route === 'styles.css' ? 'styles.css' : null;
201
+ const name = route === '' ? 'index.html' : route === 'main.js' ? 'main.js' : route === 'styles.css' ? 'styles.css' : null;
150
202
  if (!name)
151
203
  return failure('JOB_REQUEST_INVALID', 404);
152
- const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'job.js' ? 'text/javascript' : 'text/css';
204
+ const type = name === 'index.html' ? 'text/html; charset=utf-8' : name === 'main.js' ? 'text/javascript' : 'text/css';
153
205
  return new Response(request.method === 'HEAD' ? null : await options.resource(name), {
154
- headers: { ...headers, 'Content-Type': type, ...(embedded ? {
155
- 'Content-Security-Policy': headers['Content-Security-Policy'].replace("frame-ancestors 'none'", "frame-ancestors 'self'"),
156
- } : {}) },
206
+ headers: { ...headers, 'Content-Type': type },
157
207
  });
158
208
  }
159
209
  return {
@@ -165,31 +215,16 @@ export function createJobFront(options: {
165
215
  /** Installed files are fixed here. A job request never selects a local pathname. */
166
216
  export function jobWindowResources() {
167
217
  let bundle: Promise<Blob> | null = null;
168
- return async (name: 'index.html' | 'job.js' | 'styles.css'): Promise<BodyInit> => {
169
- if (name === 'index.html') {
170
- return '<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
171
- '<title>rig-review</title><link rel="stylesheet" href="styles.css"></head>' +
172
- '<body data-job-window><script type="module" src="job.js"></script></body></html>';
173
- }
174
- if (name === 'styles.css')
175
- return Bun.file(new URL('../web/styles.css', import.meta.url));
176
- bundle ??= buildJobWindow();
218
+ return async (name: 'index.html' | 'main.js' | 'styles.css'): Promise<BodyInit> => {
219
+ if (name === 'index.html') return await Bun.file(new URL('../web/index.html', import.meta.url)).text();
220
+ if (name === 'styles.css')return await Bun.file(new URL('../web/styles.css', import.meta.url)).text();
221
+ bundle ??= buildWeb();
177
222
  return bundle;
178
223
  };
179
224
  }
180
- export async function buildJobWindow(): Promise<Blob> {
181
- const source = new URL('../web/job-session.ts', import.meta.url).pathname;
182
- const result = await Bun.build({ entrypoints: [source], target: 'browser', format: 'esm', minify: false });
183
- if (!result.success)
184
- throw new Error(result.logs.map(log => log.message).join('\n'));
185
- const output = result.outputs.find(output => output.path.endsWith('.js'));
186
- if (!output)
187
- throw new Error('JOB_WINDOW_BUNDLE_MISSING');
188
- return output;
189
- }
190
225
 
191
226
  interface RetainedView {
192
- review: ReviewPackage;
227
+ review: ReviewPackage | null;
193
228
  parts: PartsViewPackage | null;
194
229
  }
195
230
 
@@ -199,21 +234,70 @@ export function retainedPublicationRoutes(session: JobSession) {
199
234
  return async (jobId: string, publicationId: string, key: string, path: string, request: Request): Promise<Response> => {
200
235
  if (jobId !== session.jobId) return failure('JOB_UNKNOWN', 404);
201
236
  try {
237
+ const crop = path === 'api/stage-parts/comment' && request.method === 'POST';
238
+ if (crop) session.authorize('ui', request.headers.get('X-Review-Capability'));
202
239
  return await session.readPublicationResponse(publicationId, async retained => {
203
240
  const display = session.displayPublication(publicationId);
241
+ // Retain history, but expose images only for this publication's declared questions.
242
+ const questions = retained.questions.map(question => ({...question,
243
+ images: retained.subjects.some(subject => subject.kind === 'interview-picks' &&
244
+ subject.setId === question.set.id && subject.questionId === question.set.question)
245
+ ? question.images : [],
246
+ }));
204
247
  if (key !== display.publication.instanceKey) return failure('JOB_DISPLAY_MISMATCH', 409);
205
- const json = (value: unknown) => new Response(request.method === 'HEAD' ? null : JSON.stringify(value), {
206
- headers: {...headers, 'Content-Type': 'application/json'},
207
- });
248
+ if (crop && session.status().publication?.publicationId !== publicationId)
249
+ return failure('JOB_ACT_SOURCE_STALE', 409);
250
+ const json = (value: Record<string, unknown>) => {
251
+ const payload = path === 'api/review' ? planTextMetadata(retained, value) : value;
252
+ const body = JSON.stringify(payload);
253
+ return new Response(request.method === 'HEAD' ? null : body, {
254
+ headers: {...headers, 'Content-Type': 'application/json'},
255
+ });
256
+ };
208
257
  const sealedFile = async (relativePath: string) => {
209
258
  const seal = retained.seals.find(file => file.path === relativePath);
210
259
  if (!seal) return failure('JOB_SOURCE_UNRETAINABLE', 404);
211
260
  const file = await safeFile(retained.snapshotRoot, relativePath);
212
261
  return serveReference(request, file, seal.sha256, headers);
213
262
  };
263
+ const evidenceRoute = /^api\/checkpoint-evidence\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(table|tiles\/(0|[1-9]\d*))$/.exec(path);
264
+ if (evidenceRoute) {
265
+ const packet = retained.source.checkpointEvidence?.find(item => item.checkpointId === evidenceRoute[1]);
266
+ const isTable = evidenceRoute[2] === 'table';
267
+ const member = isTable ? packet?.table : packet?.tiles[Number(evidenceRoute[3])];
268
+ if (!member) return failure('JOB_SOURCE_UNRETAINABLE', 404);
269
+ readCheckpointEvidenceBytes(retained.snapshotRoot, member, isTable ? 256 * 1024 : 8 * 1024 * 1024);
270
+ return await sealedFile(member.path);
271
+ }
214
272
  if (isRetainedRecordSource(retained)) {
273
+ // hasParts is projected only after validating the option's sealed draft closure.
274
+ const question = retained.questions.find(question => question.hasParts);
275
+ if (question && (path === 'api/stage-parts' || /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.test(path))) {
276
+ let pending = views.get(publicationId);
277
+ if (!pending) {
278
+ pending = (async () => {
279
+ const context = (question.set as unknown as {context:{parts:{path:string;files:{path:string;sha256:string}[]}}}).context;
280
+ const root = join(retained.snapshotRoot, context.parts.path);
281
+ const parts = await loadPartsView(root);
282
+ for (const file of [...parts.files, ...parts.flagFiles]) {
283
+ const path = relative(retained.snapshotRoot, file.abs).split('\\').join('/');
284
+ if (!context.parts.files.some(bound => bound.path === path && bound.sha256 === file.sha256)) throw new JobError('JOB_SOURCE_UNRETAINABLE');
285
+ }
286
+ return {review:null, parts};
287
+ })();
288
+ views.set(publicationId, pending);
289
+ }
290
+ const {parts} = await pending;
291
+ if (!parts) throw new JobError('JOB_SOURCE_UNRETAINABLE');
292
+ if (path === 'api/stage-parts') return json({...partsViewJson(parts, {verdict:null,stale:null}),
293
+ sourceHash:retained.source.sourceHash,inspectionSourceHash:retained.source.sourceHash,readOnly:true});
294
+ const image = /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.exec(path)!;
295
+ const file = servedImage(parts, image[1] as 'image'|'page', Number(image[2]));
296
+ return file ? await sealedFile(relative(retained.snapshotRoot,file).split('\\').join('/')) : failure('JOB_SOURCE_UNRETAINABLE',404);
297
+ }
215
298
  if (path === 'api/review') {
216
299
  return json({
300
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
217
301
  recordSource: retained.source,
218
302
  sourceHash: retained.source.sourceHash,
219
303
  assetsBase: display.routes.assetsBase,
@@ -230,7 +314,7 @@ export function retainedPublicationRoutes(session: JobSession) {
230
314
  });
231
315
  }
232
316
  if (path === 'api/interview') {
233
- return json({questions: retained.questions.map(question => ({...question,
317
+ return json({questions: questions.map(question => ({...question,
234
318
  images: question.images.map((image, index) => ({name: image.name,
235
319
  url: `/api/interview/image/${question.ref.sha256}/${index}`})),
236
320
  }))});
@@ -247,9 +331,21 @@ export function retainedPublicationRoutes(session: JobSession) {
247
331
  if (!pending) {
248
332
  pending = (async () => {
249
333
  const review = await loadReview(retained.manifestPath);
250
- const parts = retained.source.parts
251
- ? await loadPartsView(dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)))
252
- : null;
334
+ const partsRoot = retained.source.parts
335
+ ? dirname(join(retained.snapshotRoot, retained.source.parts.manifest.path)) : null;
336
+ // Forward only retained producer files. Discovery never reads the live draft.
337
+ const retainedFile = (path: string) => retained.seals.some(file =>
338
+ file.path === relative(retained.snapshotRoot, path).split('\\').join('/')) ? path : undefined;
339
+ const rigRoot = review.handoff?.rig ?? partsRoot;
340
+ const parts = partsRoot ? await loadPartsView(partsRoot, {
341
+ rig: rigRoot ? retainedFile(join(rigRoot, 'rig.json')) : undefined,
342
+ meshReport: rigRoot ? retainedFile(join(rigRoot, 'mesh_report.json')) : undefined,
343
+ // The original SVG stays a sealed Review reference; Parts' optional
344
+ // native-pixel comparison accepts PNG bytes, not vector artwork.
345
+ painting: review.handoff?.source && extname(review.handoff.source).toLowerCase() !== '.svg'
346
+ ? retainedFile(review.handoff.source) : undefined,
347
+ paintingRoot: retained.snapshotRoot,
348
+ }) : null;
253
349
  if (parts) {
254
350
  if (parts.items.length !== retained.partIds.length || parts.items.some(item => !retained.partIds.includes(item.name))) {
255
351
  throw new JobError('JOB_SOURCE_MISMATCH');
@@ -266,15 +362,21 @@ export function retainedPublicationRoutes(session: JobSession) {
266
362
  views.set(publicationId, pending);
267
363
  }
268
364
  const {review, parts} = await pending;
365
+ if (!review) throw new JobError('JOB_SOURCE_MISMATCH');
269
366
  await assertReviewUnchanged(review);
367
+ if (retained.checkpointEvidencePackageHash !== undefined && retained.checkpointEvidencePackageHash !== review.sourceHash) {
368
+ throw new JobError('JOB_SOURCE_MISMATCH');
369
+ }
270
370
  if (path === 'api/review') {
271
371
  return json({
372
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
272
373
  manifest: review.manifest,
273
374
  sourceHash: retained.source.sourceHash,
274
375
  reviewedSource: review.reviewedSource,
275
376
  initialAnimation: null,
276
377
  setsHash: review.setsHash,
277
- direction: review.direction,
378
+ direction: review.direction && {...review.direction, ...(retained.source.selector?.kind==='post'?{postVersion:retained.source.selector.version}:{})},
379
+ scene: review.scene,
278
380
  referenceHashes: review.referenceHashes,
279
381
  sourcePainting: review.sourcePainting && {...review.sourcePainting, url: '/review-painting'},
280
382
  feedbackCatalog: review.feedbackCatalog,
@@ -289,7 +391,7 @@ export function retainedPublicationRoutes(session: JobSession) {
289
391
  if (path === 'api/interview') {
290
392
  const interview = retained.interview !== undefined ? retained.interview : display.publication.interview;
291
393
  return json({
292
- questions: retained.questions.map(question => ({...question,
394
+ questions: questions.map(question => ({...question,
293
395
  images: question.images.map((image, index) => ({name: image.name,
294
396
  url: `/api/interview/image/${question.ref.sha256}/${index}`})),
295
397
  })),
@@ -302,17 +404,41 @@ export function retainedPublicationRoutes(session: JobSession) {
302
404
  if (!image) return failure('JOB_SOURCE_UNRETAINABLE', 404);
303
405
  return await sealedFile(image.ref.path);
304
406
  }
305
- const imageSetImage = /^api\/image-set\/(0|[1-9]\d*)$/.exec(path);
306
- if (imageSetImage && retained.source.subject === 'image-set') {
307
- const image = retained.source.imageSet.images[Number(imageSetImage[1])];
308
- if (!image) return failure('JOB_SOURCE_UNRETAINABLE', 404);
309
- return await sealedFile(image.path);
407
+ if (crop) {
408
+ if (!parts) return failure('JOB_SOURCE_UNRETAINABLE', 409);
409
+ if (request.headers.get('origin') !== new URL(request.url).origin)
410
+ return failure('JOB_SAME_ORIGIN_REQUIRED', 403);
411
+ const raw = await jobBody(request);
412
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw) ||
413
+ (raw as {sourceHash?: unknown}).sourceHash !== retained.source.sourceHash)
414
+ return failure('JOB_ACT_SOURCE_STALE', 409);
415
+ // Preserve the exact displayed job identity through native evidence validation.
416
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals);
417
+ let comment;
418
+ try {
419
+ comment = await preparePartsComment(parts, raw, false, {sourceHash: retained.source.sourceHash});
420
+ } catch (error) {
421
+ if (error instanceof JobError ||
422
+ error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')) throw error;
423
+ return failure('JOB_SOURCE_MISMATCH', 409, cropFailureDiagnostic(error, raw));
424
+ }
425
+ assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals);
426
+ if (session.status().publication?.publicationId !== publicationId)
427
+ return failure('JOB_ACT_SOURCE_STALE', 409);
428
+ return json({comment});
310
429
  }
311
430
  if (path === 'api/stage-parts') {
312
431
  if (!parts) return failure('JOB_SOURCE_UNRETAINABLE', 409);
313
432
  return json({...partsViewJson(parts, {verdict: null, stale: null}), sourceHash: retained.source.sourceHash,
314
433
  inspectionSourceHash: retained.source.sourceHash, readOnly: true});
315
434
  }
435
+ const difference=/^api\/stage-parts\/difference\/(0|[1-9]\d*)$/.exec(path);
436
+ if(difference&&parts){
437
+ const url=new URL(request.url),threshold=url.searchParams.get('threshold'),footprints=url.searchParams.get('footprints');
438
+ if(!threshold||!/^\d{1,3}$/.test(threshold)||!['true','false'].includes(footprints??''))return failure('JOB_REQUEST_INVALID',400);
439
+ 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);
440
+ 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)}});
441
+ }
316
442
  const part = /^api\/stage-parts\/(image|page)\/(0|[1-9]\d*)$/.exec(path);
317
443
  if (part && parts) {
318
444
  const file = servedImage(parts, part[1] as 'image' | 'page', Number(part[2]));
@@ -330,7 +456,12 @@ export function retainedPublicationRoutes(session: JobSession) {
330
456
  return failure('JOB_REQUEST_INVALID', 404);
331
457
  });
332
458
  } catch (error) {
333
- return failure(error instanceof JobError ? error.code : 'JOB_SOURCE_MISMATCH', 409);
459
+ const code = error instanceof JobError ? error.code :
460
+ error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')
461
+ ? 'PARTS_COMMENT_STALE_SOURCE' : 'JOB_SOURCE_MISMATCH';
462
+ const message = error instanceof JobError && /^(CHECKPOINT_EVIDENCE|PLAN_TEXT)_[A-Z_]+$/.test(error.message)
463
+ ? error.message : undefined;
464
+ return failure(code, errorStatus[code as JobErrorCode] ?? 409, undefined, message);
334
465
  }
335
466
  };
336
467
  }
@@ -686,8 +817,8 @@ function attachFailure(error: unknown): Response {
686
817
 
687
818
  /** One live job request context. Its caller publishes it only after descriptor installation. */
688
819
  export function createJobRequestContext(session: JobSession, startup: JobHostOptions, origin: string,
689
- identity: ReturnType<typeof jobHostIdentity>, resource = jobWindowResources(), hubIncarnation?: string,
690
- listenerIncarnation: string = hubIncarnation ?? randomUUID(), accepting: () => boolean = () => true) {
820
+ identity: ReturnType<typeof jobHostIdentity>, resource = jobWindowResources(),
821
+ listenerIncarnation: string = randomUUID(), accepting: () => boolean = () => true) {
691
822
  const ports = createJobHostPorts(session, new URL(origin).origin);
692
823
  // This legacy GET projection and its property order are deliberately unchanged.
693
824
  const record: JobHostRecord = {
@@ -707,7 +838,7 @@ export function createJobRequestContext(session: JobSession, startup: JobHostOpt
707
838
  fingerprint: startup.fingerprint,
708
839
  pid: process.pid,
709
840
  };
710
- const front = createJobFront({origin, ports, resource, hubIncarnation, publication: retainedPublicationRoutes(session)});
841
+ const front = createJobFront({origin, ports, resource, publication: retainedPublicationRoutes(session)});
711
842
  let requests = 0, stopped = false, published = false;
712
843
  let captured: ObservedFiles;
713
844
  let descriptorBytes: string;
package/src/job-host.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  /** Stable installed managed owner host and semantic A/B contract. See docs/STABILITY.md. */
2
2
  export {startJobHost} from './job-front.ts';
3
- export {startJobHub} from './job-hub.ts';
4
- export type {JobHubOptions, JobHubJobOptions, JobHubJob, JobOwnerHub} from './job-hub.ts';
5
3
  export type {
6
4
  JobHostOptions,
7
5
  JobOwnerHost,
@@ -23,6 +21,21 @@ export type {
23
21
  JobRootIdentity,
24
22
  } from './job-source.ts';
25
23
  export {parseRecordAct} from './job-api.ts';
24
+ export {parseCommentsAct, parseContextCommentsAct} from './job-api.ts';
25
+ export {projectComments} from './stage-comment.ts';
26
+ export {parseCommentsSession} from './session.ts';
27
+ export {parseCommentsCompareSession} from './compare-session.ts';
28
+ export {parseCommentsPartsVerdict} from './parts-view.ts';
29
+ export {projectSelectedCommentsFeedback} from './feedback-export.ts';
30
+ export {
31
+ JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
32
+ REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA, PARTS_COMMENTS_VERDICT_SCHEMA,
33
+ } from './job-contract.ts';
34
+ export type {
35
+ JobComment, JobCommentAnchor, JobCommentFeedbackAnchor, JobCommentPartsAnchor, JobCommentImageAnchor,
36
+ JobCommentsAct, JobCommentsActValues, ReviewCommentsSession,
37
+ JobCommentContext, JobContextComment, JobContextCommentsAct, CompareCommentsSession, PartsCommentsVerdict,
38
+ } from './job-contract.ts';
26
39
  export {prepareJobRecordAct} from './job-act.ts';
27
40
  export {
28
41
  JOB_CAPABILITIES,
@@ -81,6 +94,11 @@ export type {
81
94
  JobActV3,
82
95
  JobLegacyAct,
83
96
  JobRigReviewAct,
97
+ JobPartsVerdictAct,
98
+ JobLegacyPartsVerdictValue,
99
+ PartsVerdictValue,
100
+ JobPanelComposition,
101
+ PanelComponent,
84
102
  JobRigStill,
85
103
  JobRigCapture,
86
104
  JobSubject,
@@ -201,5 +219,6 @@ export type {
201
219
  UISubmissionV3,
202
220
  } from './job-contract.ts';
203
221
 
204
- export {assertJobImageSetCapability} from './job-image-set.ts';
205
- export type {JobCapabilities, JobImageSetInput, JobImageSet, JobImageSourceBinding, JobModelSourceBinding, JobModelReviewValue, JobImageReviewValue} from './job-contract.ts';
222
+ export type {JobCapabilities, JobModelSourceBinding, JobModelReviewValue} from './job-contract.ts';
223
+
224
+ export type {JobCheckpointEvidence, JobCheckpointTable} from './job-contract.ts';