@rig-c/review 2.9.0 → 2.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.
@@ -1216,12 +1216,147 @@ The manifest and complete retained image rows enter the composite source hash. L
1216
1216
  | `PublishResultV3` | `{kind, path, selector}` (`package`), `{kind, questionId, setId}` (`option-set`), `{kind}` (`plan`) |
1217
1217
  | `RecordFreeze` | `{kind: 'producer-held', holdId, record: {path: 'project.json', sha256}}` |
1218
1218
  | `RecordSubject` | `{kind: 'interview-picks', questionId, setId}`, `{kind: 'checkpoint', checkpointId}`, `{kind: 'signoff', stage}` (`plan-approved`, `rigging-interview`, `post-interview`), `{kind: 'reopen', stage}` |
1219
- | `RecordPublishedContext` | `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']` |
1219
+ | `RecordPublishedContext` | Required `['label', 'parts', 'inputs', 'files', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
1220
1220
  | `RecordPartsIdentity` | `['name', 'version', 'integrity']` |
1221
- | `RecordSource` | `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']` |
1222
- | `rig-review-job-record-source/1` | `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']` |
1221
+ | `RecordSource` | Required `['sourceHash', 'projectHash', 'record', 'inputs', 'files', 'subject', 'selection', 'optionSet', 'optionSetFile', 'plan', 'subjects']`, optional `checkpointEvidence` on plans |
1222
+ | `rig-review-job-record-source/1` | Required `['schema', 'record', 'selection', 'inputs', 'optionSet', 'optionSetFile', 'plan', 'subjects', 'files']`, optional `checkpointEvidence` on plans |
1223
1223
  | `rig-review-job-record-instance/1` | `['schema', 'fingerprint', 'sourceHash']` |
1224
1224
 
1225
1225
  The read-only official reader returns the six-key `RecordPublishedContext` with producer-sealed `parts`. `prepareJobRecordSource` runs `phase: 'inventory'` on the immutable source root (re-verifying `project.json` identity before and after each reader phase and before mapping generic reader failures so mid-read record movement reports `JOB_RECORD_MOVED` / `JOB_SOURCE_MISMATCH` rather than `JOB_RECORD_INCOMPLETE`) and retains the sorted, duplicate-free `inventory.files` closure into an owned snapshot (`project.json` within 8 MiB, at most 4,096 regular non-symlink files, 64 MiB per file and 256 MiB total bytes). It then calls `phase: 'retained'` on the snapshot root with `parts: inventory.parts` forwarded unchanged and requires `assertEqualRecordContexts(inventory, retainedContext)`. Before ask or finalize, `verifyJobRecordSourceFresh` re-runs `phase: 'inventory'`, rejects any `inventory.parts` drift against the originally sealed `retained.context.parts` (`JOB_SOURCE_MISMATCH` on ask and `JOB_ACT_SOURCE_STALE` on finalize) before invoking `phase: 'retained'`, and forwards the sealed `retained.context.parts` unchanged when equal; synchronous `store.update` commit re-verifies source and retained snapshot integrity before persisting. Missing reader or contract tokens (`CREATE_PUBLICATION_CONTRACT_UNAVAILABLE`, `CREATE_PLAN_PUBLICATION_CONTRACT_UNAVAILABLE`) refuse with `JOB_SOURCE_UNRETAINABLE`, while named producer tokens (`JOB_RECORD_CLOSURE_INCOMPLETE`, `JOB_RECORD_PARTS_MISMATCH`, `JOB_RECORD_PARTS_LOCK_MISSING`) map to `JOB_RECORD_INCOMPLETE` on publish or ask and `JOB_ACT_SOURCE_STALE` on finalize.
1226
1226
 
