rig-review 2.9.0 → 2.11.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,203 @@ 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.
1363
+
1364
+ ### Sealed plan step text
1365
+
1366
+ Both publication-pinned `api/review` responses append delivery-only `planText`
1367
+ when the accepted source has a plan. The daemon authenticates `project.json`
1368
+ from that publication's retained snapshot against its record seal and existing
1369
+ `projectHash`, then projects `does`, `produces`, `bar` and `rests_on`.
1370
+
1371
+ The projected envelope has ordered keys `schema`, `record`, `status`, `steps`.
1372
+ `schema` is `rig-review/job-plan-text@1`, `record` is `{path:"project.json",sha256}`,
1373
+ and `status` is `projected`. Rows follow the accepted plan's exact id/hash order.
1374
+ Each row has `id`, `hash`, optional `does`, `produces`, `bar`, `rests_on`, then
1375
+ `issues`. Each field supplies exactly one value or an ordered
1376
+ `{field,reason:"absent"|"invalid"|"limit"}` issue. Scalar values are strings and
1377
+ `rests_on` is an ordered string array. Empty strings/arrays, whitespace, line
1378
+ endings, Unicode form, duplicate references and array order are preserved.
1379
+ Producer extras stay outside this display projection.
1380
+
1381
+ D1 matches only accepted ids, preserving source order and existing checkpoint
1382
+ aliases (`planStepId ?? checkpointId`). D2 retains its existing whole-plan
1383
+ count/ordered-id admission checks. Hashes are the producer's opaque accepted
1384
+ identities. The existing reader retains responsibility for their semantic value.
1385
+
1386
+ The unavailable envelope has `schema`, `record` (or null),
1387
+ `status:"unavailable"`, `reason`. Named reasons are
1388
+ `PLAN_TEXT_RECORD_UNAVAILABLE`, `PLAN_TEXT_RECORD_UNSUPPORTED`,
1389
+ `PLAN_TEXT_STEPS_ABSENT`, `PLAN_TEXT_STEPS_INVALID`,
1390
+ `PLAN_TEXT_MAPPING_UNAVAILABLE` and `PLAN_TEXT_LIMIT`. The UI shows the named
1391
+ absence and existing ids/hashes. Partial valid fields remain visible beside
1392
+ their missing/invalid field labels. Existing act authority and historical
1393
+ metadata omission retain their fallback behavior.
1394
+
1395
+ The server retains its 8 MiB project read bound. Display limits are 4,096 plan
1396
+ steps, 4,096 `rests_on` entries and 512 KiB UTF-8 for `planText`. Whole owner
1397
+ metadata retains its 2 MiB bound. A small unavailable envelope replaces an
1398
+ oversized projection. If that envelope also exceeds the response budget, the
1399
+ server returns `JOB_BODY_LIMIT` with `PLAN_TEXT_LIMIT`. Values remain complete
1400
+ within the admitted display budget.
1401
+
1402
+ The browser checks the closed grammar, metadata/source association, record SHA
1403
+ and ordered id/hash mapping. Field values have the normal daemon's authority.
1404
+ Type-valid post-server text mutation can pass those checks. The server's sealed
1405
+ record authentication and the browser's source/grammar checks are their
1406
+ respective validation boundaries. Checkpoint evidence retains its established
1407
+ raw-member authentication.
1408
+
1409
+ This metadata is produced at response time. Source/act schemas, producer reader
1410
+ DTOs, stable `job-host` exports, durable state and canonical hash preimages retain
1411
+ their existing definitions. Checkpoint and signoff values continue through their
1412
+ existing forms, outcome select and submission lifecycle.
1413
+
1414
+ Under HQ ruling 7896ec71, the official D2 consumer gate is the supported
1415
+ record-checkpoint flow following Create #395 integration. Create owns the actual
1416
+ producer receipt. Review's plan-signoff rendering has synthetic UI coverage.
1417
+ Normal CLI plan-signoff bootstrap and `plan-approved` act@4 ingestion are a
1418
+ separate Create follow-up. (Naru, 2026-11-11)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "2.9.0",
3
+ "version": "2.11.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
@@ -161,6 +178,79 @@ export interface JobPlanIdentity {
161
178
  readonly steps: readonly JobPlanStepIdentity[];
162
179
  }
