rig-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-source.ts CHANGED
@@ -1,15 +1,17 @@
1
+ import {resolvePartsPaintingInRig} from './parts-view.ts';
2
+ import {checkpointEvidenceFields, checkpointEvidenceMetadata} from './job-checkpoint-evidence.ts';
1
3
  import { randomUUID } from 'node:crypto';
2
4
  import { type Dirent, lstatSync, readdirSync, realpathSync, type Stats } from 'node:fs';
3
5
  import { mkdir, open, rm, writeFile } from 'node:fs/promises';
4
6
  import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
5
7
  import { PNG } from 'pngjs';
6
8
  import {
7
- JOB_API_V3_SCHEMA,
9
+ JOB_API_V3_SCHEMA, JOB_PLAN_TEXT_FIELDS, JOB_PLAN_TEXT_SCHEMA,
8
10
  JOB_PARTS_ENUMERATOR_RANGE,
9
11
  } from './job-contract.ts';
10
12
  import type {
11
- JobFileIdentity, JobImageSetInput, JobInterviewDiagnostics, JobInterviewRecord, JobModelSourceBinding, JobPartsEnumerator, JobPartsFileReference, JobPartsIdentity, JobPlanIdentity, JobPublishRequest,
12
- JobSelector, JobSourceBinding, JobSubject,
13
+ JobCheckpointEvidence, JobFileIdentity, JobInterviewDiagnostics, JobInterviewRecord, JobModelSourceBinding, JobPartsEnumerator, JobPartsFileReference, JobPartsIdentity, JobPlanIdentity, JobPublishRequest,
14
+ JobSelector, JobSourceBinding, JobSubject, JobPlanTextProjection, JobPlanTextStep,
13
15
  OptionContext, OptionSource, PackageResultV3, PlanContext, PlanSource, ProjectRecord, PublishRequestV3,
14
16
  RecordFreeze, RecordOptionResult, RecordPlanResult, RecordPublicationReader, RecordPublishedContext,
15
17
  RecordReaderInput, RecordResult, RecordSource, RecordSubject,
@@ -41,7 +43,6 @@ import {
41
43
  validateRecordAskSubject,
42
44
  } from './job-api.ts';
43
45
  import { JobError, type JobSnapshotOwner } from './job-store.ts';
44
- import { prepareJobImageSet } from './job-image-set.ts';
45
46
 
46
47
  export interface JobRootIdentity {
47
48
  readonly path: string;
@@ -55,7 +56,7 @@ export interface JobRootIdentity {
55
56
  * referenced-image enumeration belongs to the public Parts #1163 surface.
56
57
  */
57
58
  export interface JobPublishedContext {
58
- readonly imageSet?: JobImageSetInput;
59
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
59
60
  readonly selector: JobSelector | null;
60
61
  readonly plan: JobPlanIdentity | null;
61
62
  readonly parts: JobPartsIdentity | null;
@@ -71,6 +72,8 @@ export type JobPublicationReader = (input: {
71
72
  }) => Promise<JobPublishedContext>;
72
73
 
73
74
  export interface JobRetainedSource {
75
+ /** Private base preimage for evidence-aware durable validation, absent historically. */
76
+ readonly checkpointEvidencePackageHash?: string;
74
77
  readonly root: JobRootIdentity;
75
78
  readonly record: JobFileIdentity | null;
76
79
  readonly seals: readonly JobFileIdentity[];
@@ -230,30 +233,63 @@ function referenceRow(raw: unknown, row: number, hashed: boolean): JobPartsFileR
230
233
  return {path, role, ...(hashed ? {sha256: item.sha256 as string} : {})};
231
234
  }
232
235
 
236
+ /** Reuse the official-reference PNG admission and decoded-size bound for generic sidecar operands. */
237
+ function assertPartsReferencePng(data: Buffer, detail: string): void {
238
+ if (data.length < 33 || !data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
239
+ data.readUInt32BE(8) !== 13 || data.toString('ascii', 12, 16) !== 'IHDR') {
240
+ throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
241
+ }
242
+ const width = data.readUInt32BE(16), height = data.readUInt32BE(20);
243
+ if (!width || !height) throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
244
+ if (width > Math.floor(maxFileBytes / 4 / height)) {
245
+ throw new JobError('JOB_SOURCE_UNRETAINABLE', `PARTS_REFERENCE_LIMIT ${detail}`);
246
+ }
247
+ try { PNG.sync.read(data); }
248
+ catch { throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`); }
249
+ }
250
+
251
+ function partsIdentityHeader(value: unknown): {raw: Record<string, unknown>; version: string} {
252
+ const raw = jobObject(value, ['enumeratorVersion', 'manifest', 'images']);
253
+ return {raw, version: jobPartsEnumeratorVersion(raw.enumeratorVersion)};
254
+ }
255
+
256
+ function partsManifest(value: unknown): JobFileIdentity {
257
+ try {
258
+ const raw = jobObject(value, ['path', 'sha256']);
259
+ const path = jobPath(raw.path);
260
+ if (posix.basename(path) !== 'parts.json') throw new Error('Manifest directory API');
261
+ return {path, sha256: jobSha(raw.sha256)};
262
+ } catch { throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_PATH_REFUSED manifest'); }
263
+ }
264
+
265
+ function partsReferenceList(value: unknown): unknown[] {
266
+ if (!Array.isArray(value) || value.length > maxSourceFiles) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
267
+ return value;
268
+ }
269
+
270
+ /** Pure declared identity decoder; official enumeration and native bytes remain preparation checks. */
271
+ export function parseJobPartsIdentity(value: unknown): JobPartsIdentity {
272
+ const {raw, version} = partsIdentityHeader(value);
273
+ const manifest = partsManifest(raw.manifest);
274
+ const images = partsReferenceList(raw.images).map((row, index) => referenceRow(row, index, true));
275
+ return {enumeratorVersion: version, manifest, images: images as JobPartsIdentity['images']};
276
+ }
277
+
233
278
  /** Membership, order and duplicate semantics belong solely to the trusted public
234
279
  * enumerator. Review compares its exact array and validates byte boundaries.
235
280
  */
236
281
  async function prepareParts(root: string, snapshotRoot: string, claimed: JobPartsIdentity | null,
237
- enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
282
+ declared: readonly JobFileIdentity[], enumerator?: JobPartsEnumerator): Promise<{identity: JobPartsIdentity | null; bytes: Map<string, Buffer>}> {
238
283
  const bytes = new Map<string, Buffer>();
239
284
  if (claimed === null) return {identity: null, bytes};
240
285
  if (!enumerator) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_ENUMERATOR_UNAVAILABLE');
241
- jobObject(claimed, ['enumeratorVersion', 'manifest', 'images']);
242
- const version = jobPartsEnumeratorVersion(claimed.enumeratorVersion);
286
+ const {version} = partsIdentityHeader(claimed);
243
287
  if (version !== jobPartsEnumeratorVersion(enumerator.version)) {
244
288
  throw new JobError('JOB_SOURCE_UNRETAINABLE',
245
289
  `PARTS_ENUMERATOR_VERSION_MISMATCH range="${JOB_PARTS_ENUMERATOR_RANGE}" received="${version}" installed="${enumerator.version}"`);
246
290
  }
247
- let manifestPath: string;
248
- try {
249
- jobObject(claimed.manifest, ['path', 'sha256']);
250
- manifestPath = jobPath(claimed.manifest.path);
251
- if (posix.basename(manifestPath) !== 'parts.json') throw new Error('Manifest directory API');
252
- jobSha(claimed.manifest.sha256);
253
- } catch { throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_PATH_REFUSED manifest'); }
254
- if (!Array.isArray(claimed.images) || claimed.images.length > maxSourceFiles) {
255
- throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
256
- }
291
+ const {path: manifestPath} = partsManifest(claimed.manifest);
292
+ const claimedImages = partsReferenceList(claimed.images);
257
293
  let manifestBytes: Buffer;
258
294
  try { manifestBytes = sourceBytes(root, manifestPath); }
259
295
  catch (error) {
@@ -278,11 +314,8 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
278
314
  throw new JobError('JOB_SOURCE_MISMATCH', 'PARTS_ENUMERATION_REFUSED' + rule);
279
315
  }
280
316
  } finally { await rm(enumerationRoot, {recursive: true, force: true}); }
281
- if (!Array.isArray(references) || references.length > maxSourceFiles) {
282
- throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
283
- }
284
- const official = references.map((raw, row) => referenceRow(raw, row, false));
285
- const supplied = claimed.images.map((raw, row) => referenceRow(raw, row, true));
317
+ const official = partsReferenceList(references).map((raw, row) => referenceRow(raw, row, false));
318
+ const supplied = claimedImages.map((raw, row) => referenceRow(raw, row, true));
286
319
  const difference = official.findIndex((row, i) => row.path !== supplied[i]?.path || row.role !== supplied[i]?.role);
287
320
  if (difference !== -1 || official.length !== supplied.length) {
288
321
  throw new JobError('JOB_SOURCE_MISMATCH',
@@ -315,17 +348,7 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
315
348
  }
316
349
  }
317
350
  if (!decoded.has(path)) {
318
- if (data.length < 33 || !data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
319
- data.readUInt32BE(8) !== 13 || data.toString('ascii', 12, 16) !== 'IHDR') {
320
- throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
321
- }
322
- const width = data.readUInt32BE(16), height = data.readUInt32BE(20);
323
- if (!width || !height) throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`);
324
- if (width > Math.floor(maxFileBytes / 4 / height)) {
325
- throw new JobError('JOB_SOURCE_UNRETAINABLE', `PARTS_REFERENCE_LIMIT ${detail}`);
326
- }
327
- try { PNG.sync.read(data); }
328
- catch { throw new JobError('JOB_SOURCE_MISMATCH', `PARTS_REFERENCE_PNG_INVALID ${detail}`); }
351
+ assertPartsReferencePng(data, detail);
329
352
  bytes.set(path, data);
330
353
  decoded.add(path);
331
354
  }
@@ -335,6 +358,29 @@ async function prepareParts(root: string, snapshotRoot: string, claimed: JobPart
335
358
  }
336
359
  images.push({path: reference.path, role: reference.role, sha256});
337
360
  }
361
+ // Inline declarations retain their historical admission behavior; fallback is never a rescue.
362
+ if (!Object.hasOwn(JSON.parse(manifestBytes.toString('utf8')), 'painting_in_rig')) {
363
+ try {
364
+ const resolved = await resolvePartsPaintingInRig(dirname(join(root, manifestPath)), manifestBytes,
365
+ async (absolute, kind) => {
366
+ const data = sourceBytes(root, rootRelative(root, absolute));
367
+ if (kind === 'painting') assertPartsReferencePng(data, 'painting_in_rig');
368
+ return data;
369
+ });
370
+ if (resolved.sidecar) for (const file of resolved.files) {
371
+ const path = rootRelative(root, file.declaredPath ?? file.abs);
372
+ if (!declared.some(row => row.path === path && row.sha256 === file.sha256)) {
373
+ throw new JobError('JOB_SOURCE_MISMATCH', 'PARTS_DIFFERENCE_PROVENANCE: sidecar and painting require generic file identities');
374
+ }
375
+ const data = sourceBytes(root, path);
376
+ if (jobHash(data) !== file.sha256) throw new JobError('JOB_SOURCE_MISMATCH');
377
+ bytes.set(path, data);
378
+ }
379
+ } catch (error) {
380
+ if (error instanceof JobError) throw error;
381
+ throw new JobError('JOB_SOURCE_MISMATCH', error instanceof Error ? error.message : 'PARTS_DIFFERENCE_PROVENANCE');
382
+ }
383
+ }
338
384
  return {identity: {enumeratorVersion: version, manifest: {path: manifestPath, sha256: jobHash(manifestBytes)}, images}, bytes};
339
385
  }
340
386
 
@@ -651,7 +697,7 @@ async function readRecordPublishedPhase(
651
697
  return parseRecordPublishedContext(raw, input.result, input.record);
652
698
  }
653
699
 
654
- function readProjectRecordBytes(root: string, record: ProjectRecord): {
700
+ function readProjectRecordBytes(root: string, record: ProjectRecord, allowLegacySchema = false): {
655
701
  readonly bytes: Buffer;
656
702
  readonly project: Record<string, unknown>;
657
703
  } {
@@ -659,15 +705,15 @@ function readProjectRecordBytes(root: string, record: ProjectRecord): {
659
705
  try {
660
706
  stat = lstatSync(join(root, record.path));
661
707
  } catch {
662
- throw new JobError('JOB_RECORD_MOVED');
708
+ throw new JobError(allowLegacySchema ? 'JOB_SOURCE_UNRETAINABLE' : 'JOB_RECORD_MOVED');
663
709
  }
664
- if (!stat.isFile()) throw new JobError('JOB_RECORD_MOVED');
710
+ if (!stat.isFile()) throw new JobError(allowLegacySchema ? 'JOB_SOURCE_UNRETAINABLE' : 'JOB_RECORD_MOVED');
665
711
  if (stat.size > maxProjectBytes) throw new JobError('JOB_SOURCE_UNRETAINABLE');
666
712
  let bytes: Buffer;
667
713
  try {
668
714
  bytes = sourceBytes(root, record.path);
669
715
  } catch {
670
- throw new JobError('JOB_RECORD_MOVED');
716
+ throw new JobError(allowLegacySchema ? 'JOB_SOURCE_UNRETAINABLE' : 'JOB_RECORD_MOVED');
671
717
  }
672
718
  if (jobHash(bytes) !== record.sha256) throw new JobError('JOB_RECORD_MOVED');
673
719
  let project: Record<string, unknown>;
@@ -676,7 +722,7 @@ function readProjectRecordBytes(root: string, record: ProjectRecord): {
676
722
  } catch {
677
723
  throw new JobError('JOB_RECORD_INCOMPLETE');
678
724
  }
679
- if (project.schema !== 'rig-create/project@0') throw new JobError('JOB_RECORD_INCOMPLETE');
725
+ if (!allowLegacySchema && project.schema !== 'rig-create/project@0') throw new JobError('JOB_RECORD_INCOMPLETE');
680
726
  return { bytes, project };
681
727
  }
682
728
 
@@ -708,6 +754,83 @@ function readClosureFileBytes(root: string, file: JobFileIdentity): Buffer {
708
754
  return bytes;
709
755
  }
710
756
 
757
+ /** Delivery-only projection through the existing retained record reader. */
758
+ export function projectRetainedPlanText(retained: JobRetainedSourceV3): JobPlanTextProjection | undefined {
759
+ const {source, record} = retained;
760
+ const plan = source.plan;
761
+ if (!plan) return undefined;
762
+ let identity: {path: 'project.json'; sha256: string} | null = null;
763
+ const unavailable = (reason: Extract<JobPlanTextProjection, {status:'unavailable'}>['reason']): JobPlanTextProjection =>
764
+ ({schema:JOB_PLAN_TEXT_SCHEMA, record:identity, status:'unavailable', reason});
765
+ if (!record || !source.projectHash) return unavailable('PLAN_TEXT_RECORD_UNAVAILABLE');
766
+ if (record.path !== 'project.json') return unavailable('PLAN_TEXT_RECORD_UNSUPPORTED');
767
+ const seals = retained.seals.filter(file => file.path === record.path);
768
+ if (record.sha256 !== source.projectHash || seals.length !== 1 || seals[0]!.sha256 !== record.sha256 ||
769
+ isRetainedRecordSource(retained) && (!retained.source.files.some(file => file.path === record.path && file.sha256 === record.sha256) ||
770
+ retained.source.record.path !== record.path || retained.source.record.sha256 !== record.sha256)) {
771
+ throw new JobError('JOB_SOURCE_MISMATCH', 'PLAN_TEXT_RECORD_MISMATCH');
772
+ }
773
+ identity = {path:'project.json', sha256:record.sha256};
774
+ let project: Record<string, unknown>;
775
+ try {project = readProjectRecordBytes(retained.snapshotRoot, identity, true).project;}
776
+ catch (error) {
777
+ if (error instanceof JobError && error.code === 'JOB_RECORD_MOVED')
778
+ throw new JobError('JOB_SOURCE_MISMATCH', 'PLAN_TEXT_RECORD_HASH_MISMATCH');
779
+ throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PLAN_TEXT_RECORD_UNAVAILABLE');
780
+ }
781
+ if (project.schema !== 'rig-create/project@0') return unavailable('PLAN_TEXT_RECORD_UNSUPPORTED');
782
+ if (!Object.hasOwn(project, 'plan')) return unavailable('PLAN_TEXT_STEPS_ABSENT');
783
+ const rawPlan = asPlainObject(project.plan);
784
+ if (!rawPlan) return unavailable('PLAN_TEXT_STEPS_INVALID');
785
+ if (!Object.hasOwn(rawPlan, 'steps')) return unavailable('PLAN_TEXT_STEPS_ABSENT');
786
+ const rawSteps = rawPlan.steps;
787
+ if (!Array.isArray(rawSteps)) return unavailable('PLAN_TEXT_STEPS_INVALID');
788
+ if (plan.steps.length > 4096) return unavailable('PLAN_TEXT_LIMIT');
789
+ if (isRetainedRecordSource(retained) && (rawSteps.length !== plan.steps.length ||
790
+ rawSteps.some((raw, index) => asPlainObject(raw)?.id !== plan.steps[index]?.id)))
791
+ return unavailable('PLAN_TEXT_MAPPING_UNAVAILABLE');
792
+ const wanted = new Set(plan.steps.map(step => step.id));
793
+ const matched = new Map<string, Record<string, unknown> | null>();
794
+ for (const raw of rawSteps) {
795
+ const step = asPlainObject(raw);
796
+ if (typeof step?.id === 'string' && wanted.has(step.id))
797
+ matched.set(step.id, matched.has(step.id) ? null : step);
798
+ }
799
+ if (plan.steps.some(step => !matched.get(step.id))) return unavailable('PLAN_TEXT_MAPPING_UNAVAILABLE');
800
+ const steps = plan.steps.map<JobPlanTextStep>(step => {
801
+ const raw = matched.get(step.id)!;
802
+ const fields: Omit<JobPlanTextStep, 'id' | 'hash' | 'issues'> = {};
803
+ const issues: JobPlanTextStep['issues'] = [];
804
+ for (const field of JOB_PLAN_TEXT_FIELDS) {
805
+ const value = raw[field];
806
+ if (!Object.hasOwn(raw, field)) issues.push({field, reason:'absent'});
807
+ else if (field === 'rests_on') {
808
+ if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) issues.push({field, reason:'invalid'});
809
+ else if (value.length > 4096) issues.push({field, reason:'limit'});
810
+ else fields.rests_on = value;
811
+ } else if (typeof value === 'string') fields[field] = value;
812
+ else issues.push({field, reason:'invalid'});
813
+ }
814
+ return {id:step.id, hash:step.hash, ...fields, issues};
815
+ });
816
+ const projection: JobPlanTextProjection = {schema:JOB_PLAN_TEXT_SCHEMA, record:identity, status:'projected', steps};
817
+ return Buffer.byteLength(JSON.stringify(projection)) > 512 * 1024 ? unavailable('PLAN_TEXT_LIMIT') : projection;
818
+ }
819
+
820
+ /** Keep the normal owner metadata budget, including the small fallback itself. */
821
+ export function planTextMetadata(retained: JobRetainedSourceV3, metadata: Record<string, unknown>): Record<string, unknown> {
822
+ const projection = projectRetainedPlanText(retained);
823
+ if (!projection) return metadata;
824
+ let result = {...metadata, planText:projection};
825
+ if (Buffer.byteLength(JSON.stringify(result)) > 2 * 1024 * 1024) {
826
+ result = {...metadata, planText:{schema:JOB_PLAN_TEXT_SCHEMA, record:projection.record,
827
+ status:'unavailable', reason:'PLAN_TEXT_LIMIT'}};
828
+ if (Buffer.byteLength(JSON.stringify(result)) > 2 * 1024 * 1024)
829
+ throw new JobError('JOB_BODY_LIMIT', 'PLAN_TEXT_LIMIT');
830
+ }
831
+ return result;
832
+ }
833
+
711
834
  function decodeRetainedRecordProject(
712
835
  snapshotRoot: string,
713
836
  seals: readonly JobFileIdentity[],
@@ -799,13 +922,30 @@ function decodeRetainedRecordProject(
799
922
  }
800
923
  }
801
924
  }
925
+ // Older record readers retained only inputs/evidence. Keep those records usable,
926
+ // but expose a parts picture only when the option's entire draft closure is sealed.
927
+ let hasBoundParts = false;
928
+ const boundParts = ctx?.kind === 'parts' ? asPlainObject(ctx.parts) : null;
929
+ if (boundParts && typeof boundParts.path === 'string' && Array.isArray(boundParts.files)) {
930
+ try {
931
+ const root = jobPath(boundParts.path), paths = new Set<string>();
932
+ hasBoundParts = boundParts.files.every(value => {
933
+ const file = asPlainObject(value);
934
+ if (!file) return false;
935
+ const path = jobPath(file.path), sha = jobSha(file.sha256);
936
+ if (!path.startsWith(root + '/') || paths.has(path) || sealMap.get(path) !== sha) return false;
937
+ paths.add(path);
938
+ return true;
939
+ }) && paths.has(root + '/parts.json');
940
+ } catch {hasBoundParts = false;}
941
+ }
802
942
  return {
803
943
  questions: [{
804
944
  ref,
805
945
  set,
806
946
  editable: true,
807
947
  images,
808
- hasParts: false,
948
+ hasParts: hasBoundParts,
809
949
  }],
810
950
  optionSetFile: ref,
811
951
  };
@@ -859,6 +999,7 @@ export async function prepareJobRecordSource(options: {
859
999
  if (inventory.files.length > maxSourceFiles) {
860
1000
  throw new JobError('JOB_SOURCE_UNRETAINABLE');
861
1001
  }
1002
+ checkpointEvidenceMetadata(root.path, inventory.checkpointEvidence);
862
1003
  const snapshotRoot = join(options.stateRoot, 'snapshots', randomUUID());
863
1004
  const seals: JobFileIdentity[] = [];
864
1005
  let snapshotIdentity: { dev: number; ino: number } | null = null;
@@ -910,6 +1051,7 @@ export async function prepareJobRecordSource(options: {
910
1051
  assertRetainedSnapshotIntact(snapshotRoot, seals, snapshotIdentity, 'JOB_SOURCE_UNRETAINABLE');
911
1052
  assertEqualRecordContexts(inventory, retainedContext);
912
1053
  const decoded = decodeRetainedRecordProject(snapshotRoot, seals, result, retainedContext);
1054
+ checkpointEvidenceMetadata(snapshotRoot, retainedContext.checkpointEvidence);
913
1055
  const source = parseRecordSource(
914
1056
  result.kind === 'option-set'
915
1057
  ? buildRecordSource({
@@ -1052,6 +1194,14 @@ export async function verifyJobRecordSourceFresh(options: {
1052
1194
  return freshSource;
1053
1195
  }
1054
1196
 
1197
+ /** Preserve the existing composite preimage, conditionally appending the declaration. */
1198
+ function packageSourceDigest(packageSourceHash: string, record: JobFileIdentity | null,
1199
+ source: Pick<JobModelSourceBinding, 'selector' | 'plan' | 'parts'>, files: readonly JobFileIdentity[],
1200
+ evidence: {readonly checkpointEvidence?: readonly JobCheckpointEvidence[]}): string {
1201
+ return jobHash(JSON.stringify({schema: 'rig-review-job-source/2', packageSourceHash, record,
1202
+ selector: source.selector, plan: source.plan, parts: source.parts, files, ...evidence}));
1203
+ }
1204
+
1055
1205
  export async function prepareJobSource(options: {
1056
1206
  readonly root: JobRootIdentity;
1057
1207
  readonly stateRoot: string;
@@ -1168,6 +1318,8 @@ export async function prepareJobSource(options: {
1168
1318
  }
1169
1319
  if (requestDigest(context.selector) !== requestDigest(request.result.selector)) throw new JobError('JOB_SOURCE_MISMATCH');
1170
1320
  const declared = publishedIdentities(context);
1321
+ const evidence = checkpointEvidenceFields(context, context.plan, context.subjects, declared);
1322
+ checkpointEvidenceMetadata(root.path, evidence.checkpointEvidence);
1171
1323
  let review: Awaited<ReturnType<typeof loadReview>>;
1172
1324
  try {
1173
1325
  const target = checkedPath(root.path, request.result.path, lstatSync(join(root.path, request.result.path)).isDirectory());
@@ -1204,10 +1356,7 @@ export async function prepareJobSource(options: {
1204
1356
  await mkdir(snapshotRoot, {mode: 0o700});
1205
1357
  const info = lstatSync(snapshotRoot);
1206
1358
  snapshotIdentity = {dev: info.dev, ino: info.ino};
1207
- const imageSet = context.imageSet === undefined ? null : prepareJobImageSet(context.imageSet,
1208
- path => sourceBytes(root.path, path));
1209
- for (const image of imageSet?.imageSet.images ?? []) add(image.path, image.sha256);
1210
- const parts = await prepareParts(root.path, snapshotRoot, context.parts, options.partsEnumerator);
1359
+ const parts = await prepareParts(root.path, snapshotRoot, context.parts, declared, options.partsEnumerator);
1211
1360
  for (const [path, bytes] of parts.bytes) add(path, jobHash(bytes));
1212
1361
  if (wanted.size > maxSourceFiles) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'PARTS_REFERENCE_LIMIT');
1213
1362
  let size = 0;
@@ -1243,11 +1392,10 @@ export async function prepareJobSource(options: {
1243
1392
  const originalIdentity = (file: { path: string; sha256: string } | null): JobFileIdentity | null => file && ({
1244
1393
  path: rootRelative(root.path, resolve(review.root, file.path)), sha256: file.sha256,
1245
1394
  });
1246
- const modelSource: JobModelSourceBinding = {
1247
- sourceHash: project || context.plan || context.parts ? jobHash(JSON.stringify({
1248
- schema: 'rig-review-job-source/2', packageSourceHash: review.sourceHash,
1249
- record, selector: context.selector, plan: context.plan, parts: parts.identity, files: seals,
1250
- })) : review.sourceHash,
1395
+ checkpointEvidenceMetadata(snapshotRoot, evidence.checkpointEvidence);
1396
+ const modelSource: Omit<JobModelSourceBinding, 'checkpointEvidence'> = {
1397
+ sourceHash: project || context.plan || context.parts ? packageSourceDigest(review.sourceHash, record,
1398
+ {selector: context.selector, plan: context.plan, parts: parts.identity}, seals, evidence) : review.sourceHash,
1251
1399
  projectHash: project?.hash ?? null,
1252
1400
  package: { id: review.manifest.id, revision: review.manifest.revision },
1253
1401
  selector: context.selector,
@@ -1255,14 +1403,7 @@ export async function prepareJobSource(options: {
1255
1403
  direction: originalIdentity(review.direction?.file ?? null),
1256
1404
  optionSet: null, appliedResult: null, plan: context.plan, parts: parts.identity,
1257
1405
  };
1258
- let source: JobSourceBinding = modelSource;
1259
- if (imageSet) {
1260
- if (modelSource.model || modelSource.selector) throw new JobError('JOB_IMAGE_SET_INVALID');
1261
- const {model, selector, ...common} = modelSource;
1262
- source = {...common, subject: 'image-set', ...imageSet,
1263
- sourceHash: jobHash(JSON.stringify({schema: 'rig-review-job-image-set/1',
1264
- packageSourceHash: modelSource.sourceHash, record, imageSet: imageSet.imageSet}))};
1265
- }
1406
+ let source: JobSourceBinding = {...modelSource, ...evidence};
1266
1407
  const boundReview = { ...review, sourceHash: source.sourceHash };
1267
1408
  const sealedByPath = new Map(seals.map(seal => [seal.path, seal.sha256]));
1268
1409
  const retainedInterview = project
@@ -1282,12 +1423,13 @@ export async function prepareJobSource(options: {
1282
1423
  : null;
1283
1424
  const prepared: JobRetainedSource = {
1284
1425
  root, record, seals, snapshotRoot, snapshotIdentity,
1426
+ ...(evidence.checkpointEvidence ? {checkpointEvidencePackageHash: review.sourceHash} : {}),
1285
1427
  manifestPath: retained.manifestPath,
1286
1428
  source,
1287
1429
  instanceKey: openKey({ mode: 'single', p: boundReview, inputs: { input: review.manifestPath },
1288
1430
  contentHash: source.sourceHash, selection: null }, options.fingerprint),
1289
1431
  label: review.manifest.title,
1290
- visual: imageSet || review.manifest.model || review.manifest.references.length ? { status: 'available' } :
1432
+ visual: review.manifest.model || review.manifest.references.length ? { status: 'available' } :
1291
1433
  { status: 'unavailable', code: 'MODEL_UNAVAILABLE' },
1292
1434
  subjects: context.subjects,
1293
1435
  questions: (project?.questions ?? []).map(question => {
@@ -1303,6 +1445,7 @@ export async function prepareJobSource(options: {
1303
1445
  };
1304
1446
  await options.afterSnapshot?.();
1305
1447
  assertJobSourceCurrent(prepared);
1448
+ if (source.checkpointEvidence) assertRetainedSnapshotIntact(snapshotRoot, seals, snapshotIdentity);
1306
1449
  return prepared;
1307
1450
  } catch (error) {
1308
1451
  if (snapshotIdentity) await removeOwnedJobSnapshot(options.stateRoot, {snapshotRoot, ...snapshotIdentity});
@@ -1310,3 +1453,29 @@ export async function prepareJobSource(options: {
1310
1453
  throw new JobError('JOB_SOURCE_MISMATCH');
1311
1454
  }
1312
1455
  }
1456
+
1457
+ /** Authenticate the optional extension without opening live files or reclaimed snapshots. */
1458
+ export function assertStoredCheckpointEvidence(retained: JobRetainedSourceV3): void {
1459
+ if (!retained.source || typeof retained.source !== 'object' || Array.isArray(retained.source)) {
1460
+ throw new JobError('JOB_SOURCE_MISMATCH');
1461
+ }
1462
+ const hasEvidence = 'checkpointEvidence' in retained.source;
1463
+ if (isRetainedRecordSource(retained)) {
1464
+ const parsed = parseRecordSource(retained.source);
1465
+ if (!hasEvidence && !('checkpointEvidence' in retained.context)) return;
1466
+ const context = parseRecordPublishedContext(retained.context, retained.result, retained.record);
1467
+ if (requestDigest(parsed.checkpointEvidence ?? null) !== requestDigest(context.checkpointEvidence ?? null) ||
1468
+ requestDigest(parsed.subjects) !== requestDigest(retained.subjects) ||
1469
+ requestDigest(parsed.files) !== requestDigest(retained.seals)) throw new JobError('JOB_SOURCE_MISMATCH');
1470
+ return;
1471
+ }
1472
+ if (!hasEvidence && !('checkpointEvidencePackageHash' in retained)) return;
1473
+ const source = retained.source;
1474
+ if (!hasEvidence || !retained.record) throw new JobError('JOB_SOURCE_MISMATCH');
1475
+ const evidence = checkpointEvidenceFields(source, source.plan, retained.subjects, retained.seals);
1476
+ const packageSourceHash = jobSha(retained.checkpointEvidencePackageHash);
1477
+ const expected = packageSourceDigest(packageSourceHash, retained.record, source, retained.seals, evidence);
1478
+ if (expected !== source.sourceHash || requestDigest(evidence.checkpointEvidence) !== requestDigest(source.checkpointEvidence)) {
1479
+ throw new JobError('JOB_SOURCE_MISMATCH');
1480
+ }
1481
+ }
package/src/job-store.ts CHANGED
@@ -2,6 +2,8 @@ import { Database, constants as sqliteConstants } from 'bun:sqlite';
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { chmodSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
4
4
  import { join } from 'node:path';
5
+ import {createHash} from 'node:crypto';
6
+ import {validatePngCrop} from './comment-crops.ts';
5
7
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobEvent } from './job-contract.ts';
6
8
 
7
9
  export class JobError extends Error {
@@ -63,6 +65,28 @@ interface JobRow {
63
65
 
64
66
  const maximumDocumentBytes = 16 * 1024 * 1024;
65
67
 
68
+ /** Private representation only. Public act bytes are reconstructed without changing key order. */
69
+ export function jobCropReferences(value: unknown, save?: (sha256: string, bytes: Buffer) => void): string {
70
+ const paths = new WeakMap<object, string[]>(), references: [string[], string][] = [];
71
+ const text = JSON.stringify(value, function(key, item) {
72
+ if (save && (item === undefined || typeof item === 'function' || typeof item === 'symbol' ||
73
+ typeof item === 'bigint' || typeof item === 'number' && !Number.isFinite(item))) throw new JobError('JOB_STORAGE_FAILED');
74
+ const path = key === '' ? [] : [...(paths.get(this) ?? []), key];
75
+ if (item && typeof item === 'object') paths.set(item, path);
76
+ if (key === 'png' && typeof item === 'string' && item.startsWith('data:image/png;base64,') &&
77
+ this.path === `comment-crops/${this.sha256}.png`) {
78
+ if (save) save(this.sha256, validatePngCrop(this));
79
+ references.push([path, this.sha256]);
80
+ return 'job-crop:' + this.sha256;
81
+ }
82
+ return item;
83
+ });
84
+ if (!references.length) return text;
85
+ const packed = JSON.parse(text);
86
+ packed._jobCommentCrops = references;
87
+ return JSON.stringify(packed);
88
+ }
89
+
66
90
  function encode(value: unknown): string {
67
91
  try {
68
92
  const text = JSON.stringify(value, (_key, item) => {
@@ -208,6 +232,9 @@ export class JobStore<Data> {
208
232
  job_id TEXT NOT NULL, act_id TEXT NOT NULL, page_id TEXT NOT NULL, submission_id TEXT NOT NULL,
209
233
  sha256 TEXT NOT NULL, binding TEXT NOT NULL, png BLOB NOT NULL, act_bytes BLOB NOT NULL,
210
234
  PRIMARY KEY(job_id, act_id), UNIQUE(job_id, page_id, submission_id)
235
+ );
236
+ CREATE TABLE IF NOT EXISTS job_comment_crops (
237
+ sha256 TEXT PRIMARY KEY, png BLOB NOT NULL
211
238
  );`);
212
239
  this.captureStorage();
213
240
  } catch {
@@ -272,7 +299,8 @@ export class JobStore<Data> {
272
299
  const row = this.db.query<JobRow, [string]>(`SELECT jobs.*, job_closures.document AS closure
273
300
  FROM jobs LEFT JOIN job_closures USING(job_id) WHERE job_id=?`).get(jobId);
274
301
  if (!row) throw new JobError('JOB_UNKNOWN');
275
- return decode<Data>(row);
302
+ const stored = decode<Data>(row);
303
+ return {...stored, data: this.restoreCrops(stored.data)};
276
304
  } catch (error) {
277
305
  if (error instanceof JobError) throw error;
278
306
  throw new JobError('JOB_STORAGE_FAILED', 'Stored job state is invalid');
@@ -282,7 +310,7 @@ export class JobStore<Data> {
282
310
  activeByRootKey(rootKey: string): StoredJob<Data> | null {
283
311
  try {
284
312
  const row = this.db.query<JobRow, [string]>('SELECT * FROM jobs WHERE root_key=? AND active=1').get(rootKey);
285
- return row ? decode<Data>(row) : null;
313
+ return row ? this.get(row.job_id) : null;
286
314
  } catch {
287
315
  throw new JobError('JOB_STORAGE_FAILED', 'Stored job state is invalid');
288
316
  }
@@ -309,7 +337,7 @@ export class JobStore<Data> {
309
337
  const current = this.db.query<JobRow, [string]>(
310
338
  'SELECT * FROM jobs WHERE root_key=? AND active=1',
311
339
  ).get(rootKey);
312
- if (current) return decode<Data>(current);
340
+ if (current) return this.get(current.job_id);
313
341
  const jobId = randomUUID();
314
342
  const document = encode(initialize(jobId));
315
343
  this.db.query('INSERT INTO jobs(job_id,root_key,revision,active,document) VALUES(?,?,0,1,?)')
@@ -336,7 +364,7 @@ export class JobStore<Data> {
336
364
  if (expectedRevision !== null && current.revision !== expectedRevision) throw new JobError('JOB_GENERATION_STALE');
337
365
  const next = operation(current);
338
366
  const active = next.active ?? current.active;
339
- const document = encode(next.data);
367
+ const document = encode(JSON.parse(this.saveCrops(next.data)));
340
368
  if (next.snapshot) {
341
369
  const snapshot = next.snapshot;
342
370
  this.db.query(`INSERT INTO job_snapshot_owners
@@ -347,7 +375,8 @@ export class JobStore<Data> {
347
375
  const still = next.still;
348
376
  this.db.query(`INSERT INTO job_act_stills
349
377
  (job_id,act_id,page_id,submission_id,sha256,binding,png,act_bytes) VALUES(?,?,?,?,?,?,?,?)`)
350
- .run(jobId, still.actId, still.pageId, still.submissionId, still.sha256, still.binding, still.png, still.actBytes);
378
+ .run(jobId, still.actId, still.pageId, still.submissionId, still.sha256, still.binding, still.png,
379
+ Buffer.from(this.saveCrops(JSON.parse(Buffer.from(still.actBytes).toString()))));
351
380
  }
352
381
  this.db.query('UPDATE jobs SET revision=?,active=?,document=? WHERE job_id=?')
353
382
  .run(current.revision + 1, active ? 1 : 0, document, jobId);
@@ -356,9 +385,54 @@ export class JobStore<Data> {
356
385
  }
357
386
 
358
387
  readStill(jobId: string, actId: string): Pick<JobStoredStill, 'sha256' | 'png' | 'actBytes'> | null {
359
- return this.db.query<{sha256: string; png: Uint8Array; actBytes: Uint8Array}, [string, string]>(
388
+ const stored = this.db.query<{sha256: string; png: Uint8Array; actBytes: Uint8Array}, [string, string]>(
360
389
  'SELECT sha256,png,act_bytes AS actBytes FROM job_act_stills WHERE job_id=? AND act_id=?',
361
390
  ).get(jobId, actId);
391
+ if (!stored) return null;
392
+ let parsed: unknown;
393
+ try { parsed = JSON.parse(Buffer.from(stored.actBytes).toString()); }
394
+ catch { throw new JobError('JOB_STILL_CAPTURE_FAILED'); }
395
+ if (!Buffer.from(JSON.stringify(parsed)).equals(Buffer.from(stored.actBytes))) throw new JobError('JOB_STILL_CAPTURE_FAILED');
396
+ return {...stored, actBytes: Buffer.from(JSON.stringify(this.restoreCrops(parsed)))};
397
+ }
398
+
399
+ readCrop(sha256: string): Buffer {
400
+ const row = this.db.query<{png: Uint8Array}, [string]>('SELECT png FROM job_comment_crops WHERE sha256=?').get(sha256);
401
+ if (!row || createHash('sha256').update(row.png).digest('hex') !== sha256) throw new JobError('JOB_STORAGE_FAILED');
402
+ return Buffer.from(row.png);
403
+ }
404
+
405
+ private saveCrops(value: unknown): string {
406
+ this.db.exec('CREATE TABLE IF NOT EXISTS job_comment_crops (sha256 TEXT PRIMARY KEY, png BLOB NOT NULL)');
407
+ const saved = new Set<string>();
408
+ return jobCropReferences(value, (sha256, bytes) => {
409
+ if (saved.has(sha256)) return;
410
+ saved.add(sha256);
411
+ this.db.query('INSERT OR IGNORE INTO job_comment_crops(sha256,png) VALUES(?,?)').run(sha256, bytes);
412
+ if (!this.readCrop(sha256).equals(bytes)) throw new JobError('JOB_STORAGE_FAILED');
413
+ });
414
+ }
415
+
416
+ private restoreCrops<T>(value: T): T {
417
+ const packed = value as Record<string, unknown>, references = packed._jobCommentCrops;
418
+ if (references === undefined) return value;
419
+ if (!Array.isArray(references)) throw new JobError('JOB_STORAGE_FAILED');
420
+ delete packed._jobCommentCrops;
421
+ const cache = new Map<string, string>();
422
+ for (const [path, sha256] of references) {
423
+ if (!Array.isArray(path) || !path.every(key => typeof key === 'string') || path.at(-1) !== 'png' ||
424
+ typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(sha256)) throw new JobError('JOB_STORAGE_FAILED');
425
+ let owner: any = packed;
426
+ for (const key of path.slice(0, -1)) {
427
+ if (!owner || typeof owner !== 'object' || !Object.hasOwn(owner, key)) throw new JobError('JOB_STORAGE_FAILED');
428
+ owner = owner[key];
429
+ }
430
+ if (owner?.png !== 'job-crop:' + sha256 || owner.sha256 !== sha256 ||
431
+ owner.path !== `comment-crops/${sha256}.png`) throw new JobError('JOB_STORAGE_FAILED');
432
+ if (!cache.has(sha256)) cache.set(sha256, 'data:image/png;base64,' + this.readCrop(sha256).toString('base64'));
433
+ owner.png = cache.get(sha256);
434
+ }
435
+ return value;
362
436
  }
363
437
 
364
438
  /** Close never grows or rewrites the bounded historical document. */