1227
1227
  `interview-picks` records carry `plan: null` and remain valid for source preparation, ask binding and `rig-review/act@4` preparation. An inspection-only plan record with `plan: {steps: []}` and `subjects: []` is valid for source preparation and freshness checks, while plan `checkpoint` and `signoff` ask binding and `rig-review/act@4` preparation require non-empty `plan.steps` and declared subjects (`JOB_ASK_INVALID` / `JOB_ACT_INVALID`), and plan `reopen` ask binding and `rig-review/act@4` `{stage, words}` preparation require a declared `{kind: 'reopen', stage}` subject on a `plan` record source ([Review #586](https://github.com/rig-c/review/issues/586)). Focused unit tests cover synthetic reader doubles, normal owner URL model-free record inspection (`retainedPublicationRoutes` + `prepareJobInspection` + `createJobWindow`), and archive-backed reader-double evidence over extracted `2-rigging-answers.tar.gz` (`rig-review/job-api@3` and `rig-review/act@4` parsed by `parseRecordAct` using a local `readRecordPublished` reader double and synthetic parts integrity, distinct from official installed Create reader/consumer conformance under [Create #278](https://github.com/rig-c/create/issues/278) and [Create #317](https://github.com/rig-c/create/issues/317)).
1228
+
1229
+ ### Optional sealed checkpoint evidence
1230
+
1231
+ The trusted `JobPublicationReader` package context and the record reader's
1232
+ `PlanContext` may declare `checkpointEvidence`. Package-only API@2, API@3 package
1233
+ publications in record-and-package mode, and model-free record plan publications
1234
+ share this declaration. It is admitted only through the trusted reader and its
1235
+ exact work-root-relative file closure. Each packet binds an admitted checkpoint
1236
+ subject to an existing plan step. Package aliases use the subject's
1237
+ `planStepId ?? checkpointId`. Record checkpoints use the same checkpoint and plan
1238
+ step ID. Image-set and option-set publications refuse this extension.
1239
+
1240
+ The collection contains ordered packets with exactly these fields.
1241
+
1242
+ ```ts
1243
+ {
1244
+ schema: 'rig-review-checkpoint-evidence/1',
1245
+ checkpointId: string,
1246
+ planStepId: string,
1247
+ tiles: [{id: string, label: string, path: string, sha256: string}],
1248
+ table: {path: string, sha256: string, label?: string},
1249
+ routesText: string,
1250
+ recommendationText: string
1251
+ }
1252
+ ```
1253
+
1254
+ The table's sealed UTF-8 JSON document has exactly `schema`, `columns` and `rows`.
1255
+ Its schema is `rig-review-checkpoint-table/1`. Columns are ordered, nonempty text
1256
+ labels. Each row is an array of exactly that column count, with string, finite
1257
+ number, boolean or null cells. The declaration carries only the table file seal
1258
+ and optional label. The document alone supplies the table body. All rows, column
1259
+ order, tile order and exact Unicode/text values are preserved. Routes and the
1260
+ recommendation are verbatim text. The owner UI displays supplied text as text and
1261
+ labels the recommendation through its EN/KO catalog. An evidence-bearing card's
1262
+ adjacent mapping uses pass for route (i), accepting the openings, and fail plus
1263
+ the owner's words for (ii) or (iii). The browser value remains
1264
+ `{checkpointId, outcome, words}`. The daemon supplies the finalized `planStepId`.
1265
+
1266
+ Admission bounds are explicit.
1267
+
1268
+ | Item | Bound |
1269
+ | --- | --- |
1270
+ | Packets and tiles | 1–8 packets, 1–8 ordered tiles per packet, unique checkpoint IDs and tile IDs within each packet |
1271
+ | Entire canonical declaration | 32 KiB UTF-8 |
1272
+ | IDs and paths | Existing `jobId` 128-character and `jobPath` 4,096-character limits |
1273
+ | Tile labels, optional table label and column labels | Nonempty strings, at most 512 UTF-16 units each |
1274
+ | Routes and recommendation | Nonempty strings, at most 4,096 UTF-16 units each |
1275
+ | Tile bytes | Static noninterlaced 8-bit RGB/RGBA PNG, at most 8 MiB, each edge at most 16,384 and at most 16,777,216 pixels, validated through the existing PNG decoder |
1276
+ | Table bytes | At most 256 KiB per raw document and 512 KiB total raw table bytes per publication |
1277
+ | Table dimensions | 1–32 columns, 0–2,048 rows, at most 16,384 cells per document |
1278
+ | String cells | At most 2,048 UTF-16 units, including empty strings |
1279
+
1280
+ Text permits LF and tab and refuses other ASCII control characters. Present
1281
+ `undefined`, null and empty evidence collections refuse. Missing required keys,
1282
+ unknown packet/tile/table/document keys, duplicate identities, nested cells and
1283
+ incorrect row widths refuse. Absent evidence stays omitted in normalized
1284
+ contexts, sources, metadata and stored state. Existing 512 KiB event, 2 MiB owner
1285
+ metadata and 16 MiB durable-document delivery/admission limits remain in force.
1286
+ The declaration and table bounds leave room for existing metadata and events.
1287
+ Existing closure file count and total retained-byte limits also apply.
1288
+
1289
+ Every tile and table path must exactly match a trusted closure member and SHA-256.
1290
+ Review reuses regular-file, descriptor-based, literal portable path containment
1291
+ checks, including every directory component, and rejects symlinks and escapes.
1292
+ Actual PNG bytes are decoded and the table is parsed before publication.
1293
+ `JOB_SOURCE_MISMATCH` carries named details `CHECKPOINT_EVIDENCE_INVALID`,
1294
+ `CHECKPOINT_EVIDENCE_HASH_MISMATCH`, `CHECKPOINT_EVIDENCE_PNG_INVALID` or
1295
+ `CHECKPOINT_EVIDENCE_TABLE_INVALID`. Unreadable paths or byte bounds use
1296
+ `JOB_SOURCE_UNRETAINABLE` with `CHECKPOINT_EVIDENCE_PATH_REFUSED` or
1297
+ `CHECKPOINT_EVIDENCE_TABLE_LIMIT`. Existing live-source and retained-snapshot
1298
+ refusals still apply to movement during retention or subsequent operations.
1299
+
1300
+ Source binding contains the canonical `checkpointEvidence` collection. Packet
1301
+ key order is `schema`, `checkpointId`, `planStepId`, `tiles`, `table`, `routesText`,
1302
+ `recommendationText`. Tile key order is `id`, `label`, `path`, `sha256`. Table
1303
+ key order is `path`, `sha256`, followed by `label` only when supplied. JSON uses
1304
+ these fixed keys and preserves collection order and exact strings. The package
1305
+ `rig-review-job-source/2` composite preimage appends `checkpointEvidence` after
1306
+ `files`. The record `rig-review-job-record-source/1` digest preimage does the same.
1307
+ No evidence field is emitted or hashed for historical absence. Legacy direct
1308
+ package hashes and literal historical digest/source bytes retain their existing
1309
+ form. Labels, paths, IDs, routes and recommendations all participate, so a
1310
+ metadata-only edit changes source and instance identity or refuses against an
1311
+ already bound source. Raw table bytes are bound by their seal, including changes
1312
+ that parse to the same table. Existing API, finalized-act and source schema
1313
+ markers remain as documented above.
1314
+
1315
+ Both publication-pinned `api/review` projections conditionally include the ordered
1316
+ `checkpointEvidence` collection. Metadata retains the declaration fields, adds
1317
+ each tile's `url` as
1318
+ `/api/checkpoint-evidence/<checkpointId>/tiles/<zero-based-index>`, and expands
1319
+ `table` with its parsed `schema`, `columns`, complete `rows` and `url` as
1320
+ `/api/checkpoint-evidence/<checkpointId>/table`. Both tile and table URLs are
1321
+ relative to the pinned publication base, matching existing interview image URLs.
1322
+ The resolver admits only a declared checkpoint member, finds its exact seal and
1323
+ streams its retained bytes through the existing sealed reference route. Table
1324
+ GET returns the exact retained raw JSON bytes, including their whitespace, and
1325
+ supports HEAD through the same route. Its 256 KiB bound and regular-file/path/SHA
1326
+ checks run before streaming. The URL is derived delivery metadata. The producer's
1327
+ table declaration continues to contain only `path`, `sha256` and optional `label`.
1328
+
1329
+ Before presenting the projection, the owner UI fetches the pinned table URL and
1330
+ checks its raw-byte SHA-256 against the source binding's declared table seal.
1331
+ It parses that authenticated UTF-8 JSON and compares its `schema`, `columns` and
1332
+ `rows` with the projected body, preserving every column and row in order. This
1333
+ comparison uses ordinary JSON parsing and exact data equality. The backend owns
1334
+ table grammar validation at admission and metadata projection. A changed metadata
1335
+ row, column, order or schema under the same source hash fails that comparison.
1336
+ Metadata has the same pinned source hash as the publication. A record publication
1337
+ remains manifest-free. Undeclared evidence has no projection, tile or table route.
1338
+
1339
+ Durable reads authenticate evidence-bearing package composite hashes from the
1340
+ retained base-package hash, record, selector, plan, parts and closure. The private
1341
+ retained `checkpointEvidencePackageHash` stores that base hash only for this
1342
+ extension. The package metadata route additionally compares it to `loadReview`
1343
+ on the retained package. Record sources reuse their canonical digest parser.
1344
+ Stored context, publication, ask, act, event and replay copies must agree with
1345
+ the retained declaration and source identity. Null, undefined or missing source
1346
+ copies for an evidence-bound publication refuse with `JOB_SOURCE_MISMATCH` before
1347
+ source property access. These checks require no live files
1348
+ or reclaimed historical snapshots. Retained-file integrity is checked on fresh
1349
+ evidence mutations and actual asset/metadata reads. Record asks/finalizations
1350
+ also repeat the existing two reader phases and reject metadata drift. Package
1351
+ asks use the reader declaration pinned at publication and the existing current
1352
+ record/file seals. They retain the existing single-reader publication lifecycle.
1353
+ An exact committed publication/ask/act retry returns its original identity after
1354
+ live output drift. A fresh mutation still validates currentness. Reopening never
1355
+ adds current live evidence to an old publication.
1356
+
1357
+ Review owns this additive public declaration. Create #395 implementation requires
1358
+ HQ signature at the exact Review shape PR head. Historical record-source readers
1359
+ with the earlier closed key set refuse evidence-bearing sources. New consumers
1360
+ require the signed extended contract. Owner-screen integration,
1361
+ EN/KO visual verification and later release serving have their own acceptance
1362
+ steps.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "2.9.0",
3
+ "version": "2.10.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
package/src/job-api.ts CHANGED
@@ -1,10 +1,11 @@
1
+ import {checkpointEvidenceFields} from './job-checkpoint-evidence.ts';
1
2
  import { createHash, timingSafeEqual } from 'node:crypto';
2
3
  import {
3
4
  JOB_ACT_SCHEMA, JOB_API_SCHEMA, JOB_API_V3_SCHEMA, JOB_ENABLED_ACT_KINDS, JOB_PARTS_ENUMERATOR_RANGE,
4
5
  JOB_PLAN_BOUND_SIGNOFF_STAGES, JOB_RECORD_ACT_SCHEMA, JOB_RECORD_INSTANCE_SCHEMA, JOB_RECORD_SOURCE_SCHEMA,
5
6
  JOB_RESERVED_ACT_KINDS,
6
7
  type AgentRequestV3, type FetchActRequestV3, type JobAgentRequest, type JobApiSchema,
7
- type JobDisplayAcknowledgment, type JobErrorCode, type JobFetchActRequest, type JobFileIdentity,
8
+ type JobCheckpointEvidence, type JobDisplayAcknowledgment, type JobErrorCode, type JobFetchActRequest, type JobFileIdentity,
8
9
  type JobHostPorts, type JobHumanAuthority, type JobInterviewDiagnostic, type JobInterviewDiagnostics,
9
10
  type JobInterviewJson, type JobInterviewRecord, type JobPlanIdentity, type JobPublicationMode,
10
11
  type JobPublishRequest, type JobResult, type JobSelector, type JobSha256, type JobSubject,
@@ -391,13 +392,14 @@ function asCode<Value>(fn: () => Value, code: JobErrorCode): Value {
391
392
  }
392
393
  }
393
394
 
394
- function exactObject(
395
+ export function exactObject(
395
396
  value: unknown,
396
397
  keys: readonly string[],
397
398
  code: JobErrorCode,
399
+ optional: readonly string[] = [],
398
400
  ): Record<string, unknown> {
399
- const item = asCode(() => jobObject(value, keys), code);
400
- if (Object.keys(item).length !== keys.length || keys.some(key => item[key] === undefined)) {
401
+ const item = asCode(() => jobObject(value, [...keys, ...optional]), code);
402
+ if (keys.some(key => !Object.hasOwn(item, key) || item[key] === undefined)) {
401
403
  throw new JobError(code);
402
404
  }
403
405
  return item;
@@ -648,6 +650,7 @@ type ParsedRecordPayload =
648
650
  }
649
651
  | {
650
652
  readonly kind: 'plan';
653
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
651
654
  readonly inputs: readonly JobFileIdentity[];
652
655
  readonly files: readonly JobFileIdentity[];
653
656
  readonly plan: JobPlanIdentity;
@@ -661,17 +664,18 @@ function parseRecordClosureAndSubjects(
661
664
  rawSubjects: unknown,
662
665
  selection: RecordResult,
663
666
  checkedRecord?: ProjectRecord,
667
+ evidenceHolder: object = {},
664
668
  ): ParsedRecordPayload {
665
669
  const { inputs, files } = parseFileClosure(rawInputs, rawFiles, checkedRecord, 'JOB_SOURCE_MISMATCH');
666
670
  if (selection.kind === 'option-set') {
667
- if (rawPlan !== null) throw new JobError('JOB_SOURCE_MISMATCH');
671
+ if (rawPlan !== null || 'checkpointEvidence' in evidenceHolder) throw new JobError('JOB_SOURCE_MISMATCH');
668
672
  const subjects = parseOptionSubjects(rawSubjects, selection, 'JOB_SOURCE_MISMATCH');
669
673
  return { kind: 'option-set', inputs, files, plan: null, subjects };
670
674
  }
671
675
  if (rawPlan === null) throw new JobError('JOB_SOURCE_MISMATCH');
672
676
  const { plan, stepIds } = parsePlanIdentity(rawPlan, 'JOB_SOURCE_MISMATCH');
673
677
  const subjects = parsePlanSubjects(rawSubjects, stepIds, 'JOB_SOURCE_MISMATCH');
674
- return { kind: 'plan', inputs, files, plan, subjects };
678
+ return { kind: 'plan', inputs, files, plan, subjects, ...checkpointEvidenceFields(evidenceHolder, plan, subjects, files) };
675
679
  }
676
680
 
677
681
  export function parseRecordPublishedContext(
@@ -696,7 +700,7 @@ export function parseRecordPublishedContext(
696
700
  ): OptionContext | PlanContext {
697
701
  const selection = parseRecordResult(result);
698
702
  const checkedRecord = record === undefined ? undefined : parseProjectRecord(record, 'JOB_SOURCE_MISMATCH');
699
- const item = exactObject(value, ['label', 'parts', 'inputs', 'files', 'plan', 'subjects'], 'JOB_SOURCE_MISMATCH');
703
+ const item = exactObject(value, ['label', 'parts', 'inputs', 'files', 'plan', 'subjects'], 'JOB_SOURCE_MISMATCH', ['checkpointEvidence']);
700
704
  const label = asCode(() => jobText(item.label), 'JOB_SOURCE_MISMATCH');
701
705
  const parts = parseRecordPartsIdentity(item.parts, 'JOB_SOURCE_MISMATCH');
702
706
  const body = parseRecordClosureAndSubjects(
@@ -706,11 +710,13 @@ export function parseRecordPublishedContext(
706
710
  item.subjects,
707
711
  selection,
708
712
  checkedRecord,
713
+ item,
709
714
  );
710
715
  if (body.kind === 'option-set') {
711
716
  return { label, parts, inputs: body.inputs, files: body.files, plan: null, subjects: body.subjects };
712
717
  }
713
- return { label, parts, inputs: body.inputs, files: body.files, plan: body.plan, subjects: body.subjects };
718
+ return { label, parts, inputs: body.inputs, files: body.files, plan: body.plan, subjects: body.subjects,
719
+ ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}) };
714
720
  }
715
721
 
716
722
  export function assertEqualRecordContexts(
@@ -734,6 +740,7 @@ export function assertEqualRecordContexts(
734
740
  }
735
741
 
736
742
  export interface RecordSourceDigestInput {
743
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
737
744
  readonly schema?: typeof JOB_RECORD_SOURCE_SCHEMA;
738
745
  readonly sourceHash?: JobSha256;
739
746
  readonly projectHash?: JobSha256;
@@ -764,6 +771,7 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
764
771
  'plan',
765
772
  'subjects',
766
773
  'files',
774
+ 'checkpointEvidence',
767
775
  ]),
768
776
  'JOB_SOURCE_MISMATCH',
769
777
  );
@@ -787,7 +795,7 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
787
795
  const { inputs, files, byPath } = parseFileClosure(item.inputs, item.files, record, 'JOB_SOURCE_MISMATCH');
788
796
 
789
797
  if (selection.kind === 'option-set') {
790
- if (item.plan !== null || item.optionSet === null || item.optionSetFile === null) {
798
+ if ('checkpointEvidence' in item || item.plan !== null || item.optionSet === null || item.optionSetFile === null) {
791
799
  throw new JobError('JOB_SOURCE_MISMATCH');
792
800
  }
793
801
  const rawOptionSet = exactObject(item.optionSet, ['id', 'sha256'], 'JOB_SOURCE_MISMATCH');
@@ -831,6 +839,7 @@ export function serializeRecordSourceDigestPayload(input: RecordSourceDigestInpu
831
839
  plan,
832
840
  subjects,
833
841
  files,
842
+ ...checkpointEvidenceFields(item, plan, subjects, files),
834
843
  });
835
844
  }
836
845
 
@@ -896,6 +905,7 @@ function assembleRecordSource(
896
905
  plan: body.plan,
897
906
  subjects: body.subjects,
898
907
  files: body.files,
908
+ ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}),
899
909
  });
900
910
  return {
901
911
  sourceHash,
@@ -903,6 +913,7 @@ function assembleRecordSource(
903
913
  record,
904
914
  inputs: body.inputs,
905
915
  files: body.files,
916
+ ...(body.checkpointEvidence ? {checkpointEvidence: body.checkpointEvidence} : {}),
906
917
  subject: 'plan',
907
918
  selection: { kind: 'plan' },
908
919
  optionSet: null,
@@ -948,6 +959,7 @@ export function buildRecordSource(input: {
948
959
  files: context.files,
949
960
  plan: context.plan,
950
961
  subjects: context.subjects,
962
+ ...(context.checkpointEvidence ? {checkpointEvidence: context.checkpointEvidence} : {}),
951
963
  };
952
964
  return assembleRecordSource(record, selection, body, input.optionSetFile);
953
965
  }
@@ -969,6 +981,7 @@ export function parseRecordSource(value: unknown): RecordSource {
969
981
  'subjects',
970
982
  ],
971
983
  'JOB_SOURCE_MISMATCH',
984
+ ['checkpointEvidence'],
972
985
  );
973
986
  const record = parseProjectRecord(item.record, 'JOB_SOURCE_MISMATCH');
974
987
  const projectHash = asCode(() => jobSha(item.projectHash), 'JOB_SOURCE_MISMATCH');
@@ -983,6 +996,7 @@ export function parseRecordSource(value: unknown): RecordSource {
983
996
  item.subjects,
984
997
  selection,
985
998
  record,
999
+ item,
986
1000
  );
987
1001
  if (selection.kind === 'option-set') {
988
1002
  const rawOptionSet = exactObject(item.optionSet, ['id', 'sha256'], 'JOB_SOURCE_MISMATCH');
@@ -0,0 +1,113 @@
1
+ import {realpathSync} from 'node:fs';
2
+ import type {JobCheckpointEvidence, JobCheckpointTable, JobFileIdentity, JobPlanIdentity, JobSubject, RecordSubject} from './job-contract.ts';
3
+ import {exactObject, jobHash, jobId, jobPath, jobSha} from './job-api.ts';
4
+ import {JobError} from './job-store.ts';
5
+ import {checkedPath, readRegular} from './interview-project.ts';
6
+ import {validatePngBytes} from './comment-crops.ts';
7
+
8
+ const evidenceSchema = 'rig-review-checkpoint-evidence/1';
9
+ const tableSchema = 'rig-review-checkpoint-table/1';
10
+
11
+ function evidenceText(value: unknown, max: number): string {
12
+ if (typeof value !== 'string' || !value.length || value.length > max || /[\x00-\x08\x0b-\x1f\x7f]/.test(value)) {
13
+ throw new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_TEXT_INVALID');
14
+ }
15
+ return value;
16
+ }
17
+
18
+ /** Canonical optional declaration. Absence must not materialize a historical field. */
19
+ export function checkpointEvidenceFields(holder: object, plan: JobPlanIdentity | null,
20
+ subjects: readonly (JobSubject | RecordSubject)[], files: readonly JobFileIdentity[]): {checkpointEvidence?: readonly JobCheckpointEvidence[]} {
21
+ if (!('checkpointEvidence' in holder)) return {};
22
+ try {
23
+ const raw = holder.checkpointEvidence;
24
+ if (!plan || !Array.isArray(raw) || raw.length < 1 || raw.length > 8) throw new Error('collection');
25
+ const seen = new Set<string>();
26
+ const checkpointEvidence = raw.map<JobCheckpointEvidence>(value => {
27
+ const item = exactObject(value, ['schema', 'checkpointId', 'planStepId', 'tiles', 'table', 'routesText', 'recommendationText'], 'JOB_SOURCE_MISMATCH');
28
+ const checkpointId = jobId(item.checkpointId), planStepId = jobId(item.planStepId);
29
+ if (item.schema !== evidenceSchema || seen.has(checkpointId) || !plan.steps.some(step => step.id === planStepId) ||
30
+ !subjects.some(subject => subject.kind === 'checkpoint' && subject.checkpointId === checkpointId &&
31
+ (('planStepId' in subject ? subject.planStepId : undefined) ?? subject.checkpointId) === planStepId)) throw new Error('association');
32
+ seen.add(checkpointId);
33
+ if (!Array.isArray(item.tiles) || item.tiles.length < 1 || item.tiles.length > 8) throw new Error('tiles');
34
+ const ids = new Set<string>();
35
+ const tiles = item.tiles.map(value => {
36
+ const tile = exactObject(value, ['id', 'label', 'path', 'sha256'], 'JOB_SOURCE_MISMATCH');
37
+ const id = jobId(tile.id);
38
+ if (ids.has(id)) throw new Error('duplicate tile');
39
+ ids.add(id);
40
+ return {id, label: evidenceText(tile.label, 512), path: jobPath(tile.path), sha256: jobSha(tile.sha256)};
41
+ });
42
+ const rawTable = exactObject(item.table, ['path', 'sha256'], 'JOB_SOURCE_MISMATCH', ['label']);
43
+ const table = {path: jobPath(rawTable.path), sha256: jobSha(rawTable.sha256),
44
+ ...('label' in rawTable ? {label: evidenceText(rawTable.label, 512)} : {})};
45
+ for (const file of [...tiles, table]) {
46
+ if (!files.some(seal => seal.path === file.path && seal.sha256 === file.sha256)) throw new Error('closure');
47
+ }
48
+ return {schema: evidenceSchema, checkpointId, planStepId, tiles, table,
49
+ routesText: evidenceText(item.routesText, 4096), recommendationText: evidenceText(item.recommendationText, 4096)};
50
+ });
51
+ if (Buffer.byteLength(JSON.stringify(checkpointEvidence)) > 32 * 1024) throw new Error('declaration bound');
52
+ return {checkpointEvidence};
53
+ } catch {
54
+ throw new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_INVALID');
55
+ }
56
+ }
57
+
58
+ /** The sealed document is the sole table body. Preserve columns, rows and scalars. */
59
+ export function parseCheckpointTable(bytes: Buffer): JobCheckpointTable {
60
+ try {
61
+ if (bytes.length > 256 * 1024) throw new Error('byte bound');
62
+ const item = exactObject(JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes)), ['schema', 'columns', 'rows'], 'JOB_SOURCE_MISMATCH');
63
+ if (item.schema !== tableSchema || !Array.isArray(item.columns) || item.columns.length < 1 || item.columns.length > 32 ||
64
+ !Array.isArray(item.rows) || item.rows.length > 2048 || item.rows.length * item.columns.length > 16384) throw new Error('dimensions');
65
+ const columns = item.columns.map(value => evidenceText(value, 512));
66
+ const rows = item.rows.map(row => {
67
+ if (!Array.isArray(row) || row.length !== columns.length) throw new Error('row width');
68
+ return row.map(cell => {
69
+ if (typeof cell === 'string') {
70
+ if (cell.length > 2048 || /[\x00-\x08\x0b-\x1f\x7f]/.test(cell)) throw new Error('cell text');
71
+ } else if (cell !== null && typeof cell !== 'boolean' && !(typeof cell === 'number' && Number.isFinite(cell))) {
72
+ throw new Error('scalar');
73
+ }
74
+ return cell as string | number | boolean | null;
75
+ });
76
+ });
77
+ return {schema: tableSchema, columns, rows};
78
+ } catch {
79
+ throw new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_TABLE_INVALID');
80
+ }
81
+ }
82
+
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;
86
+ try {
87
+ if (realpathSync(root) !== root) throw new Error('Noncanonical evidence root');
88
+ bytes = readRegular(checkedPath(root, file.path), limit);
89
+ }
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');
92
+ return bytes;
93
+ }
94
+
95
+ /** Used before publication and metadata delivery. No table body enters durable state. */
96
+ export function checkpointEvidenceMetadata(root: string, evidence: readonly JobCheckpointEvidence[] | undefined) {
97
+ if (evidence === undefined) return {};
98
+ let tableBytes = 0;
99
+ const checkpointEvidence = evidence.map(packet => {
100
+ for (const tile of packet.tiles) {
101
+ const bytes = readCheckpointEvidenceBytes(root, tile, 8 * 1024 * 1024);
102
+ try { validatePngBytes(bytes, bytes.readUInt32BE(16), bytes.readUInt32BE(20)); }
103
+ catch { throw new JobError('JOB_SOURCE_MISMATCH', 'CHECKPOINT_EVIDENCE_PNG_INVALID'); }
104
+ }
105
+ const bytes = readCheckpointEvidenceBytes(root, packet.table, 256 * 1024);
106
+ tableBytes += bytes.length;
107
+ if (tableBytes > 512 * 1024) throw new JobError('JOB_SOURCE_UNRETAINABLE', 'CHECKPOINT_EVIDENCE_TABLE_LIMIT');
108
+ return {...packet, tiles: packet.tiles.map((tile, index) => ({...tile,
109
+ url: `/api/checkpoint-evidence/${packet.checkpointId}/tiles/${index}`})),
110
+ table: {...packet.table, url: `/api/checkpoint-evidence/${packet.checkpointId}/table`, ...parseCheckpointTable(bytes)}};
111
+ });
112
+ return {checkpointEvidence};
113
+ }
@@ -147,6 +147,23 @@ export interface JobFileIdentity {
147
147
  readonly sha256: JobSha256;
148
148
  }
