rig-review 4.6.0 → 4.8.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.
package/src/job-api.ts CHANGED
@@ -1,13 +1,16 @@
1
1
  import {checkpointEvidenceFields} from './job-checkpoint-evidence.ts';
2
+ import {previousDraftFields} from './job-previous-draft.ts';
2
3
  import { createHash, timingSafeEqual } from 'node:crypto';
3
4
  import {
4
5
  JOB_ACT_SCHEMA, JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ENABLED_ACT_KINDS, JOB_PARTS_ENUMERATOR_RANGE,
5
6
  JOB_PLAN_BOUND_SIGNOFF_STAGES, JOB_RECORD_SIGNOFF_STAGES, JOB_RECORD_ACT_SCHEMA, JOB_RECORD_INSTANCE_SCHEMA, JOB_RECORD_SOURCE_SCHEMA,
6
7
  JOB_RESERVED_ACT_KINDS,
8
+ JOB_MESH_EDITS_ACT_SCHEMA,
7
9
  type AgentRequestV3, type FetchActRequestV3, type JobAgentRequest, type JobApiSchema,
8
10
  type JobCheckpointEvidence, type JobDisplayAcknowledgment, type JobErrorCode, type JobFetchActRequest, type JobFileIdentity,
9
11
  type JobHostPorts, type JobHumanAuthority, type JobInterviewDiagnostic, type JobInterviewDiagnostics,
10
12
  type JobInterviewJson, type JobInterviewRecord, type JobPlanIdentity, type JobPublicationMode,
13
+ type JobAct, type JobMeshEdit, type JobMeshEditsAct, type JobMeshEditValue,
11
14
  type JobPublishRequest, type JobResult, type JobSelector, type JobSha256, type JobSubject,
12
15
  type OptionContext, type OptionSource, type PlanContext, type PlanSource, type ProjectRecord,
13
16
  type PublishRequestV3, type PublishResultV3, type RecordAct, type RecordFreeze,
@@ -26,7 +29,8 @@ import { parseStageComment, hasStageComment, projectComments, commentModes } fro
26
29
  import { validatePngCrop, validatePngCropMetadata } from './comment-crops.ts';
27
30
  import {parseJobPartsIdentity} from './job-source.ts';
28
31
  import {parseControlPart, parseControlView} from './control.ts';
29
- import {EMIT_UNPINNED_CREATE_FIELDS} from './create-pin-gate.ts';
32
+ import {canonicalJson} from './canonical-json.ts';
33
+ import {MESH_EDIT_MAX_OPS, type Vec} from './mesh-edit.ts';
30
34
 
31
35
  export type {
32
36
  JobInterviewJson,
@@ -37,23 +41,17 @@ export type {
37
41
 
38
42
  export const jobBodyLimit = 256 * 1024;
39
43
  export const jobWaitLimitMs = 30_000;
44
+ /** Subjects one `ask-batch` request may list (#963). */
45
+ export const jobAskBatchLimit = 64;
40
46
  const requestDeadlineMs = 10_000;
41
47
 
42
48
  export function jobHash(value: string | Uint8Array): string {
43
49
  return createHash('sha256').update(value).digest('hex');
44
50
  }
45
51
 
46
- /** Private replay digests only. This is not a mesh payload/source hash format. */
52
+ /** Private replay digest. Preserve the original serializer for persisted request identity. */
47
53
  export function requestDigest(value: unknown): string {
48
- const sorted = (item: unknown): unknown => {
49
- if (Array.isArray(item)) return item.map(sorted);
50
- if (item !== null && typeof item === 'object') {
51
- return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
52
- .map(([key, child]) => [key, sorted(child)]));
53
- }
54
- return item;
55
- };
56
- return jobHash(JSON.stringify(sorted(value)));
54
+ return jobHash(canonicalJson(value));
57
55
  }
58
56
 
59
57
  export function sameCapability(given: string | null, expected: string): boolean {
@@ -285,7 +283,7 @@ export function parseJobRequest(
285
283
  ): JobAgentRequest | JobFetchActRequest | AgentRequestV3 | FetchActRequestV3 {
286
284
  const item = jobObject(value, [
287
285
  'schema', 'jobId', 'requestId', 'verb', 'expectedGeneration', 'idempotencyKey',
288
- 'result', 'freeze', 'publicationId', 'subject', 'after', 'waitMs', 'reason', 'actId',
286
+ 'result', 'freeze', 'publicationId', 'subject', 'subjects', 'after', 'waitMs', 'reason', 'actId',
289
287
  ]);
290
288
  const targetSchema = mode === 'package-only' || mode === 'record-and-package'
291
289
  ? jobApiSchemaForMode(mode)
@@ -332,18 +330,26 @@ export function parseJobRequest(
332
330
  }
333
331
  case 'ask': {
334
332
  jobObject(item, ['schema', 'jobId', 'requestId', 'verb', 'expectedGeneration', 'idempotencyKey', 'publicationId', 'subject']);
335
- const isReopenSubject =
336
- item.subject !== null &&
337
- typeof item.subject === 'object' &&
338
- !Array.isArray(item.subject) &&
339
- (item.subject as { kind?: unknown }).kind === 'reopen';
340
333
  return {
341
334
  ...mutation,
342
335
  verb: 'ask',
343
336
  publicationId: jobId(item.publicationId),
344
- subject: isReopenSubject ? parseRecordSubject(item.subject) : parseJobSubject(item.subject),
337
+ subject: parseAskSubjectV3(item.subject),
345
338
  };
346
339
  }
340
+ case 'ask-batch': {
341
+ jobObject(item, ['schema', 'jobId', 'requestId', 'verb', 'expectedGeneration', 'idempotencyKey', 'publicationId', 'subjects']);
342
+ const listed = item.subjects;
343
+ if (!Array.isArray(listed) || listed.length < 1 || listed.length > jobAskBatchLimit) throw new JobError('JOB_REQUEST_INVALID');
344
+ const seen = new Map<string, number>();
345
+ const subjects = Array.from(listed, (value: unknown, index) => atSubject(index, () => {
346
+ const subject = parseAskSubjectV3(value), digest = requestDigest(subject), first = seen.get(digest);
347
+ if (first !== undefined) throw new JobError('JOB_REQUEST_INVALID', `duplicate of subjects[${first}]`);
348
+ seen.set(digest, index);
349
+ return subject;
350
+ }));
351
+ return { ...mutation, verb: 'ask-batch', publicationId: jobId(item.publicationId), subjects };
352
+ }
347
353
  case 'close':
348
354
  jobObject(item, ['schema', 'jobId', 'requestId', 'verb', 'expectedGeneration', 'idempotencyKey', 'reason']);
349
355
  return { ...mutation, verb: 'close', reason: jobText(item.reason, 1024) };
@@ -386,6 +392,23 @@ export function parseJobRequest(
386
392
  throw new JobError('JOB_REQUEST_INVALID');
387
393
  }
388
394
 
395
+ /** The single V3 `ask` subject parser; `ask-batch` parses each listed subject through it. */
396
+ function parseAskSubjectV3(value: unknown): JobSubject | RecordSubject {
397
+ const isReopenSubject =
398
+ value !== null && typeof value === 'object' && !Array.isArray(value) && (value as { kind?: unknown }).kind === 'reopen';
399
+ return isReopenSubject ? parseRecordSubject(value) : parseJobSubject(value);
400
+ }
401
+
402
+ /** `ask-batch` refuses with the subject's own code, its message prefixed by the subject's request index. */
403
+ export function atSubject<Value>(index: number, fn: () => Value): Value {
404
+ try {
405
+ return fn();
406
+ } catch (error) {
407
+ if (error instanceof JobError) throw new JobError(error.code, `subjects[${index}]: ${error.message}`);
408
+ throw error;
409
+ }
410
+ }
411
+
389
412
  export function parseJobRequestV3(value: unknown): AgentRequestV3 | FetchActRequestV3 {
390
413
  return parseJobRequest(value, JOB_API_V3_SCHEMA);
391
414
  }
@@ -415,7 +438,7 @@ export function exactObject(
415
438
  return item;
416
439
  }
417
440
 
418
- function parseFileRow(value: unknown, code: JobErrorCode): JobFileIdentity {
441
+ export function parseFileRow(value: unknown, code: JobErrorCode): JobFileIdentity {
419
442
  const item = exactObject(value, ['path', 'sha256'], code);
420
443
  return asCode(() => ({ path: jobPath(item.path), sha256: jobSha(item.sha256) }), code);
421
444
  }
@@ -710,6 +733,7 @@ export function parseRecordPublishedContext(
710
733
  ): OptionContext | PlanContext {
711
734
  const selection = parseRecordResult(result);
712
735
  const checkedRecord = record === undefined ? undefined : parseProjectRecord(record, 'JOB_SOURCE_MISMATCH');
736
+ if (value && typeof value === 'object') previousDraftFields(value, null);
713
737
  const item = exactObject(value, ['label', 'parts', 'inputs', 'files', 'plan', 'subjects'], 'JOB_SOURCE_MISMATCH', ['checkpointEvidence']);
714
738
  const label = asCode(() => jobText(item.label), 'JOB_SOURCE_MISMATCH');
715
739
  const parts = parseRecordPartsIdentity(item.parts, 'JOB_SOURCE_MISMATCH');
@@ -1218,6 +1242,11 @@ function parseCommentAnchor(raw: unknown, text: string, source?: SourceV3 | stri
1218
1242
  if ('schema' in item) {
1219
1243
  commentsObject(item, ['schema', 'id', 'parts', 'sourceHash', 'rigRegion', 'imageRegion', 'view', 'crop', 'nativeCrop']);
1220
1244
  const issue = parsePartsIssue({...item, summary: text}, true, false, false);
1245
+ const comparison = issue.view.comparison;
1246
+ if (comparison?.mode === 'difference' && comparison.operand === 'previous-draft' &&
1247
+ (issue.view.mode !== 'assembled' || !source || typeof source === 'string' || 'record' in source || !source.previousDraft)) {
1248
+ throw new JobError('JOB_ACT_INVALID');
1249
+ }
1221
1250
  if (issue.crop.png !== undefined) validatePngCrop(issue.crop as Parameters<typeof validatePngCrop>[0]);
1222
1251
  if (sourceHash && issue.sourceHash !== sourceHash) throw new JobError('JOB_ACT_SOURCE_STALE');
1223
1252
  if (source && typeof source !== 'string' && !('record' in source)) {
@@ -1364,11 +1393,13 @@ function commentsSource(raw: unknown): Exclude<SourceV3, OptionSource> {
1364
1393
  return record;
1365
1394
  }
1366
1395
  const common = ['sourceHash', 'projectHash', 'package', 'direction', 'optionSet', 'appliedResult', 'plan', 'parts'];
1367
- const item = commentsObject(raw, [...common, 'selector', 'model'], ['checkpointEvidence']);
1396
+ const item = commentsObject(raw, [...common, 'selector', 'model'], ['checkpointEvidence', 'previousDraft']);
1368
1397
  jobSha(item.sourceHash); if (item.projectHash !== null) jobSha(item.projectHash);
1369
1398
  const pkg = commentsObject(item.package, ['id', 'revision']); jobText(pkg.id); jobText(pkg.revision);
1370
1399
  for (const key of ['direction', 'model']) if (item[key] !== null) parseFileRow(item[key], 'JOB_ACT_INVALID');
1371
- parseJobSelector(item.selector);
1400
+ const selector = parseJobSelector(item.selector);
1401
+ const previousDraft = previousDraftFields(item, selector);
1402
+ if (previousDraft.previousDraft && item.parts === null) throw new JobError('JOB_ACT_INVALID');
1372
1403
  if (item.optionSet !== null) {
1373
1404
  const set = commentsObject(item.optionSet, ['id', 'sha256']); jobId(set.id); jobSha(set.sha256);
1374
1405
  }
@@ -1396,28 +1427,130 @@ function commentsSource(raw: unknown): Exclude<SourceV3, OptionSource> {
1396
1427
 
1397
1428
  /** Public @6 decoder. The UI finalizers write checkpoint, parts, rig/post verdict and signoff acts at @6 (#713). */
1398
1429
  export function parseCommentsAct(raw: unknown): JobCommentsAct {
1399
- return decodeCommentsAct(raw, false) as JobCommentsAct;
1430
+ return decodeCommentsAct(raw, JOB_COMMENTS_ACT_SCHEMA) as JobCommentsAct;
1400
1431
  }
1401
1432
 
1402
1433
  /** Public @7 decoder: the @6 rules plus an optional `context` on each comment. @6 input refuses. */
1403
1434
  export function parseContextCommentsAct(raw: unknown): JobContextCommentsAct {
1404
- return decodeCommentsAct(raw, true) as JobContextCommentsAct;
1435
+ return decodeCommentsAct(raw, JOB_COMMENT_CONTEXT_ACT_SCHEMA) as JobContextCommentsAct;
1405
1436
  }
1406
1437
 
1407
- /** The comments act a writer sends. With EMIT_UNPINNED_CREATE_FIELDS off, contexts are dropped and @6 goes out. */
1408
- export function commentsActForEmission(act: JobCommentsAct | JobContextCommentsAct,
1409
- emitUnpinned: boolean = EMIT_UNPINNED_CREATE_FIELDS): JobCommentsAct | JobContextCommentsAct {
1438
+ /** Public @8 decoder. Model freshness and topology are checked by the writer. */
1439
+ export function parseMeshEditsAct(raw: unknown): JobMeshEditsAct {
1440
+ return decodeCommentsAct(raw, JOB_MESH_EDITS_ACT_SCHEMA) as JobMeshEditsAct;
1441
+ }
1442
+
1443
+ export function meshEditDigest(edit: JobMeshEditValue): JobSha256 {
1444
+ return jobHash(canonicalJson(edit));
1445
+ }
1446
+
1447
+ function meshNumber(raw: unknown): number {
1448
+ if (typeof raw !== 'number' || !Number.isFinite(raw) || Object.is(raw, -0)) throw new JobError('JOB_ACT_INVALID');
1449
+ return raw;
1450
+ }
1451
+
1452
+ function meshPair(raw: unknown, parse: (value: unknown) => number): Vec {
1453
+ if (!Array.isArray(raw) || raw.length !== 2) throw new JobError('JOB_ACT_INVALID');
1454
+ return [parse(raw[0]), parse(raw[1])];
1455
+ }
1456
+
1457
+ function roundedMeshPair(raw: unknown): void {
1458
+ const pair = meshPair(raw, meshNumber);
1459
+ // A multiply-round-divide pass can change an already rounded large double.
1460
+ if (pair.some(n => Number(n.toFixed(2)) !== n)) throw new JobError('JOB_ACT_INVALID');
1461
+ }
1462
+
1463
+ const meshIndex = (raw: unknown): number => jobInteger(meshNumber(raw));
1464
+
1465
+ function validateMeshOp(raw: unknown): void {
1466
+ const op = (raw as {op?: unknown} | null)?.op;
1467
+ switch (op) {
1468
+ case 'move': {
1469
+ const move = commentsObject(raw, ['op', 'v', 'from', 'to']);
1470
+ meshIndex(move.v); meshPair(move.from, meshNumber); roundedMeshPair(move.to);
1471
+ break;
1472
+ }
1473
+ case 'add': {
1474
+ const add = commentsObject(raw, ['op', 'at'], ['onEdge']);
1475
+ roundedMeshPair(add.at);
1476
+ if (Object.hasOwn(add, 'onEdge')) meshPair(add.onEdge, meshIndex);
1477
+ break;
1478
+ }
1479
+ case 'remove':
1480
+ meshIndex(commentsObject(raw, ['op', 'v']).v);
1481
+ break;
1482
+ case 'edge':
1483
+ case 'unedge': {
1484
+ const edge = commentsObject(raw, ['op', 'a', 'b']);
1485
+ meshIndex(edge.a); meshIndex(edge.b);
1486
+ break;
1487
+ }
1488
+ default:
1489
+ throw new JobError('JOB_ACT_INVALID');
1490
+ }
1491
+ }
1492
+
1493
+ function validateMeshEdit(raw: unknown): asserts raw is JobMeshEditValue {
1494
+ const edit = commentsObject(raw, ['slot', 'skin', 'attachment', 'basis', 'source', 'ops']);
1495
+ if (edit.basis !== 'setup' || [edit.slot, edit.skin, edit.attachment].some(name => typeof name !== 'string' || !name)) {
1496
+ throw new JobError('JOB_ACT_INVALID');
1497
+ }
1498
+ const source = commentsObject(edit.source, ['vertexCount', 'triangleCount', 'hullLength', 'hash', 'frame', 'positions']);
1499
+ const vertexCount = meshIndex(source.vertexCount);
1500
+ meshIndex(source.triangleCount); meshIndex(source.hullLength); jobSha(source.hash);
1501
+ const frame = commentsObject(source.frame, ['width', 'height']);
1502
+ if (meshNumber(frame.width) <= 0 || meshNumber(frame.height) <= 0 ||
1503
+ !Array.isArray(source.positions) || source.positions.length !== vertexCount) throw new JobError('JOB_ACT_INVALID');
1504
+ for (const position of source.positions) meshPair(position, meshNumber);
1505
+ if (!Array.isArray(edit.ops) || !edit.ops.length || edit.ops.length > MESH_EDIT_MAX_OPS) throw new JobError('JOB_ACT_INVALID');
1506
+ for (const op of edit.ops) validateMeshOp(op);
1507
+ }
1508
+
1509
+ /** Structures and digests only. The retained model is the writer's source of topology and freshness. */
1510
+ export function parseMeshEdits(raw: unknown): readonly JobMeshEdit[] {
1511
+ return asCode(() => {
1512
+ if (!Array.isArray(raw) || !raw.length) throw new JobError('JOB_ACT_INVALID');
1513
+ const seen = new Set<string>();
1514
+ let previousOrder: string | undefined;
1515
+ for (const item of raw) {
1516
+ const {edit, sha256} = commentsObject(item, ['edit', 'sha256']);
1517
+ validateMeshEdit(edit);
1518
+ const identity = [edit.skin, edit.slot, edit.attachment];
1519
+ const order = identity.join('/'), key = JSON.stringify(identity);
1520
+ if (seen.has(key) || (previousOrder !== undefined && order < previousOrder) || jobSha(sha256) !== meshEditDigest(edit)) {
1521
+ throw new JobError('JOB_ACT_INVALID');
1522
+ }
1523
+ seen.add(key);
1524
+ previousOrder = order;
1525
+ }
1526
+ return structuredClone(raw) as JobMeshEdit[];
1527
+ }, 'JOB_ACT_INVALID');
1528
+ }
1529
+
1530
+ /** Write @7 when a comment carries context, otherwise keep the @6 envelope. */
1531
+ export function commentsActForEmission(act: JobCommentsAct | JobContextCommentsAct): JobCommentsAct | JobContextCommentsAct {
1410
1532
  const value = act.value as {comments: readonly JobContextComment[]};
1411
- const comments = value.comments.map(({context, ...comment}) => emitUnpinned && context ? {...comment, context} : comment);
1412
- const schema = emitUnpinned && comments.some(comment => 'context' in comment) ? JOB_COMMENT_CONTEXT_ACT_SCHEMA : JOB_COMMENTS_ACT_SCHEMA;
1413
- const next = {...structuredClone(act), schema, value: {...structuredClone(act.value), comments: structuredClone(comments)}};
1533
+ const schema = value.comments.some(comment => Object.hasOwn(comment, 'context')) ? JOB_COMMENT_CONTEXT_ACT_SCHEMA : JOB_COMMENTS_ACT_SCHEMA;
1534
+ const next = {...act, schema};
1414
1535
  return schema === JOB_COMMENTS_ACT_SCHEMA ? parseCommentsAct(next) : parseContextCommentsAct(next);
1415
1536
  }
1416
1537
 
1417
- function decodeCommentsAct(raw: unknown, withContext: boolean): JobCommentsAct | JobContextCommentsAct {
1538
+ /** Write @8 for a rig verdict carrying mesh evidence. */
1539
+ export function meshEditsActForEmission(act: JobCommentsAct | (Extract<JobCommentsAct, {kind: 'review-verdict'}> & {
1540
+ readonly value: {readonly meshEdits: readonly JobMeshEdit[]};
1541
+ })): JobCommentsAct | Extract<JobAct, {schema: typeof JOB_MESH_EDITS_ACT_SCHEMA}> {
1542
+ if (!Object.hasOwn(act.value, 'meshEdits')) {
1543
+ parseCommentsAct(act);
1544
+ return act;
1545
+ }
1546
+ return parseMeshEditsAct({...act, schema: JOB_MESH_EDITS_ACT_SCHEMA}) as Extract<JobAct, {schema: typeof JOB_MESH_EDITS_ACT_SCHEMA}>;
1547
+ }
1548
+
1549
+ function decodeCommentsAct(raw: unknown, schema: JobCommentsAct['schema'] | JobContextCommentsAct['schema'] | JobMeshEditsAct['schema']):
1550
+ JobCommentsAct | JobContextCommentsAct | JobMeshEditsAct {
1418
1551
  return asCode(() => {
1419
1552
  const item = commentsObject(raw, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value'], ['still']);
1420
- if (item.schema !== (withContext ? JOB_COMMENT_CONTEXT_ACT_SCHEMA : JOB_COMMENTS_ACT_SCHEMA)) throw new JobError('JOB_ACT_INVALID');
1553
+ if (item.schema !== schema) throw new JobError('JOB_ACT_INVALID');
1421
1554
  for (const key of ['actId', 'jobId', 'askId', 'publicationId']) jobId(item[key]);
1422
1555
  parseHumanAuthority(item.authority, 'JOB_ACT_INVALID');
1423
1556
  if (typeof item.at !== 'string' || !Number.isFinite(Date.parse(item.at))) throw new JobError('JOB_ACT_INVALID');
@@ -1429,8 +1562,9 @@ function decodeCommentsAct(raw: unknown, withContext: boolean): JobCommentsAct |
1429
1562
  };
1430
1563
  const keys = typeof item.kind === 'string' && Object.hasOwn(fields, item.kind) ? fields[item.kind] : undefined;
1431
1564
  if (!keys) throw new JobError('JOB_ACT_INVALID');
1432
- const value = commentsObject(item.value, keys);
1433
- const comments = withContext ? decodeComments(value.comments, source, true) : parseComments(value.comments, source);
1565
+ const at8 = schema === JOB_MESH_EDITS_ACT_SCHEMA;
1566
+ const value = commentsObject(item.value, keys, at8 && item.kind === 'review-verdict' ? ['meshEdits'] : []);
1567
+ const comments = schema === JOB_COMMENTS_ACT_SCHEMA ? parseComments(value.comments, source) : decodeComments(value.comments, source, true);
1434
1568
  if (comments.some(comment => comment.anchor && 'side' in comment.anchor)) throw new JobError('JOB_ACT_INVALID');
1435
1569
  if ((comments as readonly JobContextComment[]).some(comment => comment.context?.subject &&
1436
1570
  comment.context.subject.ask.kind !== item.kind)) throw new JobError('JOB_ACT_INVALID');
@@ -1456,13 +1590,22 @@ function decodeCommentsAct(raw: unknown, withContext: boolean): JobCommentsAct |
1456
1590
  if ('record' in source) validateRecordAskSubject(item.kind === 'checkpoint' ? {kind: item.kind, checkpointId: value.checkpointId} :
1457
1591
  {kind: item.kind, stage: value.stage}, source);
1458
1592
  const rig = item.kind === 'review-verdict' && value.stage === 'rig-review';
1593
+ let meshEdits: readonly JobMeshEdit[] | undefined;
1594
+ if (at8 && Object.hasOwn(value, 'meshEdits')) {
1595
+ if (!rig || value.verdict !== 'changes-requested') throw new JobError('JOB_ACT_INVALID');
1596
+ meshEdits = parseMeshEdits(value.meshEdits);
1597
+ }
1598
+ if (at8 && item.kind === 'review-verdict' && value.verdict === 'changes-requested' && !comments.length && !meshEdits) {
1599
+ throw new JobError('JOB_ACT_INVALID');
1600
+ }
1459
1601
  if (rig) {
1460
1602
  const still = commentsObject(item.still, ['path', 'sha256', 'camera', 'frame'], ['animation']);
1461
1603
  if (still.path !== jobSha(still.sha256) + '.png' || still.camera !== 'fixed' ||
1462
1604
  (still.frame === 'setup' ? 'animation' in still : typeof still.frame !== 'number' || !Number.isFinite(still.frame) ||
1463
1605
  still.frame < 0 || typeof still.animation !== 'string' || !still.animation)) throw new JobError('JOB_ACT_INVALID');
1464
1606
  } else if ('still' in item) throw new JobError('JOB_ACT_INVALID');
1465
- return {...structuredClone(item), source, value: {...value, comments}} as unknown as JobCommentsAct | JobContextCommentsAct;
1607
+ return {...structuredClone(item), source, value: {...value, comments, ...(meshEdits ? {meshEdits} : {})}} as unknown as
1608
+ JobCommentsAct | JobContextCommentsAct | JobMeshEditsAct;
1466
1609
  }, 'JOB_ACT_INVALID');
1467
1610
  }
1468
1611
 
@@ -1491,12 +1634,16 @@ export async function jobBody(request: Request, maximum = jobBodyLimit): Promise
1491
1634
  chunks.push(value);
1492
1635
  }
1493
1636
  const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
1494
- const hasCommentImages = ['parts-verdict', 'review-verdict', 'checkpoint', 'signoff', 'reopen'].includes(value?.kind) &&
1495
- /"png":"data:image\/png;base64,/.test(JSON.stringify(value?.value));
1496
- const rigCapture = value?.kind === 'review-verdict' && value?.value?.stage === 'rig-review' && value.capture;
1497
- if (size > jobBodyLimit && !(maximum > jobBodyLimit && (rigCapture || hasCommentImages))) {
1637
+ if (value?.value != null && Object.hasOwn(value.value, 'meshEdits') &&
1638
+ Buffer.byteLength(canonicalJson(value.value.meshEdits)) > jobBodyLimit) {
1498
1639
  throw new JobError('JOB_BODY_LIMIT');
1499
1640
  }
1641
+ if (size > jobBodyLimit) {
1642
+ const hasCommentImages = ['parts-verdict', 'review-verdict', 'checkpoint', 'signoff', 'reopen'].includes(value?.kind) &&
1643
+ /"png":"data:image\/png;base64,/.test(JSON.stringify(value?.value));
1644
+ const rigCapture = value?.kind === 'review-verdict' && value?.value?.stage === 'rig-review' && value.capture;
1645
+ if (!(maximum > jobBodyLimit && (rigCapture || hasCommentImages))) throw new JobError('JOB_BODY_LIMIT');
1646
+ }
1500
1647
  return value;
1501
1648
  } catch (error) {
1502
1649
  void reader.cancel().catch(() => {});
@@ -1,4 +1,4 @@
1
- import {realpathSync} from 'node:fs';
1
+ import {lstatSync, realpathSync} from 'node:fs';
2
2
  import type {JobCheckpointEvidence, JobCheckpointTable, JobFileIdentity, JobPlanIdentity, JobSubject, RecordSubject} from './job-contract.ts';
3
3
  import {exactObject, jobHash, jobId, jobPath, jobSha} from './job-api.ts';
4
4
  import {JobError} from './job-store.ts';
@@ -81,14 +81,27 @@ export function parseCheckpointTable(bytes: Buffer): JobCheckpointTable {
81
81
  }
82
82
 
83
83
  /** Exact retained closure reads reuse regular-file, containment and descriptor bounds. */
84
- export function readCheckpointEvidenceBytes(root: string, file: JobFileIdentity, limit: number): Buffer {
85
- let bytes: Buffer;
84
+ export function readCheckpointEvidenceBytes(root: string, file: JobFileIdentity, limit: number,
85
+ refuse: (failure: 'path' | 'limit' | 'hash') => JobError = failure => failure === 'hash'
86
+ ? new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_HASH_MISMATCH')
87
+ : new JobError('JOB_SOURCE_UNRETAINABLE', 'CHECKPOINT_EVIDENCE_PATH_REFUSED')): Buffer {
88
+ let bytes: Buffer | undefined;
86
89
  try {
87
90
  if (realpathSync(root) !== root) throw new Error('Noncanonical evidence root');
88
- bytes = readRegular(checkedPath(root, file.path), limit);
91
+ const path = checkedPath(root, jobPath(file.path));
92
+ const before = lstatSync(path);
93
+ if (!before.isFile()) throw new Error('Expected a regular evidence file');
94
+ if (before.size <= limit) {
95
+ bytes = readRegular(path, limit);
96
+ const after = lstatSync(path);
97
+ if (realpathSync(path) !== path || bytes.length !== before.size || before.dev !== after.dev ||
98
+ before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs ||
99
+ before.ctimeMs !== after.ctimeMs) throw new Error('Evidence file changed during read');
100
+ }
89
101
  }
90
- catch { throw new JobError('JOB_SOURCE_UNRETAINABLE', 'CHECKPOINT_EVIDENCE_PATH_REFUSED'); }
91
- if (jobHash(bytes) !== file.sha256) throw new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_HASH_MISMATCH');
102
+ catch { throw refuse('path'); }
103
+ if (bytes === undefined) throw refuse('limit');
104
+ if (jobHash(bytes) !== file.sha256) throw refuse('hash');
92
105
  return bytes;
93
106
  }
94
107
 
package/src/job-cli.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import {closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync} from 'node:fs';
3
3
  import {join} from 'node:path';
4
- import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit, jobActDeliveryLimit, jobResponseBodyLimit,
5
- type JobAct, type JobCommentsAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
- import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest, parseCommentsAct } from './job-api.ts';
4
+ import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_COMMENT_CONTEXT_ACT_SCHEMA, JOB_MESH_EDITS_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit, jobActDeliveryLimit, jobResponseBodyLimit,
5
+ type JobAct, type JobMeshEditsAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
+ import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest, parseCommentsAct, parseContextCommentsAct, parseMeshEditsAct } from './job-api.ts';
7
7
  import { JobError } from './job-store.ts';
8
8
  import {validatePngBytes} from './comment-crops.ts';
9
9
  import {destinationDirectory} from './destination-directory.ts';
@@ -145,15 +145,21 @@ async function consumerBytes(stream: ReadableStream<Uint8Array> | null, maximum:
145
145
  }
146
146
  }
147
147
 
148
- type ConsumerAct = JobAct | JobCommentsAct;
148
+ type ConsumerAct = JobAct | JobMeshEditsAct;
149
+
150
+ const consumerCommentsDecoders = {
151
+ [JOB_COMMENTS_ACT_SCHEMA]: parseCommentsAct,
152
+ [JOB_COMMENT_CONTEXT_ACT_SCHEMA]: parseContextCommentsAct,
153
+ [JOB_MESH_EDITS_ACT_SCHEMA]: parseMeshEditsAct,
154
+ } as const;
149
155
 
150
156
  function parseConsumerAct(bytes: Buffer, job: string, actId: string): ConsumerAct {
151
157
  let value: unknown;
152
158
  try { value = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes)); }
153
159
  catch { throw new JobError('JOB_REQUEST_INVALID'); }
154
160
  const act = jobObject(value, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value', 'still']);
155
- if (act.schema === JOB_COMMENTS_ACT_SCHEMA) {
156
- const comments = parseCommentsAct(act);
161
+ if (typeof act.schema === 'string' && Object.hasOwn(consumerCommentsDecoders, act.schema)) {
162
+ const comments = consumerCommentsDecoders[act.schema as keyof typeof consumerCommentsDecoders](act);
157
163
  if (comments.jobId !== job || comments.actId !== actId) throw new JobError('JOB_ACT_INVALID');
158
164
  return comments;
159
165
  }
@@ -18,6 +18,7 @@ import type { CompareFeedback, CompareSession } from './compare-session.ts';
18
18
  import type { MarkRegion } from './stage-comment.ts';
19
19
  import type { PartsVerdict } from './parts-view.ts';
20
20
  import type { ControlNumericCamera, ControlPart } from './control.ts';
21
+ import type { MeshOp, Vec } from './mesh-edit.ts';
21
22
 
22
23
  export const JOB_API_SCHEMA = 'rig-review/job-api@2' as const;
23
24
  export const JOB_API_V3_SCHEMA = 'rig-review/job-api@3' as const;
@@ -30,8 +31,10 @@ export const JOB_RECORD_ACT_SCHEMA = 'rig-review/act@4' as const;
30
31
  export const JOB_PARTS_VERDICT_ACT_SCHEMA = 'rig-review/act@5' as const;
31
32
  /** Fresh checkpoint, parts-verdict, rig/post review-verdict and signoff writers. Image-review and interview-picks stay @2; record acts stay @4. */
32
33
  export const JOB_COMMENTS_ACT_SCHEMA = 'rig-review/act@6' as const;
33
- /** @6 plus an optional per-comment `context`. Emitted only behind EMIT_UNPINNED_CREATE_FIELDS (#714). */
34
+ /** @6 plus an optional per-comment `context` (#714). */
34
35
  export const JOB_COMMENT_CONTEXT_ACT_SCHEMA = 'rig-review/act@7' as const;
36
+ /** @7 plus a mesh payload on a compiled rig's Request changes (#952). */
37
+ export const JOB_MESH_EDITS_ACT_SCHEMA = 'rig-review/act@8' as const;
35
38
  export const REVIEW_COMMENTS_SESSION_SCHEMA = 'rig-review-session/2' as const;
36
39
  export const REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA = 'rig-review-compare-session/2' as const;
37
40
  export const PARTS_COMMENTS_VERDICT_SCHEMA = 'rig-review-parts-verdict/5' as const;
@@ -96,6 +99,49 @@ export type JobContextCommentsAct = {
96
99
  readonly value: Omit<JobCommentsActValues[Kind], 'comments'> & { readonly comments: readonly JobContextComment[] };
97
100
  }
98
101
  }[keyof JobCommentsActValues];
102
+
103
+ export interface JobMeshEditValue {
104
+ readonly slot: string;
105
+ readonly skin: string;
106
+ readonly attachment: string;
107
+ readonly basis: 'setup';
108
+ readonly source: {
109
+ readonly vertexCount: number;
110
+ readonly triangleCount: number;
111
+ readonly hullLength: number;
112
+ /** SHA-256 of JSON.stringify(entry) in the retained model's stored key order. */
113
+ readonly hash: JobSha256;
114
+ readonly frame: {readonly width: number; readonly height: number};
115
+ /** Unrounded displayed setup positions in rig canvas crop px, in source vertex order. */
116
+ readonly positions: readonly Vec[];
117
+ };
118
+ readonly ops: readonly MeshOp[];
119
+ }
120
+
121
+ export interface JobMeshEdit {
122
+ readonly edit: JobMeshEditValue;
123
+ readonly sha256: JobSha256;
124
+ }
125
+
126
+ type JobRigMeshEditsAct = Omit<Extract<JobContextCommentsAct, {kind: 'review-verdict'}>, 'schema' | 'source' | 'value' | 'still'> & {
127
+ readonly schema: typeof JOB_MESH_EDITS_ACT_SCHEMA;
128
+ readonly source: JobRigReviewAct['source'];
129
+ readonly still: JobRigStill;
130
+ readonly value: {
131
+ readonly stage: 'rig-review';
132
+ readonly verdict: 'changes-requested';
133
+ readonly comments: readonly JobContextComment[];
134
+ readonly meshEdits: readonly JobMeshEdit[];
135
+ };
136
+ };
137
+
138
+ /** Decoder grammar for @8, whose writer emits it only when mesh edits are present. */
139
+ export type JobMeshEditsAct = JobRigMeshEditsAct | {
140
+ [Kind in keyof JobCommentsActValues]: Omit<Extract<JobContextCommentsAct, {kind: Kind}>, 'schema' | 'value'> & {
141
+ readonly schema: typeof JOB_MESH_EDITS_ACT_SCHEMA;
142
+ readonly value: Extract<JobContextCommentsAct, {kind: Kind}>['value'] & {readonly meshEdits?: never};
143
+ }
144
+ }[keyof JobCommentsActValues];
99
145
  export type ReviewCommentsSession = Omit<ReviewSession, 'schema' | 'feedback' | 'checkpoints'> & {
100
146
  schema: typeof REVIEW_COMMENTS_SESSION_SCHEMA;
101
147
  checkpoints: Record<string, { outcome: 'pending' | 'pass' | 'fail' }>;
@@ -193,6 +239,7 @@ export const JOB_RECORD_ACT_KINDS = [
193
239
  'reopen',
194
240
  ] as const;
195
241
 
242
+ /** Standalone asks and acts for these kinds remain disabled. */
196
243
  export const JOB_RESERVED_ACT_KINDS = ['described-correction', 'mesh-edit'] as const;
197
244
  export type JobEnabledActKind = typeof JOB_ENABLED_ACT_KINDS[number];
198
245
  export type RecordActKind = typeof JOB_RECORD_ACT_KINDS[number];
@@ -208,16 +255,6 @@ export const JOB_PLAN_BOUND_SIGNOFF_STAGES = [
208
255
  /** Record-only approval stages; not part of the public job-host runtime exports. */
209
256
  export const JOB_RECORD_SIGNOFF_STAGES = [...JOB_PLAN_BOUND_SIGNOFF_STAGES, 'direction-review', 'interview'] as const;
210
257
 
211
- /** Reserved kinds have no accepted value shape and cannot be asked or submitted.
212
- * Described correction awaits the joint Create #182 context allowlist.
213
- * Mesh edit awaits the joint Parts #1159 freeze. Proposal 6ff03ec9 discusses
214
- * slot/attachment/skin identity, setup basis, vertex/triangle/hull counts and
215
- * at most 300 closed move/add/remove/edge/unedge operations in crop pixels.
216
- * The exact attachment bytes behind source.hash and the canonical payload
217
- * digest replacing delta_sha256 are UNRESOLVED. This contract defines neither.
218
- * A future submitted mesh act must carry human UI authority, time, exact rig
219
- * revision/source and recomputable provenance. Drafts are never consumer acts.
220
- */
221
258
  export const JOB_CONSUMER_AUTH_MODE = 'writer-owned-sibling-fetch-capability' as const;
222
259
 
223
260
  /** Hex digests, opaque IDs/cursors and timestamps require runtime validation.
@@ -380,6 +417,16 @@ export interface JobPartsIdentity {
380
417
  }[];
381
418
  }
382
419
 
420
+ export const JOB_PREVIOUS_DRAFT_SCHEMA = 'rig-review-previous-draft/1';
421
+
422
+ /** Publisher-owned accepted draft and work-root-relative seals for its comparison. */
423
+ export interface JobPreviousDraft {
424
+ readonly schema: typeof JOB_PREVIOUS_DRAFT_SCHEMA;
425
+ readonly draft: { readonly id: JobId; readonly revision: JobSha256 };
426
+ readonly composites: { readonly current: JobFileIdentity; readonly previous: JobFileIdentity };
427
+ readonly diff?: JobFileIdentity;
428
+ }
429
+
383
430
  export type JobSelector =
384
431
  | { readonly kind: 'draft'; readonly id: string }
385
432
  | { readonly kind: 'rig'; readonly version: number }
@@ -391,6 +438,7 @@ export type JobSelector =
391
438
  */
392
439
  export interface JobModelSourceBinding {
393
440
  readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
441
+ readonly previousDraft?: JobPreviousDraft;
394
442
  readonly subject?: never;
395
443
  readonly sourceHash: JobSha256;
396
444
  readonly projectHash: JobSha256 | null;
@@ -499,11 +547,17 @@ export interface JobActValues {
499
547
  * supplies checkpoint ID, outcome and words only. Create derives execution
500
548
  * stage from its authoritative step phase/order. Review never stamps a stage.
501
549
  */
502
- export type JobUIActValues = Omit<JobActValues, 'checkpoint' | 'review-verdict'> & {
550
+ export type JobUIActValues = Omit<JobActValues, 'checkpoint' | 'parts-verdict' | 'review-verdict'> & {
503
551
  readonly checkpoint: Omit<JobActValues['checkpoint'], 'planStepId'>;
552
+ readonly 'parts-verdict': PartsVerdictValue & {readonly general?: readonly string[]};
504
553
  readonly 'review-verdict': JobImageReviewValue
505
554
  | (JobModelReviewValue & {readonly stage: 'direction-review'})
506
- | (JobModelReviewValue & {readonly stage: 'rig-review'; readonly feedback?: readonly Feedback[]});
555
+ | (JobModelReviewValue & {
556
+ readonly stage: 'rig-review';
557
+ readonly feedback?: readonly Feedback[];
558
+ readonly general?: readonly string[];
559
+ readonly meshEdits?: readonly JobMeshEdit[];
560
+ });
507
561
  };
508
562
 
509
563
  export interface JobActSources {
@@ -571,8 +625,8 @@ export type JobPartsVerdictAct = Omit<Extract<JobLegacyAct, {kind: 'parts-verdic
571
625
  };
572
626
 
573
627
  /** Historical @2 acts remain readable without being backfilled or relabelled.
574
- * Fresh checkpoint, parts, rig/post verdict and signoff acts are written as act@6. */
575
- export type JobAct = JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct | JobCommentsAct;
628
+ * Fresh comments use @6, live rig comments carrying context use @7, and rig verdicts carrying mesh edits use @8. */
629
+ export type JobAct = JobLegacyAct | JobRigReviewAct | JobPartsVerdictAct | JobCommentsAct | JobContextCommentsAct | JobRigMeshEditsAct;
576
630
 
577
631
  /** Authenticated browser provenance. The daemon validates identity and hashes PNG bytes. */
578
632
  export interface JobRigCapture {
@@ -967,6 +1021,17 @@ export type AskRequestV3 = Omit<JobAskRequest, 'schema' | 'subject'> & {
967
1021
  readonly subject: JobSubject | RecordSubject;
968
1022
  };
969
1023
 
1024
+ /** One request that asks every listed subject of the head record publication (#963). */
1025
+ export type AskBatchRequestV3 = Omit<AskRequestV3, 'verb' | 'subject'> & {
1026
+ readonly verb: 'ask-batch';
1027
+ readonly subjects: readonly (JobSubject | RecordSubject)[];
1028
+ };
1029
+
1030
+ /** `asks[i]` answers `subjects[i]` of the request. */
1031
+ export interface AskBatchValueV3 {
1032
+ readonly asks: readonly PendingAskV3[];
1033
+ }
1034
+
970
1035
  export type NextRequestV3 = Omit<JobNextRequest, 'schema'> & {
971
1036
  readonly schema: typeof JOB_API_V3_SCHEMA;
972
1037
  };
@@ -978,6 +1043,7 @@ export type CloseRequestV3 = Omit<JobCloseRequest, 'schema'> & {
978
1043
  export type AgentRequestV3 =
979
1044
  | PublishRequestV3
980
1045
  | AskRequestV3
1046
+ | AskBatchRequestV3
981
1047
  | NextRequestV3
982
1048
  | CloseRequestV3;
983
1049
 
@@ -1157,14 +1223,21 @@ export type RecordAct = Pick<JobLegacyAct,
1157
1223
  export type SourceV3 = JobSourceBinding | RecordSource;
1158
1224
  export type ActV3 = JobAct | RecordAct;
1159
1225
 
1226
+ /**
1227
+ * `recordPublication`, `recordActSchema` and `askBatch` describe the host, not the current head.
1228
+ * `ask-batch` applies only to a record-retained head publication; a package head refuses `JOB_REQUEST_INVALID`,
1229
+ * so a consumer checks the publication's mode as well as the flag (#972).
1230
+ */
1160
1231
  export interface JobCapabilitiesV3 extends JobCapabilities {
1161
1232
  readonly recordPublication: true;
1162
1233
  readonly recordActSchema: typeof JOB_RECORD_ACT_SCHEMA;
1234
+ readonly askBatch: true;
1163
1235
  }
1164
1236
 
1165
1237
  export const JOB_CAPABILITIES_V3: JobCapabilitiesV3 = Object.freeze({
1166
1238
  recordPublication: true,
1167
1239
  recordActSchema: JOB_RECORD_ACT_SCHEMA,
1240
+ askBatch: true,
1168
1241
  });
1169
1242
 
1170
1243
  export interface PendingAskV3 extends Omit<JobPendingAsk, 'subject' | 'source'> {
@@ -1206,6 +1279,7 @@ export interface NextValueV3 {
1206
1279
  export interface ResponseValuesV3 {
1207
1280
  readonly publish: PublicationV3;
1208
1281
  readonly ask: PendingAskV3;
1282
+ readonly 'ask-batch': AskBatchValueV3;
1209
1283
  readonly next: NextValueV3;
1210
1284
  readonly close: { readonly status: 'closed'; readonly cursor: JobCursor | null };
1211
1285
  readonly 'fetch-act': ActV3;
@@ -1229,6 +1303,8 @@ export type JobProjectRecord = ProjectRecord;
1229
1303
  export type JobRecordFreeze = RecordFreeze;
1230
1304
  export type JobPublishRequestV3 = PublishRequestV3;
1231
1305
  export type JobAskRequestV3 = AskRequestV3;
1306
+ export type JobAskBatchRequestV3 = AskBatchRequestV3;
1307
+ export type JobAskBatchValueV3 = AskBatchValueV3;
1232
1308
  export type JobNextRequestV3 = NextRequestV3;
1233
1309
  export type JobCloseRequestV3 = CloseRequestV3;
1234
1310
  export type JobAgentRequestV3 = AgentRequestV3;