rig-review 2.10.0 → 2.12.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
@@ -17,6 +17,14 @@ import {
17
17
  } from './job-contract.ts';
18
18
  import { JobError } from './job-store.ts';
19
19
  import type { JobSession } from './job-session.ts';
20
+ import { JOB_COMMENTS_ACT_SCHEMA, type JobComment, type JobCommentAnchor, type JobCommentsAct,
21
+ type SourceV3, type JobRigStill } from './job-contract.ts';
22
+ import { parseFeedback } from './session.ts';
23
+ import { parsePartsIssue } from './parts-comment.ts';
24
+ import { parseStageComment, hasStageComment, projectComments } from './stage-comment.ts';
25
+ import { validatePngCrop, validatePngCropMetadata } from './comment-crops.ts';
26
+ import {parseJobImageSetBinding} from './job-image-set.ts';
27
+ import {parseJobPartsIdentity} from './job-source.ts';
20
28
 
21
29
  export type {
22
30
  JobInterviewJson,
@@ -1181,6 +1189,198 @@ export function parseRecordAct(value: unknown): RecordAct {
1181
1189
  throw new JobError('JOB_ACT_INVALID');
1182
1190
  }
1183
1191
 
1192
+ /** Shared closed object reader for the comments contract; legacy readers retain their rules. */
1193
+ export function commentsObject(value: unknown, keys: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
1194
+ if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) throw new JobError('JOB_ACT_INVALID');
1195
+ return exactObject(value, keys, 'JOB_ACT_INVALID', optional);
1196
+ }
1197
+
1198
+ function commentCrop(value: unknown): void {
1199
+ const crop = commentsObject(value, ['path', 'sha256', 'width', 'height'], ['png']);
1200
+ jobSha(crop.sha256);
1201
+ validatePngCropMetadata(crop as unknown as Parameters<typeof validatePngCropMetadata>[0]);
1202
+ if (Object.hasOwn(crop, 'png')) validatePngCrop(crop as unknown as Parameters<typeof validatePngCrop>[0]);
1203
+ }
1204
+
1205
+ /** Both checkpoint values and pins obey the source's declared checkpoint mapping. */
1206
+ function assertCommentsCheckpointBinding(source: SourceV3, checkpointId: string, planStepId: string): void {
1207
+ if (!source.plan?.steps.some(step => step.id === planStepId) ||
1208
+ 'record' in source && checkpointId !== planStepId) throw new JobError('JOB_ACT_INVALID');
1209
+ const evidence = source.checkpointEvidence?.find(packet => packet.checkpointId === checkpointId);
1210
+ if (evidence && evidence.planStepId !== planStepId) throw new JobError('JOB_ACT_INVALID');
1211
+ }
1212
+
1213
+ function parseCommentAnchor(raw: unknown, text: string, source?: SourceV3 | string): JobCommentAnchor {
1214
+ const item = commentsObject(raw, [], Object.keys(raw && typeof raw === 'object' ? raw : {}));
1215
+ const sourceHash = typeof source === 'string' ? source : source?.sourceHash;
1216
+ if ('schema' in item) {
1217
+ commentsObject(item, ['schema', 'id', 'parts', 'sourceHash', 'rigRegion', 'imageRegion', 'view', 'crop', 'nativeCrop']);
1218
+ const issue = parsePartsIssue({...item, summary: text}, true, false, false);
1219
+ if (issue.crop.png !== undefined) validatePngCrop(issue.crop as Parameters<typeof validatePngCrop>[0]);
1220
+ if (sourceHash && issue.sourceHash !== sourceHash) throw new JobError('JOB_ACT_SOURCE_STALE');
1221
+ if (source && typeof source !== 'string' && !('record' in source)) {
1222
+ if (!source.parts || issue.parts.some(part => !source.parts!.images.some(image =>
1223
+ image.role === 'part' && image.path === `parts/${part.name}.png` && image.sha256 === part.imageHash))) throw new JobError('JOB_ACT_SOURCE_STALE');
1224
+ }
1225
+ const {summary: _summary, ...anchor} = issue;
1226
+ return anchor;
1227
+ }
1228
+ if ('frameStart' in item) {
1229
+ commentsObject(item, ['id', 'frameStart', 'frameEnd', 'target', 'category'], ['context', 'side']);
1230
+ commentsObject(item.target, ['kind', 'name']);
1231
+ jobId(item.id);
1232
+ if ('side' in item && item.side !== 'a' && item.side !== 'b') throw new JobError('JOB_ACT_INVALID');
1233
+ const feedback = parseFeedback({...item, summary: text});
1234
+ const context = feedback.context as Record<string, unknown> | undefined;
1235
+ if (hasStageComment(context?.comment)) {
1236
+ const mark = parseStageComment(context!.comment);
1237
+ validatePngCrop(mark.crop);
1238
+ if (sourceHash && mark.sourceHash !== sourceHash) throw new JobError('JOB_ACT_SOURCE_STALE');
1239
+ if (source && typeof source !== 'string' && !('record' in source) &&
1240
+ mark.viewport !== 'reference' && mark.modelHash !== source.model?.sha256) throw new JobError('JOB_ACT_SOURCE_STALE');
1241
+ }
1242
+ const {summary: _summary, ...anchor} = feedback;
1243
+ return {...anchor, ...('side' in item ? {side: item.side as 'a' | 'b'} : {})};
1244
+ }
1245
+ if ('checkpointId' in item) {
1246
+ commentsObject(item, ['checkpointId', 'planStepId']);
1247
+ const checkpointId = jobId(item.checkpointId), planStepId = jobId(item.planStepId);
1248
+ if (source && typeof source !== 'string') assertCommentsCheckpointBinding(source, checkpointId, planStepId);
1249
+ return {checkpointId, planStepId};
1250
+ }
1251
+ if ('name' in item) {
1252
+ commentsObject(item, ['name'], ['imageRegion', 'crop', 'nativeCrop']);
1253
+ const name = jobText(item.name);
1254
+ if (source && (typeof source === 'string' || source.subject !== 'image-set' ||
1255
+ !source.imageSet.images.some(image => image.name === name))) throw new JobError('JOB_ACT_SOURCE_STALE');
1256
+ if (Object.keys(item).length === 1) return {name};
1257
+ commentsObject(item, ['name', 'imageRegion', 'crop', 'nativeCrop']);
1258
+ const region = commentsObject(item.imageRegion, ['x', 'y', 'width', 'height']);
1259
+ for (const axis of ['x', 'y', 'width', 'height']) jobInteger(region[axis]);
1260
+ if (!region.width || !region.height || Number(region.width) * Number(region.height) > 16777216) throw new JobError('JOB_ACT_INVALID');
1261
+ commentsObject(item.nativeCrop, ['path', 'sha256', 'width', 'height']);
1262
+ commentCrop(item.crop); commentCrop(item.nativeCrop);
1263
+ if ((item.nativeCrop as {width: number}).width !== region.width ||
1264
+ (item.nativeCrop as {height: number}).height !== region.height) throw new JobError('JOB_ACT_INVALID');
1265
+ return structuredClone(item) as unknown as JobCommentAnchor;
1266
+ }
1267
+ throw new JobError('JOB_ACT_INVALID');
1268
+ }
1269
+
1270
+ /** Structural/source-identity decoding only. Original asset freshness remains with the retained-source owner. */
1271
+ export function parseComments(value: unknown, source?: SourceV3 | string): JobComment[] {
1272
+ return asCode(() => {
1273
+ if (!Array.isArray(value) || value.length > 1000) throw new JobError('JOB_ACT_INVALID');
1274
+ const ids = new Set<string>();
1275
+ const comments = value.map(raw => {
1276
+ const item = commentsObject(raw, ['text'], ['anchor']);
1277
+ const text = parseActWords(item.text, 'JOB_ACT_INVALID');
1278
+ if (!text.trim()) throw new JobError('JOB_ACT_INVALID');
1279
+ if (!Object.hasOwn(item, 'anchor')) return {text};
1280
+ const anchor = parseCommentAnchor(item.anchor, text, source);
1281
+ if ('id' in anchor) {
1282
+ if (ids.has(anchor.id)) throw new JobError('JOB_ACT_INVALID');
1283
+ ids.add(anchor.id);
1284
+ }
1285
+ return {text, anchor};
1286
+ });
1287
+ projectComments(comments);
1288
+ return comments;
1289
+ }, 'JOB_ACT_INVALID');
1290
+ }
1291
+
1292
+ function commentsSource(raw: unknown): Exclude<SourceV3, OptionSource> {
1293
+ if (isRecordSource(raw)) {
1294
+ const record = parseRecordSource(raw);
1295
+ if (record.subject !== 'plan') throw new JobError('JOB_ACT_INVALID');
1296
+ return record;
1297
+ }
1298
+ const image = !!raw && typeof raw === 'object' && (raw as {subject?: unknown}).subject === 'image-set';
1299
+ const common = ['sourceHash', 'projectHash', 'package', 'direction', 'optionSet', 'appliedResult', 'plan', 'parts'];
1300
+ const item = commentsObject(raw, image ? [...common, 'subject', 'imageSet', 'imageSetDigest', 'duplicateHashes'] :
1301
+ [...common, 'selector', 'model'], image ? [] : ['checkpointEvidence']);
1302
+ jobSha(item.sourceHash); if (item.projectHash !== null) jobSha(item.projectHash);
1303
+ const pkg = commentsObject(item.package, ['id', 'revision']); jobText(pkg.id); jobText(pkg.revision);
1304
+ for (const key of image ? ['direction'] : ['direction', 'model']) if (item[key] !== null) parseFileRow(item[key], 'JOB_ACT_INVALID');
1305
+ if (!image) parseJobSelector(item.selector);
1306
+ if (item.optionSet !== null) {
1307
+ const set = commentsObject(item.optionSet, ['id', 'sha256']); jobId(set.id); jobSha(set.sha256);
1308
+ }
1309
+ if (item.appliedResult !== null) {
1310
+ const applied = commentsObject(item.appliedResult, ['id', 'modelHash']); jobId(applied.id); jobSha(applied.modelHash);
1311
+ }
1312
+ if (item.plan !== null) parsePlanIdentity(item.plan, 'JOB_ACT_INVALID');
1313
+ if (item.parts !== null) parseJobPartsIdentity(item.parts);
1314
+ if ('checkpointEvidence' in item) {
1315
+ if (!Array.isArray(item.checkpointEvidence)) throw new JobError('JOB_ACT_INVALID');
1316
+ // Validate the declared packet with the existing codec. Actual closure seals remain
1317
+ // with the retained-source owner; a decoder has neither files nor source authority.
1318
+ const declarations = item.checkpointEvidence.map(raw => commentsObject(raw,
1319
+ ['schema', 'checkpointId', 'planStepId', 'tiles', 'table', 'routesText', 'recommendationText']));
1320
+ const subjects = declarations.map(row => ({kind: 'checkpoint' as const, checkpointId: jobId(row.checkpointId), planStepId: jobId(row.planStepId)}));
1321
+ const files = declarations.flatMap(row => {
1322
+ if (!Array.isArray(row.tiles)) throw new JobError('JOB_ACT_INVALID');
1323
+ return [...row.tiles, row.table].map(file => parseFileRow(
1324
+ {path: (file as JobFileIdentity)?.path, sha256: (file as JobFileIdentity)?.sha256}, 'JOB_ACT_INVALID'));
1325
+ });
1326
+ checkpointEvidenceFields(item, item.plan as JobPlanIdentity | null, subjects, files);
1327
+ }
1328
+ if (image) parseJobImageSetBinding({imageSet: item.imageSet, imageSetDigest: item.imageSetDigest, duplicateHashes: item.duplicateHashes});
1329
+ return structuredClone(item) as unknown as Exclude<SourceV3, OptionSource>;
1330
+ }
1331
+
1332
+ /** Public @6 decoder. Current UI finalizers continue to emit their existing versions. */
1333
+ export function parseCommentsAct(raw: unknown): JobCommentsAct {
1334
+ return asCode(() => {
1335
+ const item = commentsObject(raw, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value'], ['still']);
1336
+ if (item.schema !== JOB_COMMENTS_ACT_SCHEMA) throw new JobError('JOB_ACT_INVALID');
1337
+ for (const key of ['actId', 'jobId', 'askId', 'publicationId']) jobId(item[key]);
1338
+ parseHumanAuthority(item.authority, 'JOB_ACT_INVALID');
1339
+ if (typeof item.at !== 'string' || !Number.isFinite(Date.parse(item.at))) throw new JobError('JOB_ACT_INVALID');
1340
+ const source = commentsSource(item.source);
1341
+ const fields: Record<string, readonly string[]> = {
1342
+ checkpoint: ['checkpointId', 'planStepId', 'outcome', 'comments'],
1343
+ 'parts-verdict': ['verdict', 'comments'], 'review-verdict': ['stage', 'verdict', 'comments'],
1344
+ signoff: ['stage', 'decision', 'comments'], reopen: ['stage', 'comments'],
1345
+ };
1346
+ const keys = typeof item.kind === 'string' && Object.hasOwn(fields, item.kind) ? fields[item.kind] : undefined;
1347
+ if (!keys) throw new JobError('JOB_ACT_INVALID');
1348
+ if (source.subject === 'image-set' && item.kind !== 'review-verdict') throw new JobError('JOB_ACT_INVALID');
1349
+ const value = commentsObject(item.value, keys);
1350
+ const comments = parseComments(value.comments, source);
1351
+ if (comments.some(comment => comment.anchor && 'side' in comment.anchor)) throw new JobError('JOB_ACT_INVALID');
1352
+ if (item.kind === 'checkpoint') {
1353
+ const checkpointId = jobId(value.checkpointId), planStepId = jobId(value.planStepId);
1354
+ if (typeof value.outcome !== 'string' || !['pass', 'fail'].includes(value.outcome)) throw new JobError('JOB_ACT_INVALID');
1355
+ assertCommentsCheckpointBinding(source, checkpointId, planStepId);
1356
+ } else if (item.kind === 'parts-verdict') {
1357
+ if ('record' in source || source.subject === 'image-set' || source.selector?.kind !== 'draft' || !source.parts || !source.projectHash ||
1358
+ typeof value.verdict !== 'string' || !['approved', 'changes-requested'].includes(value.verdict)) throw new JobError('JOB_ACT_INVALID');
1359
+ const issues = comments.filter(comment => comment.anchor && 'schema' in comment.anchor).length;
1360
+ if ((value.verdict === 'approved') !== (issues === 0)) throw new JobError('JOB_ACT_INVALID');
1361
+ } else if (item.kind === 'review-verdict') {
1362
+ if ('record' in source || typeof value.verdict !== 'string' || !['pending', 'approved', 'changes-requested'].includes(value.verdict)) throw new JobError('JOB_ACT_INVALID');
1363
+ if (source.subject === 'image-set' ? value.stage !== 'image-review' :
1364
+ !source.model || (value.stage === 'rig-review' ? source.selector?.kind !== 'rig' : value.stage !== 'direction-review' || source.selector?.kind !== 'post' || !source.direction)) throw new JobError('JOB_ACT_INVALID');
1365
+ } else {
1366
+ const stage = jobId(value.stage);
1367
+ if (item.kind === 'signoff' && value.decision !== 'approved') throw new JobError('JOB_ACT_INVALID');
1368
+ if (item.kind === 'reopen' && !('record' in source)) throw new JobError('JOB_ACT_INVALID');
1369
+ if (item.kind === 'signoff' && JOB_PLAN_BOUND_SIGNOFF_STAGES.includes(stage as RecordSignoffStage) && !source.plan?.steps.length) throw new JobError('JOB_ACT_INVALID');
1370
+ }
1371
+ if ('record' in source) validateRecordAskSubject(item.kind === 'checkpoint' ? {kind: item.kind, checkpointId: value.checkpointId} :
1372
+ {kind: item.kind, stage: value.stage}, source);
1373
+ const rig = item.kind === 'review-verdict' && value.stage === 'rig-review';
1374
+ if (rig) {
1375
+ const still = commentsObject(item.still, ['path', 'sha256', 'camera', 'frame'], ['animation']);
1376
+ if (still.path !== jobSha(still.sha256) + '.png' || still.camera !== 'fixed' ||
1377
+ (still.frame === 'setup' ? 'animation' in still : typeof still.frame !== 'number' || !Number.isFinite(still.frame) ||
1378
+ still.frame < 0 || typeof still.animation !== 'string' || !still.animation)) throw new JobError('JOB_ACT_INVALID');
1379
+ } else if ('still' in item) throw new JobError('JOB_ACT_INVALID');
1380
+ return {...structuredClone(item), source, value: {...value, comments}} as unknown as JobCommentsAct;
1381
+ }, 'JOB_ACT_INVALID');
1382
+ }
1383
+
1184
1384
  export async function jobBody(request: Request, maximum = jobBodyLimit): Promise<unknown> {
1185
1385
  if (!/^application\/json(?:\s*;|$)/i.test(request.headers.get('content-type') ?? '')) {
1186
1386
  throw new JobError('JOB_REQUEST_INVALID');
package/src/job-cli.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import {closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync} from 'node:fs';
3
3
  import {join} from 'node:path';
4
- import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit,
5
- type JobAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
- import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest } from './job-api.ts';
4
+ import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_ENABLED_ACT_KINDS, jobRawActMediaType, jobStillByteLimit,
5
+ type JobAct, type JobCommentsAct, type JobAgentRequest, type JobNextRequest, type JobNextValue } from './job-contract.ts';
6
+ import { assertJobApiSchema, jobFailure, jobHash, jobId, jobInteger, jobObject, jobWaitLimitMs, parseJobRequest, parseCommentsAct } from './job-api.ts';
7
7
  import { JobError } from './job-store.ts';
8
8
  import {validatePngBytes} from './comment-crops.ts';
9
9
  import {destinationDirectory} from './destination-directory.ts';
@@ -145,11 +145,18 @@ async function consumerBytes(stream: ReadableStream<Uint8Array> | null, maximum:
145
145
  }
146
146
  }