163
180
 
181
+ /** Ephemeral owner metadata, projected by the daemon from the sealed project. */
182
+ export const JOB_PLAN_TEXT_SCHEMA = 'rig-review/job-plan-text@1' as const;
183
+ export const JOB_PLAN_TEXT_FIELDS = ['does', 'produces', 'bar', 'rests_on'] as const;
184
+ export type JobPlanTextField = typeof JOB_PLAN_TEXT_FIELDS[number];
185
+ export interface JobPlanTextStep {
186
+ readonly id: string;
187
+ readonly hash: string;
188
+ does?: string;
189
+ produces?: string;
190
+ bar?: string;
191
+ rests_on?: readonly string[];
192
+ readonly issues: {field: JobPlanTextField; reason: 'absent' | 'invalid' | 'limit'}[];
193
+ }
194
+ export const JOB_PLAN_TEXT_UNAVAILABLE = [
195
+ 'PLAN_TEXT_RECORD_UNAVAILABLE', 'PLAN_TEXT_RECORD_UNSUPPORTED', 'PLAN_TEXT_STEPS_ABSENT',
196
+ 'PLAN_TEXT_STEPS_INVALID', 'PLAN_TEXT_MAPPING_UNAVAILABLE', 'PLAN_TEXT_LIMIT',
197
+ ] as const;
198
+ export type JobPlanTextProjection = {
199
+ readonly schema: typeof JOB_PLAN_TEXT_SCHEMA;
200
+ readonly record: {readonly path: 'project.json'; readonly sha256: string};
201
+ readonly status: 'projected';
202
+ readonly steps: readonly JobPlanTextStep[];
203
+ } | {
204
+ readonly schema: typeof JOB_PLAN_TEXT_SCHEMA;
205
+ readonly record: {readonly path: 'project.json'; readonly sha256: string} | null;
206
+ readonly status: 'unavailable';
207
+ readonly reason: typeof JOB_PLAN_TEXT_UNAVAILABLE[number];
208
+ };
209
+
210
+ /** Closed delivery grammar. Field contents have the normal daemon's authority. */
211
+ export function parseJobPlanTextProjection(value: unknown): JobPlanTextProjection {
212
+ const fail = (): never => {throw new Error('PLAN_TEXT_METADATA_INVALID');};
213
+ const object = (input: unknown, keys: readonly string[]): Record<string, unknown> => {
214
+ if (!input || typeof input !== 'object' || Array.isArray(input) ||
215
+ Object.keys(input).some(key => !keys.includes(key))) return fail();
216
+ return input as Record<string, unknown>;
217
+ };
218
+ const envelope = object(value, ['schema', 'record', 'status', 'steps', 'reason']);
219
+ if (envelope.schema !== JOB_PLAN_TEXT_SCHEMA || !Object.hasOwn(envelope, 'record') ||
220
+ new TextEncoder().encode(JSON.stringify(value)).length > 512 * 1024) return fail();
221
+ if (envelope.record !== null) {
222
+ const record = object(envelope.record, ['path', 'sha256']);
223
+ if (record.path !== 'project.json' || typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(record.sha256)) return fail();
224
+ }
225
+ if (envelope.status === 'unavailable') {
226
+ if (Object.hasOwn(envelope, 'steps') || !(JOB_PLAN_TEXT_UNAVAILABLE as readonly unknown[]).includes(envelope.reason)) return fail();
227
+ return value as JobPlanTextProjection;
228
+ }
229
+ if (envelope.status !== 'projected' || envelope.record === null || Object.hasOwn(envelope, 'reason') ||
230
+ !Array.isArray(envelope.steps) || envelope.steps.length > 4096) return fail();
231
+ const ids = new Set<string>();
232
+ for (const raw of envelope.steps) {
233
+ const row = object(raw, ['id', 'hash', ...JOB_PLAN_TEXT_FIELDS, 'issues']);
234
+ if (typeof row.id !== 'string' || row.id.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(row.id) ||
235
+ ids.has(row.id) || typeof row.hash !== 'string' || !/^[a-f0-9]{64}$/.test(row.hash) || !Array.isArray(row.issues)) return fail();
236
+ ids.add(row.id);
237
+ const missing = JOB_PLAN_TEXT_FIELDS.filter(field => !Object.hasOwn(row, field));
238
+ if (row.issues.length !== missing.length) return fail();
239
+ row.issues.forEach((rawIssue, index) => {
240
+ const issue = object(rawIssue, ['field', 'reason']);
241
+ if (issue.field !== missing[index] || typeof issue.reason !== 'string' || !['absent', 'invalid', 'limit'].includes(issue.reason)) fail();
242
+ });
243
+ for (const field of JOB_PLAN_TEXT_FIELDS) {
244
+ if (!Object.hasOwn(row, field)) continue;
245
+ const content = row[field];
246
+ if (field === 'rests_on') {
247
+ if (!Array.isArray(content) || content.length > 4096 || content.some(item => typeof item !== 'string')) return fail();
248
+ } else if (typeof content !== 'string') return fail();
249
+ }
250
+ }
251
+ return value as JobPlanTextProjection;
252
+ }
253
+
164
254
  /** Literal work-root-relative manifest path, validated at runtime. */