149
149
 
150
+ /** Optional sealed decision material, bound verbatim to the published source. */
151
+ export interface JobCheckpointEvidence {
152
+ readonly schema: 'rig-review-checkpoint-evidence/1';
153
+ readonly checkpointId: string;
154
+ readonly planStepId: string;
155
+ readonly tiles: readonly (JobFileIdentity & {readonly id: string; readonly label: string})[];
156
+ readonly table: JobFileIdentity & {readonly label?: string};
157
+ readonly routesText: string;
158
+ readonly recommendationText: string;
159
+ }
160
+
161
+ export interface JobCheckpointTable {
162
+ readonly schema: 'rig-review-checkpoint-table/1';
163
+ readonly columns: readonly string[];
164
+ readonly rows: readonly (readonly (string | number | boolean | null)[])[];
165
+ }
166
+
150
167
  /** IDs and existing step hashes published by Create #184 for the displayed plan.
151
168
  * Review retains these values without importing or computing Create's internal
152
169
  * stepHash. Create validates them with its existing writer. No plan revision
@@ -211,6 +228,7 @@ export type JobSelector =
211
228
  * provide trusted source hashes or transfer old approval onto a new binding.
212
229
  */
213
230
  export interface JobModelSourceBinding {
231
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
214
232
  readonly subject?: never;
215
233
  readonly imageSet?: never;
216
234
  readonly imageSetDigest?: never;
@@ -244,7 +262,8 @@ export interface JobImageSet {
244
262
  }
245
263
 
246
264
  export interface JobImageSourceBinding extends Omit<JobModelSourceBinding,
247
- 'subject' | 'model' | 'selector' | 'imageSet' | 'imageSetDigest' | 'duplicateHashes'> {
265
+ 'subject' | 'model' | 'selector' | 'imageSet' | 'imageSetDigest' | 'duplicateHashes' | 'checkpointEvidence'> {
266
+ readonly checkpointEvidence?: never;
248
267
  readonly subject: 'image-set';
249
268
  readonly model?: never;
250
269
  readonly selector?: never;
@@ -877,11 +896,13 @@ export interface RecordContextBase {
877
896
  }
878
897
 
879
898
  export type OptionContext = RecordContextBase & {
899
+ readonly checkpointEvidence?: never;
880
900
  readonly plan: null;
881
901
  readonly subjects: readonly [RecordPicksSubject];
882
902
  };
883
903
 
884
904
  export type PlanContext = RecordContextBase & {
905
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
885
906
  readonly plan: JobPlanIdentity;
886
907
  readonly subjects: readonly RecordPlanSubject[];
887
908
  };
@@ -928,6 +949,7 @@ export interface RecordSourceBase {
928
949
  }
929
950
 
930
951
  export type OptionSource = RecordSourceBase & {
952
+ readonly checkpointEvidence?: never;
931
953
  readonly subject: 'option-set';
932
954
  readonly selection: RecordOptionResult;
933
955
  readonly optionSet: { readonly id: string; readonly sha256: JobSha256 };
@@ -937,6 +959,7 @@ export type OptionSource = RecordSourceBase & {
937
959
  };
938
960
 
939
961
  export type PlanSource = RecordSourceBase & {
962
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
940
963
  readonly subject: 'plan';
941
964
  readonly selection: RecordPlanResult;
942
965
  readonly optionSet: null;
package/src/job-front.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import {checkpointEvidenceMetadata, readCheckpointEvidenceBytes} from './job-checkpoint-evidence.ts';
1
2
  /** Disjoint live-job routes. The backend receives the original authenticated Request. */
2
3
  import { JOB_API_SCHEMA, JOB_ACT_SCHEMA, type JobErrorCode, type JobHostPorts, type JobId, type JobPublicationMode, type JobResult, type JobReviewerBinding } from './job-contract.ts';
3
4
  import { createJobHostPorts, jobBody, jobHash, jobId, jobObject, jobPartsEnumeratorVersion } from './job-api.ts';
@@ -28,8 +29,8 @@ interface CropFailureDiagnostic {
28
29
  expected: string | number[];
29
30
  received: string | number[];
30
31
  }
31
- function failure(code: string, status: number, diagnostic?: CropFailureDiagnostic): Response {
32
- return Response.json({ ok: false, error: { code, message: code, ...(diagnostic ? {diagnostic} : {}) } }, { status, headers });
32
+ function failure(code: string, status: number, diagnostic?: CropFailureDiagnostic, message = code): Response {
33
+ return Response.json({ ok: false, error: { code, message, ...(diagnostic ? {diagnostic} : {}) } }, { status, headers });
33
34
  }
34
35
 
35
36
  /** Explain an existing rejection without returning body text, filesystem paths or PNG bytes. */
@@ -273,9 +274,19 @@ export function retainedPublicationRoutes(session: JobSession) {
273
274
  const file = await safeFile(retained.snapshotRoot, relativePath);
274
275
  return serveReference(request, file, seal.sha256, headers);
275
276
  };
277
+ const evidenceRoute = /^api\/checkpoint-evidence\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(table|tiles\/(0|[1-9]\d*))$/.exec(path);
278
+ if (evidenceRoute) {
279
+ const packet = retained.source.checkpointEvidence?.find(item => item.checkpointId === evidenceRoute[1]);
280
+ const isTable = evidenceRoute[2] === 'table';
281
+ const member = isTable ? packet?.table : packet?.tiles[Number(evidenceRoute[3])];
282
+ if (!member) return failure('JOB_SOURCE_UNRETAINABLE', 404);
283
+ readCheckpointEvidenceBytes(retained.snapshotRoot, member, isTable ? 256 * 1024 : 8 * 1024 * 1024);
284
+ return await sealedFile(member.path);
285
+ }
276
286
  if (isRetainedRecordSource(retained)) {
277
287
  if (path === 'api/review') {
278
288
  return json({
289
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
279
290
  recordSource: retained.source,
280
291
  sourceHash: retained.source.sourceHash,
281
292
  assetsBase: display.routes.assetsBase,
@@ -338,8 +349,12 @@ export function retainedPublicationRoutes(session: JobSession) {
338
349
  }
339
350
  const {review, parts} = await pending;
340
351
  await assertReviewUnchanged(review);
352
+ if (retained.checkpointEvidencePackageHash !== undefined && retained.checkpointEvidencePackageHash !== review.sourceHash) {
353
+ throw new JobError('JOB_SOURCE_MISMATCH');
354
+ }
341
355
  if (path === 'api/review') {
342
356
  return json({
357
+ ...checkpointEvidenceMetadata(retained.snapshotRoot, retained.source.checkpointEvidence),
343
358
  manifest: review.manifest,
344
359
  sourceHash: retained.source.sourceHash,
345
360
  reviewedSource: review.reviewedSource,
@@ -427,7 +442,9 @@ export function retainedPublicationRoutes(session: JobSession) {
427
442
  const code = error instanceof JobError ? error.code :
428
443
  error instanceof Error && error.message.startsWith('PARTS_COMMENT_STALE_SOURCE:')
429
444
  ? 'PARTS_COMMENT_STALE_SOURCE' : 'JOB_SOURCE_MISMATCH';
430
- return failure(code, errorStatus[code as JobErrorCode] ?? 409);
445
+ const message = error instanceof JobError && /^CHECKPOINT_EVIDENCE_[A-Z_]+$/.test(error.message)
446
+ ? error.message : undefined;
447
+ return failure(code, errorStatus[code as JobErrorCode] ?? 409, undefined, message);
431
448
  }
432
449
  };
433
450
  }
package/src/job-host.ts CHANGED
@@ -208,3 +208,5 @@ export type {
208
208
 
209
209
  export {assertJobImageSetCapability} from './job-image-set.ts';
210
210
  export type {JobCapabilities, JobImageSetInput, JobImageSet, JobImageSourceBinding, JobModelSourceBinding, JobModelReviewValue, JobImageReviewValue} from './job-contract.ts';
211
+
212
+ export type {JobCheckpointEvidence, JobCheckpointTable} from './job-contract.ts';