147
147
 
148
- function parseConsumerAct(bytes: Buffer, job: string, actId: string): JobAct {
148
+ type ConsumerAct = JobAct | JobCommentsAct;
149
+
150
+ function parseConsumerAct(bytes: Buffer, job: string, actId: string): ConsumerAct {
149
151
  let value: unknown;
150
152
  try { value = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes)); }
151
153
  catch { throw new JobError('JOB_REQUEST_INVALID'); }
152
154
  const act = jobObject(value, ['schema', 'actId', 'jobId', 'askId', 'publicationId', 'kind', 'authority', 'at', 'source', 'value', 'still']);
155
+ if (act.schema === JOB_COMMENTS_ACT_SCHEMA) {
156
+ const comments = parseCommentsAct(act);
157
+ if (comments.jobId !== job || comments.actId !== actId) throw new JobError('JOB_ACT_INVALID');
158
+ return comments;
159
+ }
153
160
  if (act.jobId !== job || act.actId !== actId ||
154
161
  (act.schema !== JOB_ACT_SCHEMA && act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && act.schema !== JOB_PARTS_VERDICT_ACT_SCHEMA)) {
155
162
  throw new JobError('JOB_ACT_INVALID');
@@ -178,7 +185,8 @@ function unlinkOwned(path: string, identity: {dev: number; ino: number}): void {
178
185
  }
179
186
  }
