@rig-c/review 4.9.1 → 4.10.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.
@@ -1,16 +1,17 @@
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_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, JOB_MESH_EDITS_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, jobActDeliveryLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
4
+ JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, JOB_MESH_EDITS_ACT_SCHEMA, JOB_CHEST_LANDMARKS_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, jobActDeliveryLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
5
5
  type ActV3, type AgentRequestV3, type EventV3, type JobPartsEnumerator, type JobAct, type JobAgentRequest, type JobDisplayAcknowledgment,
6
6
  type JobDisplayPublication, type JobDisplayPublicationV3, type JobDisplayReceipt, type JobEvent, type JobFetchActRequest, type JobFetchActRequestV3,
7
+ type JobHostPorts, type JobProgressLineV3, type JobProgressRequestV3, type JobProgressV3, type JobProgressValueV3,
7
8
  type JobNextValue, type JobPendingAsk, type JobPublication, type JobPublicationMode, type JobReviewerBinding,
8
9
  type JobSubject, type NextValueV3, type PendingAskV3, type PublicationV3, type RecordPublicationReader, type RecordSubject, type StatusV3,
9
10
  } from './job-contract.ts';
10
11
  import { bindJobAsk, bindJobRecordAsk, finalizeJobAct, parseUISubmission, prepareJobRecordAct, prepareJobStill } from './job-act.ts';
