rig-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.
- package/docs/REVIEW_PACKAGE.md +138 -3
- package/package.json +1 -1
- package/src/job-api.ts +23 -9
- package/src/job-checkpoint-evidence.ts +113 -0
- package/src/job-contract.ts +24 -1
- package/src/job-front.ts +20 -3
- package/src/job-host.ts +2 -0
- package/src/job-session.ts +37 -5
- package/src/job-source.ts +52 -7
- package/web/catalog-en.ts +9 -0
- package/web/catalog-ko.ts +9 -0
- package/web/job-session.ts +331 -53
- package/web/parts.ts +6 -1
- package/web/stage-comments.ts +3 -3
- package/web/styles.css +17 -3
package/docs/REVIEW_PACKAGE.md
CHANGED
|
@@ -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
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 (
|
|
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
|
+
}
|
package/src/job-contract.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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';
|