180
187
 
181
- function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAct, destination: string | undefined, options: JobCLIOptions): void {
188
+ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: ConsumerAct, destination: string | undefined, options: JobCLIOptions): void {
189
+ const still = 'still' in act ? act.still : undefined;
182
190
  let temporary: string | undefined;
183
191
  let temporaryIdentity: {dev: number; ino: number} | undefined;
184
192
  let installed: string | undefined;
@@ -188,7 +196,7 @@ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAc
188
196
  let lockDescriptor: number | undefined;
189
197
  let emitted = 0;
190
198
  try {
191
- if (png && destination && act.schema === JOB_RIG_REVIEW_ACT_SCHEMA) {
199
+ if (png && destination && still) {
192
200
  const directory = destinationDirectory(destination, 'JOB_STILL_OUTPUT_FAILED', false);
193
201
  const directoryDescriptor = openSync(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | constants.O_NOFOLLOW);
194
202
  try {
@@ -204,13 +212,13 @@ function outputConsumerAct(actBytes: Buffer, png: Buffer | undefined, act: JobAc
204
212
  }
205
213
  throw error;
206
214
  }
207
- const target = join(directory, act.still.path);
215
+ const target = join(directory, still.path);
208
216
  let existing = false;
209
217
  try {
210
218
  const descriptor = openSync(target, constants.O_RDONLY | constants.O_NOFOLLOW);
211
219
  try {
212
220
  const info = fstatSync(descriptor);
213
- if (!info.isFile() || info.size > jobStillByteLimit || jobHash(readFileSync(descriptor)) !== act.still.sha256) {
221
+ if (!info.isFile() || info.size > jobStillByteLimit || jobHash(readFileSync(descriptor)) !== still.sha256) {
214
222
  throw new JobError('JOB_STILL_OUTPUT_FAILED');
215
223
  }
216
224
  existing = true;
@@ -307,14 +315,15 @@ async function fetchActCommand(args: readonly string[], options: JobCLIOptions):
307
315
  }
308
316
  const bytes = await read(jobRawActMediaType, 512 * 1024);
309
317
  const act = parseConsumerAct(bytes, job, actId);
318
+ const still = 'still' in act ? act.still : undefined;
310
319
  const destination = values.get('still-out');
311
- if (act.schema === JOB_RIG_REVIEW_ACT_SCHEMA && destination === undefined) throw new JobError('JOB_STILL_OUTPUT_FAILED');
320
+ if (still && destination === undefined) throw new JobError('JOB_STILL_OUTPUT_FAILED');
312
321
  let png: Buffer | undefined;
313
322
  if (destination !== undefined) {
314
- if (act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA) throw new JobError('JOB_STILL_UNAVAILABLE');
323
+ if (!still) throw new JobError('JOB_STILL_UNAVAILABLE');
315
324
  png = await read('image/png', jobStillByteLimit);
316
325
  try {
317
- if (png.length < 33 || jobHash(png) !== act.still.sha256) throw new Error('hash');
326
+ if (png.length < 33 || jobHash(png) !== still.sha256) throw new Error('hash');
318
327
  validatePngBytes(png, png.readUInt32BE(16), png.readUInt32BE(20));
319
328
  } catch { throw new JobError('JOB_STILL_CAPTURE_FAILED'); }
320
329
  }
@@ -13,6 +13,10 @@
13
13
 
14
14
  import type { JobPublicationReader } from './job-source.ts';
15
15
  import type { PartsIssue } from './parts-comment.ts';
16
+ import type { Feedback, ReviewSession } from './session.ts';
17
+ import type { CompareFeedback, CompareSession } from './compare-session.ts';
18
+ import type { MarkRegion } from './stage-comment.ts';
19
+ import type { PartsVerdict } from './parts-view.ts';
16
20
 
17
21
  export const JOB_API_SCHEMA = 'rig-review/job-api@2' as const;
18
22
  export const JOB_API_V3_SCHEMA = 'rig-review/job-api@3' as const;
@@ -23,6 +27,50 @@ export const JOB_RIG_REVIEW_ACT_SCHEMA = 'rig-review/act@3' as const;
23
27
  export const JOB_RECORD_ACT_SCHEMA = 'rig-review/act@4' as const;
24
28
  /** New parts verdicts only. Historical @2 parts-verdict acts remain readable. */
25
29
  export const JOB_PARTS_VERDICT_ACT_SCHEMA = 'rig-review/act@5' as const;
30
+ /** Read/parse contract only until the Create comments consumer is published. */
31
+ export const JOB_COMMENTS_ACT_SCHEMA = 'rig-review/act@6' as const;
32
+ export const REVIEW_COMMENTS_SESSION_SCHEMA = 'rig-review-session/2' as const;
33
+ export const REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA = 'rig-review-compare-session/2' as const;
34
+ export const PARTS_COMMENTS_VERDICT_SCHEMA = 'rig-review-parts-verdict/5' as const;
35
+
36
+ export type JobCommentFeedbackAnchor = Omit<Feedback, 'summary'> | Omit<CompareFeedback, 'summary'>;
37
+ export type JobCommentPartsAnchor = Omit<PartsIssue, 'summary'>;
38
+ export type JobCommentImageAnchor = { readonly name: string } | {
39
+ readonly name: string;
40
+ readonly imageRegion: MarkRegion;
41
+ readonly crop: PartsIssue['crop'];
42
+ readonly nativeCrop: NonNullable<PartsIssue['nativeCrop']>;
43
+ };
44
+ export type JobCommentAnchor = JobCommentFeedbackAnchor | JobCommentPartsAnchor | JobCommentImageAnchor
45
+ | { readonly checkpointId: string; readonly planStepId: string };
46
+ export interface JobComment { readonly text: string; readonly anchor?: JobCommentAnchor }
47
+ export interface JobCommentsActValues {
48
+ readonly checkpoint: { readonly checkpointId: string; readonly planStepId: string;
49
+ readonly outcome: 'pass' | 'fail'; readonly comments: readonly JobComment[] };
50
+ readonly 'parts-verdict': { readonly verdict: 'approved' | 'changes-requested'; readonly comments: readonly JobComment[] };
51
+ readonly 'review-verdict': { readonly stage: JobReviewStage; readonly verdict: JobVerdict; readonly comments: readonly JobComment[] };
52
+ readonly signoff: { readonly stage: string; readonly decision: 'approved'; readonly comments: readonly JobComment[] };
53
+ readonly reopen: { readonly stage: string; readonly comments: readonly JobComment[] };
54
+ }
55
+ export type JobCommentsAct = {
56
+ [Kind in keyof JobCommentsActValues]: {
57
+ readonly schema: typeof JOB_COMMENTS_ACT_SCHEMA;
58
+ readonly actId: string; readonly jobId: string; readonly askId: string; readonly publicationId: string;
59
+ readonly kind: Kind; readonly authority: JobHumanAuthority; readonly at: string;
60
+ readonly source: Exclude<SourceV3, OptionSource>; readonly value: JobCommentsActValues[Kind]; readonly still?: JobRigStill;
61
+ }
62
+ }[keyof JobCommentsActValues];
63
+ export type ReviewCommentsSession = Omit<ReviewSession, 'schema' | 'feedback' | 'checkpoints'> & {
64
+ schema: typeof REVIEW_COMMENTS_SESSION_SCHEMA;
65
+ checkpoints: Record<string, { outcome: 'pending' | 'pass' | 'fail' }>;
66
+ comments: JobComment[];
67
+ };
68
+ export type CompareCommentsSession = Omit<CompareSession, 'schema' | 'feedback'> & {
69
+ schema: typeof REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA; comments: JobComment[];
70
+ };
71
+ export type PartsCommentsVerdict = Omit<PartsVerdict, 'schema' | 'issues'> & {
72
+ schema: typeof PARTS_COMMENTS_VERDICT_SCHEMA; comments: JobComment[];
73
+ };
26
74
  export const JOB_PANEL_COMPOSITION_SCHEMA = 'rig-review/panels@1' as const;
27
75
 
28
76
  export type PanelSlot = 'left' | 'stage' | 'toolbar' | 'side';
@@ -178,6 +226,79 @@ export interface JobPlanIdentity {
178
226
  readonly steps: readonly JobPlanStepIdentity[];
179
227
  }
180
228
 
229
+ /** Ephemeral owner metadata, projected by the daemon from the sealed project. */
230
+ export const JOB_PLAN_TEXT_SCHEMA = 'rig-review/job-plan-text@1' as const;
231
+ export const JOB_PLAN_TEXT_FIELDS = ['does', 'produces', 'bar', 'rests_on'] as const;
232
+ export type JobPlanTextField = typeof JOB_PLAN_TEXT_FIELDS[number];
233
+ export interface JobPlanTextStep {
234
+ readonly id: string;
235
+ readonly hash: string;
236
+ does?: string;
237
+ produces?: string;
238
+ bar?: string;
239
+ rests_on?: readonly string[];
240
+ readonly issues: {field: JobPlanTextField; reason: 'absent' | 'invalid' | 'limit'}[];
241
+ }
242
+ export const JOB_PLAN_TEXT_UNAVAILABLE = [
243
+ 'PLAN_TEXT_RECORD_UNAVAILABLE', 'PLAN_TEXT_RECORD_UNSUPPORTED', 'PLAN_TEXT_STEPS_ABSENT',
244
+ 'PLAN_TEXT_STEPS_INVALID', 'PLAN_TEXT_MAPPING_UNAVAILABLE', 'PLAN_TEXT_LIMIT',
245
+ ] as const;
246
+ export type JobPlanTextProjection = {
247
+ readonly schema: typeof JOB_PLAN_TEXT_SCHEMA;
248
+ readonly record: {readonly path: 'project.json'; readonly sha256: string};
249
+ readonly status: 'projected';
250
+ readonly steps: readonly JobPlanTextStep[];
251
+ } | {
252
+ readonly schema: typeof JOB_PLAN_TEXT_SCHEMA;
253
+ readonly record: {readonly path: 'project.json'; readonly sha256: string} | null;
254
+ readonly status: 'unavailable';
255
+ readonly reason: typeof JOB_PLAN_TEXT_UNAVAILABLE[number];
256
+ };
257
+
258
+ /** Closed delivery grammar. Field contents have the normal daemon's authority. */
259
+ export function parseJobPlanTextProjection(value: unknown): JobPlanTextProjection {
260
+ const fail = (): never => {throw new Error('PLAN_TEXT_METADATA_INVALID');};
261
+ const object = (input: unknown, keys: readonly string[]): Record<string, unknown> => {
262
+ if (!input || typeof input !== 'object' || Array.isArray(input) ||
263
+ Object.keys(input).some(key => !keys.includes(key))) return fail();
264
+ return input as Record<string, unknown>;
265
+ };
266
+ const envelope = object(value, ['schema', 'record', 'status', 'steps', 'reason']);
267
+ if (envelope.schema !== JOB_PLAN_TEXT_SCHEMA || !Object.hasOwn(envelope, 'record') ||
268
+ new TextEncoder().encode(JSON.stringify(value)).length > 512 * 1024) return fail();
269
+ if (envelope.record !== null) {
270
+ const record = object(envelope.record, ['path', 'sha256']);
271
+ if (record.path !== 'project.json' || typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(record.sha256)) return fail();
272
+ }
273
+ if (envelope.status === 'unavailable') {
274
+ if (Object.hasOwn(envelope, 'steps') || !(JOB_PLAN_TEXT_UNAVAILABLE as readonly unknown[]).includes(envelope.reason)) return fail();
275
+ return value as JobPlanTextProjection;
276
+ }
277
+ if (envelope.status !== 'projected' || envelope.record === null || Object.hasOwn(envelope, 'reason') ||
278
+ !Array.isArray(envelope.steps) || envelope.steps.length > 4096) return fail();
279
+ const ids = new Set<string>();
280
+ for (const raw of envelope.steps) {
281
+ const row = object(raw, ['id', 'hash', ...JOB_PLAN_TEXT_FIELDS, 'issues']);
282
+ if (typeof row.id !== 'string' || row.id.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(row.id) ||
283
+ ids.has(row.id) || typeof row.hash !== 'string' || !/^[a-f0-9]{64}$/.test(row.hash) || !Array.isArray(row.issues)) return fail();
284
+ ids.add(row.id);
285
+ const missing = JOB_PLAN_TEXT_FIELDS.filter(field => !Object.hasOwn(row, field));
286
+ if (row.issues.length !== missing.length) return fail();
287
+ row.issues.forEach((rawIssue, index) => {
288
+ const issue = object(rawIssue, ['field', 'reason']);
289
+ if (issue.field !== missing[index] || typeof issue.reason !== 'string' || !['absent', 'invalid', 'limit'].includes(issue.reason)) fail();
290
+ });
291
+ for (const field of JOB_PLAN_TEXT_FIELDS) {
292
+ if (!Object.hasOwn(row, field)) continue;
293
+ const content = row[field];
294
+ if (field === 'rests_on') {
295
+ if (!Array.isArray(content) || content.length > 4096 || content.some(item => typeof item !== 'string')) return fail();
296
+ } else if (typeof content !== 'string') return fail();
297
+ }
298
+ }
299
+ return value as JobPlanTextProjection;
300
+ }
301
+
181
302
  /** Literal work-root-relative manifest path, validated at runtime. */
182
303
  export type JobPartsManifestPath = string;
183
304
  /** Literal path relative to the bound manifest directory. */
package/src/job-front.ts CHANGED
@@ -3,7 +3,7 @@ import {checkpointEvidenceMetadata, readCheckpointEvidenceBytes} from './job-che
3
3
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobHostPorts, type JobId, type JobPublicationMode, type JobResult, type JobReviewerBinding } from './job-contract.ts';
4
4
  import { createJobHostPorts, jobBody, jobHash, jobId, jobObject, jobPartsEnumeratorVersion } from './job-api.ts';
5
5
  import { JobSession } from './job-session.ts';
6
- import { assertJobRoot, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
6
+ import { assertJobRoot, assertRetainedSnapshotIntact, captureJobRoot, planTextMetadata, isRetainedRecordSource, type JobRootIdentity } from './job-source.ts';
7
7
  import type { JobWorkerOptions } from './job-worker.ts';
8
8
  import { JobError, JobStore } from './job-store.ts';
9
9
  import { loadReview, safeFile, packagePath, type ReviewPackage } from './manifest.ts';
@@ -265,9 +265,13 @@ export function retainedPublicationRoutes(session: JobSession) {
265
265
  if (key !== display.publication.instanceKey) return failure('JOB_DISPLAY_MISMATCH', 409);
266
266
  if (crop && session.status().publication?.publicationId !== publicationId)
267
267
  return failure('JOB_ACT_SOURCE_STALE', 409);
268
- const json = (value: unknown) => new Response(request.method === 'HEAD' ? null : JSON.stringify(value), {
269
- headers: {...headers, 'Content-Type': 'application/json'},
270
- });
268
+ const json = (value: Record<string, unknown>) => {
269
+ const payload = path === 'api/review' ? planTextMetadata(retained, value) : value;
270
+ const body = JSON.stringify(payload);
271
+ return new Response(request.method === 'HEAD' ? null : body, {
272
+ headers: {...headers, 'Content-Type': 'application/json'},
273
+ });
274
+ };
271
275
  const sealedFile = async (relativePath: string) => {
272
276
  const seal = retained.seals.find(file => file.path === relativePath);
273
277
  if (!seal) return failure('JOB_SOURCE_UNRETAINABLE', 404);
@@ -442,7 +446,7 @@ export function retainedPublicationRoutes(session: JobSession) {
442
446
  const code = error instanceof JobError ? error.code :
443
447
  error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')
444
448
  ? 'PARTS_COMMENT_STALE_SOURCE' : 'JOB_SOURCE_MISMATCH';
445
- const message = error instanceof JobError && /^CHECKPOINT_EVIDENCE_[A-Z_]+$/.test(error.message)
449
+ const message = error instanceof JobError && /^(CHECKPOINT_EVIDENCE|PLAN_TEXT)_[A-Z_]+$/.test(error.message)
446
450
  ? error.message : undefined;
447
451
  return failure(code, errorStatus[code as JobErrorCode] ?? 409, undefined, message);
448
452
  }
package/src/job-host.ts CHANGED
@@ -23,6 +23,20 @@ export type {
23
23
  JobRootIdentity,
24
24
  } from './job-source.ts';
25
25
  export {parseRecordAct} from './job-api.ts';
26
+ export {parseCommentsAct} from './job-api.ts';
27
+ export {projectComments} from './stage-comment.ts';
28
+ export {parseCommentsSession} from './session.ts';
29
+ export {parseCommentsCompareSession} from './compare-session.ts';
30
+ export {parseCommentsPartsVerdict} from './parts-view.ts';
31
+ export {projectSelectedCommentsFeedback} from './feedback-export.ts';
32
+ export {
33
+ JOB_COMMENTS_ACT_SCHEMA, REVIEW_COMMENTS_SESSION_SCHEMA,
34
+ REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA, PARTS_COMMENTS_VERDICT_SCHEMA,
35
+ } from './job-contract.ts';
36
+ export type {
37
+ JobComment, JobCommentAnchor, JobCommentFeedbackAnchor, JobCommentPartsAnchor, JobCommentImageAnchor,
38
+ JobCommentsAct, JobCommentsActValues, ReviewCommentsSession, CompareCommentsSession, PartsCommentsVerdict,
39
+ } from './job-contract.ts';
26
40
  export {prepareJobRecordAct} from './job-act.ts';
27
41
  export {
28
42
  JOB_CAPABILITIES,
@@ -1,5 +1,5 @@
1
1
  import type {JobImageSetInput, JobImageSourceBinding} from './job-contract.ts';
2
- import {jobHash, jobObject, jobPath, jobSha, jobText} from './job-api.ts';
2
+ import {exactObject, jobHash, jobObject, jobPath, jobSha, jobText, requestDigest} from './job-api.ts';
3
3
  import {JobError} from './job-store.ts';
4
4
 
5
5
  /** Check discovery before sending an image ask, including against older hubs. */
@@ -10,9 +10,11 @@ export function assertJobImageSetCapability(capabilities: unknown): void {
10
10
  }
11
11
  }
12
12
 
13
- /** Hash the actual bytes. Array order and exact Unicode strings are significant. */
14
- export function prepareJobImageSet(input: JobImageSetInput,
15
- readBytes: (path: string) => Uint8Array): Pick<JobImageSourceBinding, 'imageSet' | 'imageSetDigest' | 'duplicateHashes'> {
13
+ type ImageSetBinding = Pick<JobImageSourceBinding, 'imageSet' | 'imageSetDigest' | 'duplicateHashes'>;
14
+ type ImageSetRead = {kind: 'bytes'; readBytes: (path: string) => Uint8Array} | {kind: 'sealed'};
15
+
16
+ /** One declared-shape/digest codec; only byte preparation reads and hashes assets. */
17
+ function imageSetBinding(input: JobImageSetInput, read: ImageSetRead): ImageSetBinding {
16
18
  try { jobObject(input, ['purpose', 'images']); }
17
19
  catch { throw new JobError('JOB_IMAGE_SET_INVALID'); }
18
20
  if (input.purpose !== 'plate-adoption' || !Array.isArray(input.images) ||
@@ -33,11 +35,17 @@ export function prepareJobImageSet(input: JobImageSetInput,
33
35
  if (names.has(name)) throw new JobError('JOB_IMAGE_SET_DUPLICATE_NAME');
34
36
  if (paths.has(path)) throw new JobError('JOB_IMAGE_SET_DUPLICATE_PATH');
35
37
  names.add(name); paths.add(path);
36
- let bytes: Uint8Array;
37
- try { bytes = readBytes(path); }
38
- catch { throw new JobError('JOB_IMAGE_SET_PATH_REFUSED'); }
39
- const sha256 = jobHash(bytes);
40
- if (raw.sha256 !== undefined && raw.sha256 !== sha256) throw new JobError('JOB_SOURCE_MISMATCH');
38
+ let sha256: string;
39
+ if (read.kind === 'bytes') {
40
+ let bytes: Uint8Array;
41
+ try { bytes = read.readBytes(path); }
42
+ catch { throw new JobError('JOB_IMAGE_SET_PATH_REFUSED'); }
43
+ sha256 = jobHash(bytes);
44
+ if (raw.sha256 !== undefined && raw.sha256 !== sha256) throw new JobError('JOB_SOURCE_MISMATCH');
45
+ } else {
46
+ try { sha256 = jobSha(raw.sha256); }
47
+ catch { throw new JobError('JOB_IMAGE_SET_INVALID'); }
48
+ }
41
49
  const group = hashes.get(sha256) ?? [];
42
50
  group.push(name); hashes.set(sha256, group);
43
51
  return {role: raw.role, name, path, sha256};
@@ -48,3 +56,18 @@ export function prepareJobImageSet(input: JobImageSetInput,
48
56
  return {imageSet: {purpose: input.purpose, images}, imageSetDigest: jobHash(JSON.stringify(canonical)),
49
57
  duplicateHashes: [...hashes].filter(([, names]) => names.length > 1).map(([sha256, names]) => ({names, sha256}))};
50
58
  }
59
+
60
+ /** Hash the actual bytes. Array order and exact Unicode strings are significant. */
61
+ export function prepareJobImageSet(input: JobImageSetInput,
62
+ readBytes: (path: string) => Uint8Array): ImageSetBinding {
63
+ return imageSetBinding(input, {kind: 'bytes', readBytes});
64
+ }
65
+
66
+ /** Decode declared sealed identities without a byte reader or a native freshness claim. */
67
+ export function parseJobImageSetBinding(value: unknown): ImageSetBinding {
68
+ const raw = exactObject(value, ['imageSet', 'imageSetDigest', 'duplicateHashes'], 'JOB_IMAGE_SET_INVALID');
69
+ const binding = imageSetBinding(raw.imageSet as JobImageSetInput, {kind: 'sealed'});
70
+ if (jobSha(raw.imageSetDigest) !== binding.imageSetDigest ||
71
+ requestDigest(raw.duplicateHashes) !== requestDigest(binding.duplicateHashes)) throw new JobError('JOB_IMAGE_SET_INVALID');
72
+ return binding;
73
+ }
@@ -1,14 +1,14 @@
1
1
  import { randomBytes, randomUUID } from 'node:crypto';
2
2
  import { dirname, isAbsolute, join, relative, sep } from 'node:path';
3
3
  import {
4
- JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
4
+ JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ACT_SCHEMA, JOB_COMMENTS_ACT_SCHEMA, JOB_PARTS_VERDICT_ACT_SCHEMA, JOB_RIG_REVIEW_ACT_SCHEMA, JOB_RECORD_READER_ID, jobStillByteLimit, JOB_CAPABILITIES, JOB_CAPABILITIES_V3, JOB_ENABLED_ACT_KINDS,
5
5
  type ActV3, type AgentRequestV3, type EventV3, type JobPartsEnumerator, type JobAct, type JobAgentRequest, type JobDisplayAcknowledgment,
6
6
  type JobDisplayPublication, type JobDisplayPublicationV3, type JobDisplayReceipt, type JobEvent, type JobFetchActRequest, type JobFetchActRequestV3,
7
7
  type JobNextValue, type JobPendingAsk, type JobPublication, type JobPublicationMode, type JobReviewerBinding,
8
8
  type NextValueV3, type PendingAskV3, type PublicationV3, type RecordPublicationReader, type RecordSubject, type StatusV3,
9
9
  } from './job-contract.ts';
10
10
  import { bindJobAsk, bindJobRecordAsk, finalizeJobAct, parseUISubmission, prepareJobRecordAct, prepareJobStill } from './job-act.ts';
11
- import { isRecordSource, parseRecordSource, jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
11
+ import { isRecordSource, parseRecordSource, parseCommentsAct, jobApiSchemaForMode, jobHash, jobPartsEnumeratorVersion, jobWaitLimitMs, requestDigest, sameCapability } from './job-api.ts';
12
12
  import {
13
13
  assertStoredCheckpointEvidence, assertJobRoot, assertJobSourceCurrent, assertRetainedSnapshotIntact, captureJobRoot, isRetainedRecordSource, prepareJobSource, jobSnapshotHash, removeOwnedJobSnapshot, verifyJobRecordSourceFresh,
14
14
  type JobPublicationReader, type JobRetainedSource, type JobRetainedSourceV3, type JobRootIdentity,
@@ -602,17 +602,22 @@ export class JobSession {
602
602
  readActExport(actId: string, png: boolean): Buffer {
603
603
  const current = this.current();
604
604
  if (!current.active) throw new JobError('JOB_CLOSED');
605
- const act = current.data.acts[actId];
606
- if (!act) throw new JobError('JOB_ACT_UNKNOWN');
607
- if (act.schema !== JOB_RIG_REVIEW_ACT_SCHEMA) {
605
+ const storedAct = current.data.acts[actId];
606
+ if (!storedAct) throw new JobError('JOB_ACT_UNKNOWN');
607
+ // Validation must not replace the stored representation or reorder its keys.
608
+ if ((storedAct as {schema: string}).schema === JOB_COMMENTS_ACT_SCHEMA) parseCommentsAct(storedAct);
609
+ const still = 'still' in storedAct ? storedAct.still : undefined;
610
+ const actBytes = Buffer.from(JSON.stringify(storedAct));
611
+ if (storedAct.schema !== JOB_RIG_REVIEW_ACT_SCHEMA && !still) {
608
612
  if (png) throw new JobError('JOB_STILL_UNAVAILABLE');
609
- return Buffer.from(JSON.stringify(act));
613
+ return actBytes;
610
614
  }
615
+ if (!still) throw new JobError('JOB_STILL_CAPTURE_FAILED');
611
616
  const stored = this.store.readStill(this.jobId, actId);
612
617
  if (!stored || stored.png.byteLength > jobStillByteLimit || stored.actBytes.byteLength > maximumEventBytes ||
613
- stored.sha256 !== act.still.sha256 || jobHash(stored.png) !== act.still.sha256 ||
614
- act.still.path !== act.still.sha256 + '.png' ||
615
- !Buffer.from(stored.actBytes).equals(Buffer.from(JSON.stringify(act)))) {
618
+ stored.sha256 !== still.sha256 || jobHash(stored.png) !== still.sha256 ||
619
+ still.path !== still.sha256 + '.png' ||
620
+ !Buffer.from(stored.actBytes).equals(actBytes)) {
616
621
  throw new JobError('JOB_STILL_CAPTURE_FAILED');
617
622
  }
618
623
  return Buffer.from(png ? stored.png : stored.actBytes);