165
255
  export type JobPartsManifestPath = string;
166
256
  /** Literal path relative to the bound manifest directory. */
@@ -211,6 +301,7 @@ export type JobSelector =
211
301
  * provide trusted source hashes or transfer old approval onto a new binding.
212
302
  */
213
303
  export interface JobModelSourceBinding {
304
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
214
305
  readonly subject?: never;
215
306
  readonly imageSet?: never;
216
307
  readonly imageSetDigest?: never;
@@ -244,7 +335,8 @@ export interface JobImageSet {
244
335
  }
245
336
 
246
337
  export interface JobImageSourceBinding extends Omit<JobModelSourceBinding,
247
- 'subject' | 'model' | 'selector' | 'imageSet' | 'imageSetDigest' | 'duplicateHashes'> {
338
+ 'subject' | 'model' | 'selector' | 'imageSet' | 'imageSetDigest' | 'duplicateHashes' | 'checkpointEvidence'> {
339
+ readonly checkpointEvidence?: never;
248
340
  readonly subject: 'image-set';
249
341
  readonly model?: never;
250
342
  readonly selector?: never;
@@ -877,11 +969,13 @@ export interface RecordContextBase {
877
969
  }
878
970
 
879
971
  export type OptionContext = RecordContextBase & {
972
+ readonly checkpointEvidence?: never;
880
973
  readonly plan: null;
881
974
  readonly subjects: readonly [RecordPicksSubject];
882
975
  };
883
976
 
884
977
  export type PlanContext = RecordContextBase & {
978
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
885
979
  readonly plan: JobPlanIdentity;
886
980
  readonly subjects: readonly RecordPlanSubject[];
887
981
  };
@@ -928,6 +1022,7 @@ export interface RecordSourceBase {
928
1022
  }
929
1023
 
930
1024
  export type OptionSource = RecordSourceBase & {
1025
+ readonly checkpointEvidence?: never;
931
1026
  readonly subject: 'option-set';
932
1027
  readonly selection: RecordOptionResult;
933
1028
  readonly optionSet: { readonly id: string; readonly sha256: JobSha256 };
@@ -937,6 +1032,7 @@ export type OptionSource = RecordSourceBase & {
937
1032
  };
938
1033
 
939
1034
  export type PlanSource = RecordSourceBase & {
1035
+ readonly checkpointEvidence?: readonly JobCheckpointEvidence[];
940
1036
  readonly subject: 'plan';
941
1037
  readonly selection: RecordPlanResult;
942
1038
  readonly optionSet: null;