11
- import { atSubject, isRecordSource, parseRecordSource, parseCommentsAct, parseContextCommentsAct, parseMeshEditsAct, jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
12
+ import { atSubject, isRecordSource, parseRecordSource, parseCommentsAct, parseContextCommentsAct, parseMeshEditsAct, parseChestLandmarksAct, jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
12
13
  import {
13
- assertStoredCheckpointEvidence, assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, loadRetainedJobReview, prepareJobSource, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
14
+ assertStoredCheckpointEvidence, assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, loadRetainedJobReview, prepareJobSource, retainedRigDraftVerdict, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
14
15
  type JobPublicationReader, type JobRetainedSource, type JobRetainedSourceV3, type JobRootIdentity,
15
16
  } from './job-source.ts';
16
17
  import { JobError, JobStore, jobCropReferences, type JobSnapshotOwner, type StoredJob } from './job-store.ts';
@@ -54,9 +55,13 @@ interface JobData {
54
55
  events: (JobEvent | EventV3)[];
55
56
  replays: Record<string, Replay>;
56
57
  pages: Record<string, JobDisplayReceipt>;
58
+ progress?: JobProgressV3;
59
+ progressReceipt?: Pick<JobProgressV3, 'seq' | 'at'> & { writes: number };
57
60
  }
58
61
 
59
62
  const maximumEventBytes = 512 * 1024;
63
+ const progressIntervalMs = 1000;
64
+ type JobSubscription = Parameters<JobHostPorts['subscribeJob']>[0];
60
65
 
61
66
  export interface JobSessionOptions {
62
67
  readonly root: string;
@@ -84,12 +89,12 @@ function assertStoredSchemas(data: JobData): void {
84
89
  function assertStoredEvidence(data: JobData): void {
85
90
  for (const stored of Object.values(data.publications)) {
86
91
  assertStoredCheckpointEvidence(stored.retained);
87
- assertStoredEvidenceCopy(stored.publication, data);
92
+ assertStoredEvidenceCopy(stored.publication, data, true);
88
93
  }
89
94
  for (const ask of Object.values(data.asks)) assertStoredEvidenceCopy(ask, data);
90
95
  for (const act of Object.values(data.acts)) assertStoredEvidenceCopy(act, data);
91
96
  for (const event of data.events) {
92
- if (event.type === 'published') assertStoredEvidenceCopy(event.publication, data);
97
+ if (event.type === 'published') assertStoredEvidenceCopy(event.publication, data, true);
93
98
  if (event.type === 'pending') assertStoredEvidenceCopy(event.ask, data);
94
99
  if (event.type === 'act') assertStoredEvidenceCopy(event.act, data);
95
100
  }
@@ -97,7 +102,7 @@ function assertStoredEvidence(data: JobData): void {
97
102
  // An ask-batch receipt wraps its asks; each one is a durable copy like a single ask's receipt.
98
103
  const asks = (replay.value as {asks?: unknown} | null)?.asks;
99
104
  if (Array.isArray(asks)) for (const ask of asks) assertStoredEvidenceCopy(ask, data);
100
- else assertStoredEvidenceCopy(replay.value, data);
105
+ else assertStoredEvidenceCopy(replay.value, data, !!replay.value && typeof replay.value === 'object' && 'instanceKey' in replay.value);
101
106
  }
102
107
  }
103
108
 
@@ -105,11 +110,23 @@ function hasStoredEvidence(source: object | undefined): boolean {
105
110
  return !!source && ('checkpointEvidence' in source || 'previousDraft' in source);
106
111
  }
107
112
 
108
- function assertStoredEvidenceCopy(value: unknown, data: JobData): void {
113
+ function needsSnapshotRecheck(retained: JobRetainedSourceV3): boolean {
114
+ return isRetainedRecordSource(retained) || hasStoredEvidence(retained.source) || retained.chestLandmarks !== undefined;
115
+ }
116
+
117
+ function assertStoredEvidenceCopy(value: unknown, data: JobData, publication = false): void {
109
118
  if (!value || typeof value !== 'object') return;
110
119
  const copy = value as {publicationId: string; source: JobPublication['source'] | PublicationV3['source']};
111
120
  const stored = data.publications[copy.publicationId];
112
121
  const bound = stored?.retained.source;
122
+ const seeds = stored && !isRetainedRecordSource(stored.retained) ? stored.retained.chestLandmarks : undefined;
123
+ if (publication || 'chestLandmarks' in copy) {
124
+ if (('chestLandmarks' in copy) !== (seeds !== undefined) ||
125
+ ('chestLandmarks' in copy && (!publication || requestDigest(copy.chestLandmarks ?? null) !== requestDigest(seeds)))) {
126
+ throw new JobError('JOB_SOURCE_MISMATCH');
127
+ }
128
+ }
129
+ if (seeds && requestDigest(copy.source ?? null) !== requestDigest(bound)) throw new JobError('JOB_SOURCE_MISMATCH');
113
130
  if (!('source' in value) && !hasStoredEvidence(bound)) return;
114
131
  if (!copy.source || typeof copy.source !== 'object' || Array.isArray(copy.source)) throw new JobError('JOB_SOURCE_MISMATCH');
115
132
  if (!hasStoredEvidence(copy.source) && !hasStoredEvidence(bound)) return;
@@ -138,6 +155,7 @@ export class JobSession {
138
155
  readonly apiSchema: typeof JOB_API_SCHEMA | typeof JOB_API_V3_SCHEMA;
139
156
  private readonly store: JobStore<JobData>;
140
157
  private readonly listeners = new Set<() => void>();
158
+ private progressBroadcast?: { seq: number; when: number };
141
159
  private operations = 0;
142
160
  private disposed = false;
143
161
  private observedGeneration: number;
@@ -221,6 +239,8 @@ export class JobSession {
221
239
  if (!row.active) {
222
240
  row.data.fetchCapability = null;
223
241
  row.data.pages = {};
242
+ // The durable closure clears the slot without rewriting the historical row.
243
+ delete row.data.progress;
224
244
  for (const ask of Object.values(row.data.asks)) {
225
245
  if (ask.status === 'pending') row.data.asks[ask.askId] = {...ask, status: 'superseded'};
226
246
  }
@@ -323,7 +343,8 @@ export class JobSession {
323
343
  const stored = current.data.publications[publicationId];
324
344
  if (!stored) throw new JobError('JOB_PUBLICATION_UNKNOWN');
325
345
  const base = `/jobs/${this.jobId}/publications/${publicationId}/instances/${stored.publication.instanceKey}/`;
326
- return { publication: stored.publication, routes: { entry: base, apiBase: base + 'api/', assetsBase: base + 'assets/' } };
346
+ const rigDraftVerdict = retainedRigDraftVerdict(stored.retained);
347
+ return { publication: stored.publication, ...(rigDraftVerdict ? {rigDraftVerdict: true as const} : {}), routes: { entry: base, apiBase: base + 'api/', assetsBase: base + 'assets/' } };
327
348
  }
328
349
 
329
350
  /** Internal front seam. A count covers preparation and the entire file stream. */
@@ -413,18 +434,44 @@ export class JobSession {
413
434
  return previous ?? null;
414
435
  }
415
436
 
437
+ /** A stored agent receipt is returned only while it is still true (#1022). A publication that is no longer the
438
+ * head, or an ask that is no longer pending and has no finalized act, refuses by name and names the head. */
439
+ private assertReplayCurrent(current: StoredJob<JobData>, verb: string, value: unknown): void {
440
+ const data = current.data, head = 'head ' + (data.head ?? 'none');
441
+ if (verb === 'publish') {
442
+ const publicationId = (value as {publicationId: string}).publicationId;
443
+ if (data.head !== publicationId) throw new JobError('JOB_ACT_SOURCE_STALE', `publication ${publicationId} is superseded; ${head}`);
444
+ return;
445
+ }
446
+ const asks = verb === 'ask' ? [value as {askId: string}] : verb === 'ask-batch' ? (value as {asks: {askId: string}[]}).asks : [];
447
+ asks.forEach((ask, index) => {
448
+ const status = data.asks[ask.askId]?.status;
449
+ if (status === 'pending' || status === 'answered') return;
450
+ const prefix = verb === 'ask-batch' ? `subjects[${index}]: ` : '';
451
+ if (!current.active) throw new JobError('JOB_CLOSED', `${prefix}ask ${ask.askId} ended when the job closed`);
452
+ throw new JobError('JOB_ASK_SUPERSEDED', `${prefix}ask ${ask.askId} is superseded; ${head}`);
453
+ });
454
+ }
455
+
416
456
  private active(current: StoredJob<JobData>, generation: number): void {
417
457
  if (!current.active) throw new JobError('JOB_CLOSED');
418
458
  if (current.data.generation !== generation) throw new JobError('JOB_GENERATION_STALE');
419
459
  assertJobRoot(current.data.root);
420
460
  }
421
461
 
462
+ private sameSemanticRevision(observed: StoredJob<JobData>) {
463
+ // Progress writes wake cross-connection observers without invalidating semantic CAS.
464
+ const revision = observed.revision - (observed.data.progressReceipt?.writes ?? 0);
465
+ return (fresh: StoredJob<JobData>) => fresh.revision - (fresh.data.progressReceipt?.writes ?? 0) === revision;
466
+ }
467
+
422
468
  private event(data: JobData, value: JobEventPayload): EventV3 {
423
469
  const event: EventV3 = { ...value, cursor: randomUUID(), jobId: this.jobId, generation: data.generation };
424
470
  if (Buffer.byteLength(jobCropReferences(event)) > maximumEventBytes) {
425
471
  throw new JobError('JOB_BODY_LIMIT', 'Job event exceeds its delivery bound');
426
472
  }
427
473
  data.events.push(event);
474
+ if (value.type === 'published' || value.type === 'pending') delete data.progress;
428
475
  return event;
429
476
  }
430
477
 
@@ -433,7 +480,7 @@ export class JobSession {
433
480
  if (data.head !== publicationId) throw new JobError('JOB_ACT_SOURCE_STALE');
434
481
  const retained = data.publications[publicationId].retained;
435
482
  assertJobSourceCurrent(retained);
436
- if (isRetainedRecordSource(retained) || hasStoredEvidence(retained.source)) {
483
+ if (needsSnapshotRecheck(retained)) {
437
484
  assertRetainedSnapshotIntact(retained.snapshotRoot, retained.seals, retained.snapshotIdentity, 'JOB_SOURCE_UNRETAINABLE');
438
485
  }
439
486
  return retained;
@@ -451,10 +498,31 @@ export class JobSession {
451
498
 
452
499
  private notify(): void { for (const listener of this.listeners) listener(); }
453
500
 
501
+ private recordProgress(input: JobProgressRequestV3, signal: AbortSignal): JobProgressValueV3 {
502
+ if (signal.aborted || this.apiSchema !== JOB_API_V3_SCHEMA) throw new JobError('JOB_REQUEST_INVALID');
503
+ const { seq, phase, text, step } = input, at = new Date().toISOString();
504
+ let receipt: JobProgressValueV3 = { status: 'accepted', seq, at };
505
+ this.store.update(this.jobId, null, fresh => {
506
+ const { data } = fresh;
507
+ data.progress = { seq, phase, ...(text !== undefined ? { text } : {}), ...(step ? { step } : {}), at, generation: data.generation };
508
+ data.progressReceipt = { seq, at, writes: (data.progressReceipt?.writes ?? 0) + 1 };
509
+ return { data };
510
+ }, fresh => {
511
+ assertStoredSchemas(fresh.data);
512
+ if (!fresh.active) throw new JobError('JOB_CLOSED');
513
+ const previous = fresh.data.progressReceipt;
514
+ if (!previous || seq > previous.seq) return false;
515
+ receipt = { status: 'ignored', seq: previous.seq, at: previous.at };
516
+ return true;
517
+ });
518
+ return receipt;
519
+ }
520
+
454
521
  async execute(input: JobAgentRequest | AgentRequestV3 | JobFetchActRequest | JobFetchActRequestV3, signal: AbortSignal): Promise<unknown> {
455
522
  if (input.jobId !== this.jobId) throw new JobError('JOB_UNKNOWN');
456
523
  // An attached session never sees the live host's notify(), so it watches shared writes like subscribe.
457
524
  if (input.verb === 'next') return this.next(input.after, input.waitMs, signal, this.attached ? 'events' : false);
525
+ if (input.verb === 'progress') return this.recordProgress(input, signal);
458
526
  if (input.verb === 'fetch-act') {
459
527
  const current = this.current();
460
528
  if (!current.active) throw new JobError('JOB_CLOSED');
@@ -467,6 +535,7 @@ export class JobSession {
467
535
  let current = this.current();
468
536
  const previous = this.replay(current.data, key, digest);
469
537
  if (previous) {
538
+ this.assertReplayCurrent(current, input.verb, previous.value);
470
539
  this.operations++;
471
540
  try {
472
541
  if (input.verb === 'close') await this.reclaimClosedSnapshots();
@@ -501,7 +570,7 @@ export class JobSession {
501
570
  fresh.data.events.push(event);
502
571
  const value = {status: 'closed', cursor: event.cursor};
503
572
  return {generation: fresh.data.generation, event, replayKey: key, replay: {digest, value}};
504
- });
573
+ }, this.sameSemanticRevision(current));
505
574
  this.notify();
506
575
  await this.reclaimClosedSnapshots();
507
576
  return closure.replay.value;
@@ -576,7 +645,7 @@ export class JobSession {
576
645
  switch (input.verb) {
577
646
  case 'publish': {
578
647
  assertJobSourceCurrent(candidate!);
579
- if (isRetainedRecordSource(candidate!) || hasStoredEvidence(candidate!.source)) {
648
+ if (needsSnapshotRecheck(candidate!)) {
580
649
  assertRetainedSnapshotIntact(
581
650
  candidate!.snapshotRoot,
582
651
  candidate!.seals,
@@ -588,6 +657,7 @@ export class JobSession {
588
657
  publicationId: randomUUID(), instanceKey: candidate!.instanceKey, generation: data.generation,
589
658
  source: candidate!.source, label: candidate!.label, previousPublicationId: data.head, visual: candidate!.visual,
590
659
  ...(!isRetainedRecordSource(candidate!) && candidate!.interview !== undefined ? { interview: candidate!.interview } : {}),
660
+ ...(!isRetainedRecordSource(candidate!) && candidate!.chestLandmarks ? {chestLandmarks: candidate!.chestLandmarks} : {}),
591
661
  };
592
662
  for (const ask of Object.values(data.asks)) {
593
663
  if (ask.status === 'pending') data.asks[ask.askId] = { ...ask, status: 'superseded' };
@@ -620,9 +690,10 @@ export class JobSession {
620
690
  }, fresh => {
621
691
  const raced = this.replay(fresh.data, key, digest);
622
692
  if (!raced) return false;
693
+ this.assertReplayCurrent(fresh, input.verb, raced.value);
623
694
  result = raced.value;
624
695
  return true;
625
- });
696
+ }, this.sameSemanticRevision(current));
626
697
  this.notify();
627
698
  return result;
628
699
  } finally {
@@ -644,6 +715,7 @@ export class JobSession {
644
715
  if (storedAct.schema === JOB_COMMENTS_ACT_SCHEMA) parseCommentsAct(storedAct);
645
716
  if (storedAct.schema === JOB_COMMENT_CONTEXT_ACT_SCHEMA) parseContextCommentsAct(storedAct);
646
717
  if (storedAct.schema === JOB_MESH_EDITS_ACT_SCHEMA) parseMeshEditsAct(storedAct);
718
+ if (storedAct.schema === JOB_CHEST_LANDMARKS_ACT_SCHEMA) parseChestLandmarksAct(storedAct);
647
719
  const still = 'still' in storedAct ? storedAct.still : undefined;
648
720
  const actBytes = Buffer.from(JSON.stringify(storedAct));
649
721
  if (storedAct.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && !still) {
@@ -683,7 +755,7 @@ export class JobSession {
683
755
  receipt = { publicationId: input.publicationId, pageId: input.pageId, displayedNonce: randomBytes(32).toString('hex') };
684
756
  fresh.data.pages[input.pageId] = receipt;
685
757
  return { data: fresh.data };
686
- });
758
+ }, undefined, this.sameSemanticRevision(current));
687
759
  return receipt!;
688
760
  }
689
761
 
@@ -768,7 +840,7 @@ export class JobSession {
768
840
  if (!ask) throw new JobError('JOB_ASK_INVALID');
769
841
  const retained = fresh.data.publications[input.publicationId].retained;
770
842
  assertJobSourceCurrent(retained);
771
- if (isRetainedRecordSource(retained) || hasStoredEvidence(retained.source) || input.kind === 'parts-verdict') {
843
+ if (needsSnapshotRecheck(retained) || input.kind === 'parts-verdict') {
772
844
  assertRetainedSnapshotIntact(
773
845
  retained.snapshotRoot,
774
846
  retained.seals,
@@ -800,8 +872,8 @@ export class JobSession {
800
872
  return act!;
801
873
  }
802
874
 
803
- private events(after: string | null): JobNextValue | NextValueV3 {
804
- const current = this.current(), events = current.data.events;
875
+ private events(after: string | null, current = this.current()): JobNextValue | NextValueV3 {
876
+ const events = current.data.events;
805
877
  const index = after === null ? -1 : events.findIndex(event => event.cursor === after);
806
878
  if (after !== null && index < 0) throw new JobError('JOB_CURSOR_INVALID');
807
879
  const batch: EventV3[] = [];
@@ -833,10 +905,17 @@ export class JobSession {
833
905
  if (waitMs < 0 || waitMs > jobWaitLimitMs || !Number.isSafeInteger(waitMs)) throw new JobError('JOB_REQUEST_INVALID');
834
906
  if (signal.aborted) throw new JobError('JOB_REQUEST_INVALID', 'Request cancelled');
835
907
  // Capture before reading events so a commit between the read and listener registration still wakes us.
836
- let revision = observeWrites ? this.store.revision(this.jobId) : null;
908
+ const observe = observeWrites ? { revision: this.store.revision(this.jobId), mode: observeWrites } : null;
837
909
  const ready = this.events(after);
838
910
  if (ready.status !== 'timeout' || !waitMs) return ready;
839
- await new Promise<void>((resolve, reject) => {
911
+ await this.waitForChange(after, waitMs, signal, observe);
912
+ return this.events(after);
913
+ }
914
+
915
+ private waitForChange(after: string | null, waitMs: number, signal: AbortSignal,
916
+ observe: { readonly revision: number; readonly mode: 'revision' | 'events' } | null): Promise<void> {
917
+ let revision = observe?.revision ?? null;
918
+ return new Promise<void>((resolve, reject) => {
840
919
  let poll: ReturnType<typeof setInterval> | undefined;
841
920
  let settled = false;
842
921
  const cleanup = () => { clearTimeout(timer); clearInterval(poll); this.listeners.delete(finish); signal.removeEventListener('abort', abort); };
@@ -847,7 +926,7 @@ export class JobSession {
847
926
  try {
848
927
  const observed = this.store.revision(this.jobId);
849
928
  if (observed === revision) return;
850
- if (observeWrites === 'revision') return finish();
929
+ if (observe?.mode === 'revision') return finish();
851
930
  // An act wait stays open across a write without a deliverable event (display receipt).
852
931
  revision = observed;
853
932
  if (this.events(after).status !== 'timeout') finish();
@@ -859,28 +938,59 @@ export class JobSession {
859
938
  signal.addEventListener('abort', abort, { once: true });
860
939
  try {
861
940
  if (signal.aborted) abort();
862
- else if (observeWrites) {
941
+ else if (revision !== null) {
863
942
  // Other sessions commit to the same store but cannot notify this instance's listeners.
864
943
  poll = setInterval(changed, 250);
865
944
  changed();
866
945
  } else if (this.events(after).status !== 'timeout') finish();
867
946
  } catch (error) { fail(error); }
868
947
  });
869
- return this.events(after);
870
948
  }
871
949
 
872
- async *subscribe(input: { readonly jobId: string; readonly after: string | null; readonly signal: AbortSignal }): AsyncIterable<EventV3> {
950
+ subscribe(input: JobSubscription): AsyncIterable<EventV3>;
951
+ subscribe(input: JobSubscription, page: true): AsyncIterable<EventV3 | JobProgressLineV3>;
952
+ async *subscribe(input: JobSubscription, page = false): AsyncIterable<EventV3 | JobProgressLineV3> {
873
953
  if (input.jobId !== this.jobId) throw new JobError('JOB_UNKNOWN');
874
954
  let after = input.after;
955
+ let delivered: JobProgressV3 | null | undefined;
956
+ const line = (progress: JobProgressV3 | null): JobProgressLineV3 => ({
957
+ type: 'progress', jobId: this.jobId, progress, now: new Date().toISOString(),
958
+ });
875
959
  while (!input.signal.aborted) {
876
- let value: JobNextValue | NextValueV3;
877
- try { value = await this.next(after, jobWaitLimitMs, input.signal, 'revision'); }
960
+ // Read the scalar revision first so a commit between this snapshot and waiting is observed.
961
+ const revision = this.store.revision(this.jobId);
962
+ const current = this.current(), value = this.events(after, current);
963
+ const progress = current.data.progress ?? null;
964
+ const displayed = delivered;
965
+ if (page && displayed === undefined) {
966
+ delivered = progress;
967
+ yield line(delivered);
968
+ } else if (page && displayed && (!progress || value.events.some(event =>
969
+ event.type !== 'act' && event.generation > displayed.generation))) {
970
+ delivered = null;
971
+ yield line(null);
972
+ }
973
+ for (const event of value.events) { after = event.cursor; yield event; }
974
+ if (value.status === 'closed') return;
975
+ if (value.events.length) continue;
976
+ let waitMs = jobWaitLimitMs;
977
+ if (page && progress && delivered?.seq !== progress.seq) {
978
+ // Share the cadence across pages. Keep waiting for the trailing slot even when writes stop.
979
+ const when = performance.now();
980
+ const previous = this.progressBroadcast;
981
+ if (!previous || previous.seq === progress.seq || when - previous.when >= progressIntervalMs) {
982
+ if (previous?.seq !== progress.seq) this.progressBroadcast = { seq: progress.seq, when };
983
+ delivered = progress;
984
+ yield line(delivered);
985
+ continue;
986
+ }
987
+ waitMs = Math.ceil(progressIntervalMs - (when - previous.when));
988
+ }
989
+ try { await this.waitForChange(after, waitMs, input.signal, { revision, mode: 'revision' }); }
878
990
  catch (error) {
879
991
  if (input.signal.aborted && error instanceof JobError && error.code === 'JOB_REQUEST_INVALID') return;
880
992
  throw error;
881
993
  }
882
- for (const event of value.events) { after = event.cursor; yield event; }
883
- if (value.status === 'closed') return;
884
994
  }
885
995
  }
886
996
 
package/src/job-source.ts CHANGED
@@ -11,6 +11,7 @@ import {
11
11
  JOB_PARTS_ENUMERATOR_RANGE,
12
12
  } from './job-contract.ts';
13
13
  import type {
14
+ JobChestLandmarkValue, JobErrorCode, JobPublication, JobPublishedChestLandmark,
14
15
  JobCheckpointEvidence, JobFileIdentity, JobInterviewDiagnostics, JobInterviewRecord, JobModelSourceBinding, JobPartsEnumerator, JobPartsFileReference, JobPartsIdentity, JobPlanIdentity, JobPublishRequest,
15
16
  JobPreviousDraft, JobSelector, JobSourceBinding, JobSubject, JobPlanTextProjection, JobPlanTextStep,
16
17
  OptionContext, OptionSource, PackageResultV3, PlanContext, PlanSource, ProjectRecord, PublishRequestV3,
@@ -22,8 +23,12 @@ import { acceptedRigReview } from './interview-scene.ts';
22
23
  import { BUILD_MODEL_PATH, loadJobReview, loadReview } from './manifest.ts';
23
24
  import { HandoffError } from './handoff.ts';
24
25
  import { openKey } from './open.ts';
26
+ import { attachmentHashText, MESH_EDIT_CODES } from './mesh-edit.ts';
27
+ import { readStoredSetupMesh } from './setup-mesh.ts';
28
+ import { contourParts } from './rebuild.ts';
29
+ import { parseBustSpec } from './chest-landmarks.ts';
25
30
  import { assertReviewUnchanged } from './reference.ts';
26
- import {
31
+ import { isRigDraftVerdictSource,
27
32
  assertEqualRecordContexts,
28
33
  assertJobApiSchema,
29
34
  atSubject,
@@ -36,7 +41,9 @@ import {
36
41
  jobPath,
37
42
  jobSha,
38
43
  jobText,
44
+ optionSetRefs,
39
45
  parseJobInterviewDiagnostics,
46
+ parsePublishedChestLandmarks,
40
47
  parseRecordFreeze,
41
48
  parseRecordPublishedContext,
42
49
  parseRecordResult,
@@ -62,6 +69,7 @@ export interface JobRootIdentity {
62
69
  export interface JobPublishedContext {
63
70
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
64
71
  readonly previousDraft?: JobPreviousDraft;
72
+ readonly chestLandmarks?: JobPublication['chestLandmarks'];
65
73
  readonly selector: JobSelector | null;
66
74
  readonly plan: JobPlanIdentity | null;
67
75
  readonly parts: JobPartsIdentity | null;
@@ -91,6 +99,7 @@ export type JobPublicationReader = (input: {
91
99
  export interface JobRetainedSource {
92
100
  /** Private base preimage for optional declarations. Keeps its historical key. */
93
101
  readonly checkpointEvidencePackageHash?: string;
102
+ readonly chestLandmarks?: JobPublication['chestLandmarks'];
94
103
  readonly root: JobRootIdentity;
95
104
  readonly record: JobFileIdentity | null;
96
105
  readonly seals: readonly JobFileIdentity[];
@@ -133,6 +142,13 @@ export function isRetainedRecordSource(retained: JobRetainedSourceV3): retained
133
142
  return 'kind' in retained && retained.kind === 'record';
134
143
  }
135
144
 
145
+ /** Select rig inspection from the retained declaration before any ask arrives. */
146
+ export function retainedRigDraftVerdict(retained: JobRetainedSourceV3): boolean {
147
+ return !isRetainedRecordSource(retained) && isRigDraftVerdictSource(retained.source) &&
148
+ retained.subjects.some(subject => subject.kind === 'review-verdict' && subject.stage === 'rig-review');
149
+ }
150
+
151
+
136
152
  const maxSourceBytes = 256 * 1024 * 1024;
137
153
  const maxSourceFiles = 4096;
138
154
  const maxFileBytes = 64 * 1024 * 1024;
@@ -197,6 +213,50 @@ function sourceBytes(root: string, path: string): Buffer {
197
213
  return bytes;
198
214
  }
199
215
 
216
+ /** Read the sealed model for both kinds of setup-space edit. */
217
+ export function readJobEditModel(root: string, file: JobFileIdentity | null, code: JobErrorCode) {
218
+ try {
219
+ if (!file) throw new JobError(code);
220
+ const bytes = sourceBytes(root, file.path);
221
+ if (jobHash(bytes) !== file.sha256) throw new JobError(code);
222
+ return JSON.parse(bytes.toString('utf8')) as {stage?: {width?: number; height?: number}};
223
+ } catch {
224
+ throw new JobError(code);
225
+ }
226
+ }
227
+
228
+ export function readJobEditMesh(model: ReturnType<typeof readJobEditModel>, edit: Omit<JobChestLandmarkValue, 'bust'>,
229
+ stale: JobErrorCode, invalid: JobErrorCode) {
230
+ const read = readStoredSetupMesh(model, edit.slot, edit, MESH_EDIT_CODES);
231
+ if (!read.ok || jobHash(attachmentHashText(read.mesh.entry)) !== edit.source.hash) throw new JobError(stale);
232
+ const {width, height} = edit.source.frame;
233
+ if (read.mesh.linked || model.stage?.width !== width || model.stage?.height !== height) throw new JobError(invalid);
234
+ return read.mesh;
235
+ }
236
+
237
+ function assertPublishedChestLandmarks(root: string, modelFile: JobFileIdentity | null, configFiles: readonly JobFileIdentity[],
238
+ seeds: readonly JobPublishedChestLandmark[]): void {
239
+ const code = 'JOB_SOURCE_MISMATCH';
240
+ const model = readJobEditModel(root, modelFile, code);
241
+ const configs = new Map<string, ReturnType<typeof contourParts>>();
242
+ for (const seed of seeds) {
243
+ readJobEditMesh(model, seed, code, code);
244
+ const hash = seed.source.configHash;
245
+ let parts = configs.get(hash);
246
+ if (!parts) {
247
+ const file = configFiles.find(file => file.sha256 === hash);
248
+ if (!file) throw new JobError(code, 'Published chest landmarks require the retained source config');
249
+ const bytes = readCheckpointEvidenceBytes(root, file, maxFileBytes, () => new JobError(code));
250
+ parts = contourParts(new TextDecoder('utf-8', {fatal: true}).decode(bytes));
251
+ configs.set(hash, parts);
252
+ }
253
+ const contour = parts.find(part => part.name === seed.slot)?.entry.contour as {bust?: unknown} | undefined;
254
+ if (!contour || requestDigest(parseBustSpec(contour.bust, 'contour.bust', true)) !== requestDigest(seed.bust)) {
255
+ throw new JobError(code, 'Published chest landmarks differ from the retained source config');
256
+ }
257
+ }
258
+ }
259
+
200
260
  /** Read and hash the exact bytes the caller will consume, including on a cache hit at the front. */
201
261
  export function readPreviousDraftBytes(root: string, file: JobFileIdentity, operand: 'current' | 'previous' | 'diff'): Buffer {
202
262
  const limit = operand === 'diff' ? 1024 * 1024 : maxFileBytes;
@@ -896,6 +956,15 @@ export async function loadRetainedRecordRig(retained: JobRetainedRecordSource) {
896
956
  }
897
957
  }
898
958
 
959
+ /** Create declares the original painting as the first project input. */
960
+ export function retainedRecordPainting(retained: JobRetainedRecordSource): Pick<InterviewQuestion['images'][number], 'ref' | 'name'> | null {
961
+ const {project} = readProjectRecordBytes(retained.snapshotRoot, retained.record);
962
+ const input = asPlainObject(Array.isArray(project.inputs) ? project.inputs[0] : null);
963
+ const seal = retained.seals.find(file => file.path === input?.path && file.sha256 === input?.sha256);
964
+ if (!seal || !/\.(png|jpe?g|webp|svg)$/i.test(seal.path)) return null;
965
+ return {ref: seal, name: posix.basename(seal.path)};
966
+ }
967
+
899
968
  /** Delivery-only projection through the existing retained record reader. */
900
969
  export function projectRetainedPlanText(retained: JobRetainedSourceV3): JobPlanTextProjection | undefined {
901
970
  const {source, record} = retained;
@@ -981,6 +1050,7 @@ function decodeRetainedRecordProject(
981
1050
  ): {
982
1051
  readonly questions: readonly InterviewQuestion[];
983
1052
  readonly optionSetFile: JobFileIdentity | null;
1053
+ readonly optionSetFiles?: readonly JobFileIdentity[];
984
1054
  } {
985
1055
  const sealMap = new Map<string, string>();
986
1056
  for (const seal of seals) {
@@ -994,9 +1064,10 @@ function decodeRetainedRecordProject(
994
1064
  if (context.plan !== null) {
995
1065
  throw new JobError('JOB_SOURCE_MISMATCH');
996
1066
  }
997
- const { questionId, setId } = result;
998
1067
  const interview = asPlainObject(project.interview);
999
1068
  if (!interview) throw new JobError('JOB_SOURCE_MISMATCH');
1069
+ // #1004: one question per published set, in set order; one set keeps the original single-question result.
1070
+ const decodedSets = optionSetRefs(result).map(({ questionId, setId }) => {
1000
1071
  const collections = [
1001
1072
  [interview.framing, ['interview']],
1002
1073
  [interview.waypoints, ['interview', 'rigging-interview']],
@@ -1092,7 +1163,7 @@ function decodeRetainedRecordProject(
1092
1163
  } catch {hasBoundParts = false;}
1093
1164
  }
1094
1165
  return {
1095
- questions: [{
1166
+ question: {
1096
1167
  ref,
1097
1168
  set,
1098
1169
  editable: true,
@@ -1101,8 +1172,14 @@ function decodeRetainedRecordProject(
1101
1172
  ...(ctx?.kind === 'scene' && images.length ? {scenePicture: true as const} : {}),
1102
1173
  ...(set.stage === 'post-interview' && !images.length && (ctx?.kind === 'rig' || ctx?.kind === 'scene')
1103
1174
  ? {missingPicture: ctx.kind} : {}),
1104
- }],
1105
- optionSetFile: ref,
1175
+ } satisfies InterviewQuestion,
1176
+ ref,
1177
+ };
1178
+ });
1179
+ return {
1180
+ questions: decodedSets.map(item => item.question),
1181
+ optionSetFile: decodedSets[0]!.ref,
1182
+ ...(result.sets ? { optionSetFiles: decodedSets.map(item => item.ref) } : {}),
1106
1183
  };
1107
1184
  }
1108
1185
 
@@ -1216,6 +1293,7 @@ export async function prepareJobRecordSource(options: {
1216
1293
  selection: result,
1217
1294
  context: retainedContext as OptionContext,
1218
1295
  optionSetFile: decoded.optionSetFile!,
1296
+ ...(decoded.optionSetFiles ? { optionSetFiles: decoded.optionSetFiles } : {}),
1219
1297
  })
1220
1298
  : buildRecordSource({
1221
1299
  record,
@@ -1324,6 +1402,7 @@ export async function verifyJobRecordSourceFresh(options: {
1324
1402
  selection: retained.result,
1325
1403
  context: retainedContext as OptionContext,
1326
1404
  optionSetFile: decoded.optionSetFile!,
1405
+ ...(decoded.optionSetFiles ? { optionSetFiles: decoded.optionSetFiles } : {}),
1327
1406
  })
1328
1407
  : buildRecordSource({
1329
1408
  record: retained.record,
@@ -1357,7 +1436,7 @@ export async function verifyJobRecordSourceFresh(options: {
1357
1436
  /** Preserve the existing composite preimage, conditionally appending the declaration. */
1358
1437
  function packageSourceDigest(packageSourceHash: string, record: JobFileIdentity | null,
1359
1438
  source: Pick<JobModelSourceBinding, 'selector' | 'plan' | 'parts'>, files: readonly JobFileIdentity[],
1360
- evidence: Pick<JobModelSourceBinding, 'checkpointEvidence' | 'previousDraft'>): string {
1439
+ evidence: Pick<JobModelSourceBinding, 'checkpointEvidence' | 'previousDraft'> & Pick<JobPublication, 'chestLandmarks'>): string {
1361
1440
  return jobHash(JSON.stringify({schema: 'rig-review-job-source/2', packageSourceHash, record,
1362
1441
  selector: source.selector, plan: source.plan, parts: source.parts, files, ...evidence}));
1363
1442
  }
@@ -1481,6 +1560,9 @@ export async function prepareJobSource(options: {
1481
1560
  const declared = publishedIdentities(context);
1482
1561
  const previous = previousDraftFields(context, context.selector, declared);
1483
1562
  const evidence = checkpointEvidenceFields(context, context.plan, context.subjects, declared);
1563
+ const chestLandmarks = 'chestLandmarks' in context ? parsePublishedChestLandmarks(context.chestLandmarks) : undefined;
1564
+ if (chestLandmarks && context.selector?.kind !== 'rig') throw new JobError('JOB_SOURCE_MISMATCH');
1565
+ const chest = chestLandmarks ? {chestLandmarks} : {};
1484
1566
  checkpointEvidenceMetadata(root.path, evidence.checkpointEvidence);
1485
1567
  let review: Awaited<ReturnType<typeof loadJobReview>>;
1486
1568
  try {
@@ -1567,13 +1649,18 @@ export async function prepareJobSource(options: {
1567
1649
  path: rootRelative(root.path, resolve(review.root, file.path)), sha256: file.sha256,
1568
1650
  });
1569
1651
  checkpointEvidenceMetadata(snapshotRoot, evidence.checkpointEvidence);
1652
+ const model = originalIdentity(review.reviewedSource.rig);
1653
+ if (chestLandmarks) {
1654
+ const handoffConfig = originalIdentity(review.handoff?.record.config ?? null);
1655
+ assertPublishedChestLandmarks(snapshotRoot, model, handoffConfig ? [handoffConfig] : declared, chestLandmarks);
1656
+ }
1570
1657
  const modelSource: JobModelSourceBinding = {
1571
- sourceHash: project || context.plan || context.parts ? packageSourceDigest(review.sourceHash, record,
1572
- {selector: context.selector, plan: context.plan, parts: parts.identity}, seals, {...evidence, ...previous}) : review.sourceHash,
1658
+ sourceHash: project || context.plan || context.parts || chestLandmarks ? packageSourceDigest(review.sourceHash, record,
1659
+ {selector: context.selector, plan: context.plan, parts: parts.identity}, seals, {...evidence, ...previous, ...chest}) : review.sourceHash,
1573
1660
  projectHash: project?.hash ?? null,
1574
1661
  package: { id: review.manifest.id, revision: review.manifest.revision },
1575
1662
  selector: context.selector,
1576
- model: originalIdentity(review.reviewedSource.rig),
1663
+ model,
1577
1664
  direction: originalIdentity(review.direction?.file ?? null),
1578
1665
  optionSet: null, appliedResult: null, plan: context.plan, parts: parts.identity,
1579
1666
  };
@@ -1597,7 +1684,8 @@ export async function prepareJobSource(options: {
1597
1684
  : null;
1598
1685
  const prepared: JobRetainedSource = {
1599
1686
  root, record, seals, snapshotRoot, snapshotIdentity,
1600
- ...(source.checkpointEvidence || source.previousDraft ? {checkpointEvidencePackageHash: review.sourceHash} : {}),
1687
+ ...(source.checkpointEvidence || source.previousDraft || chestLandmarks ? {checkpointEvidencePackageHash: review.sourceHash} : {}),
1688
+ ...chest,
1601
1689
  manifestPath: retained.manifestPath,
1602
1690
  source,
1603
1691
  instanceKey: openKey({ mode: 'single', p: boundReview, inputs: { input: review.manifestPath },
@@ -1619,7 +1707,7 @@ export async function prepareJobSource(options: {
1619
1707
  };
1620
1708
  await options.afterSnapshot?.();
1621
1709
  assertJobSourceCurrent(prepared);
1622
- if (source.checkpointEvidence || source.previousDraft) assertRetainedSnapshotIntact(snapshotRoot, seals, snapshotIdentity);
1710
+ if (source.checkpointEvidence || source.previousDraft || chestLandmarks) assertRetainedSnapshotIntact(snapshotRoot, seals, snapshotIdentity);
1623
1711
  return prepared;
1624
1712
  } catch (error) {
1625
1713
  if (snapshotIdentity) await removeOwnedJobSnapshot(options.stateRoot, {snapshotRoot, ...snapshotIdentity});
@@ -1635,6 +1723,7 @@ export function assertStoredCheckpointEvidence(retained: JobRetainedSourceV3): v
1635
1723
  }
1636
1724
  const hasEvidence = 'checkpointEvidence' in retained.source;
1637
1725
  if (isRetainedRecordSource(retained)) {
1726
+ if ('chestLandmarks' in retained) throw new JobError('JOB_SOURCE_MISMATCH');
1638
1727
  const parsed = parseRecordSource(retained.source);
1639
1728
  if (!hasEvidence && !('checkpointEvidence' in retained.context) && !('previousDraft' in retained.context)) return;
1640
1729
  const context = parseRecordPublishedContext(retained.context, retained.result, retained.record);
@@ -1645,14 +1734,20 @@ export function assertStoredCheckpointEvidence(retained: JobRetainedSourceV3): v
1645
1734
  }
1646
1735
  const source = retained.source;
1647
1736
  const hasPreviousDraft = 'previousDraft' in source;
1648
- if (!hasEvidence && !hasPreviousDraft && !('checkpointEvidencePackageHash' in retained)) return;
1649
- if (!(hasEvidence || hasPreviousDraft) || !retained.record || (hasPreviousDraft && !source.parts)) {
1737
+ const hasChest = 'chestLandmarks' in retained;
1738
+ if (!hasEvidence && !hasPreviousDraft && !hasChest && !('checkpointEvidencePackageHash' in retained)) return;
1739
+ if (!(hasEvidence || hasPreviousDraft || hasChest) || !retained.record || (hasPreviousDraft && !source.parts) ||
1740
+ (hasChest && (source.selector?.kind !== 'rig' || !source.model))) {
1650
1741
  throw new JobError('JOB_SOURCE_MISMATCH');
1651
1742
  }
1652
1743
  const evidence = checkpointEvidenceFields(source, source.plan, retained.subjects, retained.seals);
1653
1744
  const previous = previousDraftFields(source, source.selector, retained.seals);
1654
1745
  const packageSourceHash = jobSha(retained.checkpointEvidencePackageHash);
1655
- const expected = packageSourceDigest(packageSourceHash, retained.record, source, retained.seals, {...evidence, ...previous});
1746
+ const chest = hasChest ? {chestLandmarks: parsePublishedChestLandmarks(retained.chestLandmarks)} : {};
1747
+ if (chest.chestLandmarks?.some(seed => !retained.seals.some(file => file.sha256 === seed.source.configHash))) {
1748
+ throw new JobError('JOB_SOURCE_MISMATCH');
1749
+ }
1750
+ const expected = packageSourceDigest(packageSourceHash, retained.record, source, retained.seals, {...evidence, ...previous, ...chest});
1656
1751
  if (expected !== source.sourceHash ||
1657
1752
  requestDigest(evidence.checkpointEvidence ?? null) !== requestDigest(source.checkpointEvidence ?? null) ||
1658
1753
  requestDigest(previous.previousDraft ?? null) !== requestDigest(source.previousDraft ?? null)) {