@rig-c/review 1.10.2 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -409,3 +409,8 @@ Named input refusals: `PARTS_DIFFERENCE_PROVENANCE`, `PARTS_DIFFERENCE_PATH`,
409
409
  `PARTS_VIEW_SOURCE_CHANGED`. No producer command executes for Difference.
410
410
  `tests/parts-difference.test.ts` supplies literal independent numeric controls;
411
411
  `tests/parts-difference-browser.ts` exercises bilingual display and saved evidence.
412
+
413
+ Saved standalone part notes and pointed comments can be selected as described
414
+ corrections. The handoff keeps the part and original image evidence. Its Create
415
+ selector is a retained parts inventory, with no rig version.
416
+ See [Correction handoff](WORKFLOWS.md#correction-handoff).
@@ -37,9 +37,9 @@ The illustrative `look` animation in `axes` must also be declared in `animations
37
37
 
38
38
  ## Files and references
39
39
 
40
- Every path is a literal relative path, including `model`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
40
+ Every path is a literal relative path, including `model`, optional `direction` and `sets`, optional read-only `motion`, each reference `path`, authoring `path`, clip `path`, and every page name in the compiled model. Manifest paths accept no absolute paths, URL schemes, colon, percent encoding, traversal, backslash, query, fragment, empty segment, or symlink escape. Compiled-model page names are resolved relative to the model directory: a page such as `../parts/page.png` is accepted only when its normalized destination remains inside the review package. This permits portable local builds without letting a page escape the package. All declared files must exist as regular files. The asset endpoint serves only declared files, the manifest, and compiled-model page images. There is no arbitrary directory endpoint. Keep a package focused on the files intended for inspection.
41
41
 
42
- `model` is optional and must point to `rigc-compiled/3` under a filename ending `.model.json`, produced by an upstream gated rigc build. Review uses the public `@rig-c/play` loader and player; Spine JSON/skel is not its input. Its pages are resolved relative to the model document. Missing model means unavailable playback, never a mock playback success. The runtime's optional attachment-set sidecar is not part of v1; attachment presets must remain unavailable rather than guessed.
42
+ `model` is optional and must point to `rigc-compiled/3` under a filename ending `.model.json`, produced by an upstream gated rigc build. Review uses the public `@rig-c/play` loader and player; Spine JSON/skel is not its input. Its pages are resolved relative to the model document. Missing model means unavailable playback, never a mock playback success. The optional `sets` path declares an attachment-set sidecar for single-package playback. Without that declaration, attachment presets are unavailable. See [Direction inspection](#direction-inspection).
43
43
 
44
44
  Reference `type` is `image`, `video`, or `pose`. `width` and `height` optionally state image pixel dimensions. The primary animated pose input is the canonical `rig-pose-sequence/1` format documented by `@rig-c/pose`, consumed directly:
45
45
 
@@ -892,3 +892,54 @@ Equal UV/index arrays alone are insufficient when compiled vertex data differs.
892
892
  Single Stage-1 controllers retain selection/camera on same-build navigation;
893
893
  cross-revision restoration requires the same original package/image/placement
894
894
  and exact draft skin/slot/attachment address, with named refusal if absent.
895
+
896
+ ### Correction handoff
897
+
898
+ The existing feedback context may carry `correction: {path, selector}` on a
899
+ saved single-package item. The path is `described` or `made`. A selector names
900
+ `{stage:"parts-review",kind:"draft",id}`,
901
+ `{stage:"rig-review",kind:"rig",version}` or
902
+ `{stage:"direction-review",kind:"post",version,modelFile}`. The selector is
903
+ explicit handoff data. The package revision and inspector navigation do not
904
+ supply it. The named model path is data for Create and is never opened by
905
+ Review. Only explicitly marked correction rows can carry multiline text.
906
+
907
+ A supported made item must match the server-owned settled Apply seal and
908
+ retained scratch model and pages when the item is added or changed and on
909
+ selected export. Older unchanged items remain saved as historical evidence
910
+ when a newer Apply or eviction changes the retained scratch builds. A fresh
911
+ selected export still requires its retained result. The check
912
+ must pass with exit zero, a passing gate and at least one PASS bar. Known
913
+ SKIP, WARN, CLEAR, REPORTED and UNCLASSIFIED values and the producer line are
914
+ retained as reported. Missing evidence and failed checks cannot become checked
915
+ claims. A described request and a preserved unsupported operation do not
916
+ assert a result. Selected JSON export is the exact current session file.
917
+
918
+ When a producer config names a requirements file, Review includes the original
919
+ file's path and byte hash in the handoff. Apply copies those bytes into its
920
+ private scratch directory and points the scratch config at that copy. The
921
+ copied input is checked with the retained result. A missing or redirected
922
+ requirements file refuses the handoff or Apply by name.
923
+
924
+ ### Direction inspection
925
+
926
+ In a single-package inspection, **4 Direction** keeps the stage, reference picker
927
+ and Turn Pad visible. The panel names the current model and its SHA-256, the
928
+ package revision and source SHA-256, and the installed Play version. It reports
929
+ the compiled sliders available through the Turn Pad and the attachment sets
930
+ loaded through Play. Independent depth control is unavailable on this surface.
931
+
932
+ A manifest may declare `direction` as the literal package-relative path to a
933
+ retained Create `rig-create/direction@1` document (up to 256 KiB). Preserve the
934
+ document's model path relative to the Review package root. Review requires that
935
+ path and SHA-256 to match the inspected compiled model and includes the direction
936
+ file in the package source hash. The panel shows authored camera keys and timing
937
+ read-only while that inspected model is on stage. Create remains responsible
938
+ for validating project history and citations. Viewport pan and zoom affect only
939
+ inspection. Authored camera playback and camera Apply are unavailable.
940
+
941
+ The optional `sets` manifest path names a package-local Play attachment-set
942
+ sidecar for the inspected single-package build. Review includes it in the
943
+ source hash and loads its sets through the published runtime. Scratch builds
944
+ use their own model and do not inherit the inspected build's sidecar. Compare
945
+ and standalone parts retain their existing inspection surfaces.
package/docs/WORKFLOWS.md CHANGED
@@ -357,3 +357,66 @@ On the view you are inspecting, choose **Comment · C (n)**, drag over the detai
357
357
  The four-stage navigator preserves this entry and its explicit save behavior. Compiled sessions reuse the atlas surface read-only; see [Four inspection stages](PANELS.md#four-inspection-stages).
358
358
 
359
359
  The managed front forwards only the trusted stage-atlas frame query (`stageEmbed=1`, `lang=en|ko`, and a required `side=a|b` for compare; no side for single). Unknown or duplicate keys are refused; the frame carries no filesystem path, command or capability. Stage navigation never changes CLI arguments or package bindings.
360
+
361
+ ## Create choice interview
362
+
363
+ From a create project with retained choice sets, create a dedicated output
364
+ directory and open the foreground Stage 2 view:
365
+
366
+ ```sh
367
+ mkdir -p scratch/review-picks
368
+ rig-review interview . --picks-dir scratch/review-picks
369
+ ```
370
+
371
+ Open the printed loopback URL. Select a question and inspect its bound parts
372
+ or source image. A direction set that binds only source inputs displays those
373
+ inputs with the no-bound-parts notice. Each recommendation shows the retained
374
+ reason and author/date. Choose an option for every prompt and save explicitly.
375
+ Other records your wording and stays pending until a tailored choice is
376
+ offered and picked. Auto stays pending until create has a covered agent
377
+ decision. Historical choice sets are read-only.
378
+
379
+ Each saved set has its own `<raw-set-sha256>.json` in the designated directory.
380
+ Reopening restores picks and note for the same retained set. A new set starts
381
+ without selections. The directory must exist inside the project and be
382
+ separate from every bound input. A stale context, forged selection or
383
+ superseded set is refused. Review writes only `rig-review/interview-picks@1`
384
+ files. To ingest a file, run create separately from the project root:
385
+
386
+ ```sh
387
+ rig-create interview-answer <question> . --picks-file scratch/review-picks/<raw-set-sha256>.json
388
+ ```
389
+
390
+ Part assets must be valid images as well as hash-bound. A bound PNG without a
391
+ PNG signature returns `INTERVIEW_IMAGE_INVALID`. The panel displays a named
392
+ refusal when the browser cannot display a bound image.
393
+
394
+ ## Correction handoff
395
+
396
+ In **Write review**, choose described or made under **Correction handoff** and
397
+ supply the Create review stage and its draft ID or version. A direction-review
398
+ version also needs its declared post model path. Add the feedback and submit.
399
+ A described request stays unresolved. An optional UTF-8 text file supplies
400
+ exact words, including trailing spaces and CRLF. To use an unsent pointed
401
+ comment, fill the Create identity and select **Use as described correction**
402
+ on its row.
403
+
404
+ ```sh
405
+ rig-review feedback <review-package> --correction <saved-item-id> --format issue
406
+ rig-review feedback <review-package> --correction <saved-item-id> --format json
407
+ ```
408
+
409
+ The issue shows the source selector, exact words and evidence. JSON emits the
410
+ original saved single-package session. Pass that retained session and item ID
411
+ to Create's `correction record --feedback-file … --item …` for supported made
412
+ corrections. For a described request, retain the words as UTF-8 and pass them
413
+ to `correction record --verbatim-file …`. Create owns the record and outcome.
414
+ A missing or stale result refuses a checked handoff. Mesh deltas, retarget
415
+ operations and keyed operations retain their original evidence and report
416
+ `CORRECTION_OPERATION_UNSUPPORTED`. Compare sessions remain ordinary evidence.
417
+
418
+ Standalone parts notes and comments use
419
+ `rig-review parts <parts> --format issue --correction <id> --parts-file <inventory>`.
420
+ For a part note, also pass `--part-note <part>` and supply its correction ID.
421
+ Selected parts JSON keeps the saved verdict and adds the correction selection.
422
+ The inventory names a retained Create-side input. Review does not read that path.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/review",
3
- "version": "1.10.2",
3
+ "version": "1.12.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
package/src/cli.ts CHANGED
@@ -2,10 +2,12 @@
2
2
  import {requireFeedbackFrames} from './stage-comment.ts';
3
3
  import {commentCropPaths} from './comment-crops.ts';
4
4
  import {randomBytes} from 'node:crypto';
5
+ import {appliedValue,parseCorrection,projectPartsDescription,projectSessionCorrection} from './correction-handoff.ts';
6
+ import {createRebuilds} from './rebuild.ts';
5
7
  import {readFile} from 'node:fs/promises';
6
8
  import {parseControlCommand} from './control.ts';
7
9
  import { loadReview } from './manifest.ts';
8
- import { formatFeedbackIssues,feedbackWithCommentGroups } from './feedback-export.ts';
10
+ import { formatFeedbackIssues,feedbackWithCommentGroups,formatCorrectionIssue } from './feedback-export.ts';
9
11
  import {loadReferencedReview,selectedReference,assertReviewUnchanged} from './reference.ts';
10
12
  import {animationDiagnostic,selectAnimation} from './animation-selection.ts';
11
13
  import {shellWord} from './open-shell.ts';
@@ -15,14 +17,14 @@ import { readFeedbackSession, readFeedbackCompareSession } from './session-histo
15
17
  import { startServer } from './server.ts';
16
18
  import { loadCompare } from './compare.ts';
17
19
  import { startCompareServer } from './compare-server.ts';
18
- import { loadPartsView, readVerdict, exportPartsVerdict, type PartsViewOptions } from './parts-view.ts';
20
+ import { loadPartsView, readVerdict, exportPartsVerdict, exportPartsCorrection, assertPartsUnchanged, type PartsViewOptions } from './parts-view.ts';
19
21
  import { startPartsServer } from './parts-server.ts';
20
- import { readSession, type Feedback } from './session.ts';
22
+ import { readSession, parseSession, sessionFile, type Feedback } from './session.ts';
21
23
  import { readCompareSession } from './compare-session.ts';
22
24
  import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
23
25
  import type { StripInterval, StripRequest } from './strip.ts';
24
26
  const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]]';
25
- const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--format json|issue]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--port <n>]\n rig-review --version';
27
+ const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one loopback front at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) serves /instances/<key>/; --direct serves the worker on its own port.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--format json|issue] [--correction <item id>]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
26
28
  async function stripCommand(args:string[],options:{stateDir?:string}){
27
29
  const compare=args[0]==='compare';if(compare)args.shift();const a=args.shift(),b=compare?args.shift():undefined;if(!a||compare&&!b)throw new Error('strip: expected package input(s)');
28
30
  let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -66,12 +68,17 @@ async function controlCommand(args:string[],stateDir?:string){
66
68
  const result=await controlReview(inputs,options);console.log(JSON.stringify(result,null,2));if(options.command&&(result as {status?:string}).status!=='applied')process.exitCode=2;
67
69
  }
68
70
  /** Formatting is CLI-only; session lookup/save contracts remain unchanged. */
69
- export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issue'} {
71
+ export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issue';correctionId?:string} {
70
72
  const remaining:string[]=[];let format:'json'|'issue'='json',seen=false,inputs=-1;
73
+ let correctionId:string|undefined;
71
74
  for(let i=0;i<args.length;i++){
72
75
  const token=args[i]!;
73
76
  // Compare owns its next two positional inputs, even when they look like flags.
74
77
  if(inputs>0){remaining.push(token);inputs--;continue;}
78
+ if(token==='--correction'&&inputs===0){
79
+ if(correctionId!==undefined)throw new Error('feedback --correction: duplicate option');
80
+ correctionId=args[++i];if(!correctionId||correctionId.startsWith('--'))throw new Error('feedback --correction: expected feedback item id');continue;
81
+ }
75
82
  if(token==='--format'){
76
83
  if(seen)throw new Error('feedback --format: duplicate option');seen=true;
77
84
  const value=args[++i];if(value!=='json'&&value!=='issue')throw new Error('feedback --format: expected json | issue');format=value;continue;
@@ -82,7 +89,7 @@ export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issu
82
89
  // in particular, --animation may legitimately own the value "--format".
83
90
  const value=args[++i];if(value!==undefined)remaining.push(value);
84
91
  }
85
- return {args:remaining,format};
92
+ return {args:remaining,format,correctionId};
86
93
  }
87
94
  /** Help flags are options; positional inputs and known option values remain literal. */
88
95
  function commandHelpRequested(args:readonly string[],command:'open'|'review'|'check'|'feedback'):boolean {
@@ -95,16 +102,28 @@ function commandHelpRequested(args:readonly string[],command:'open'|'review'|'ch
95
102
  }
96
103
  return false;
97
104
  }
98
- const partsUsage='Usage: rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--port <n>]\n A directory holding parts.json (or a build root whose rig/ holds it) opens in parts mode, before rigging; a review package or check/ folder opens its atlas.\n The sign-off is written to parts-review.json beside parts.json (or the model), or to --verdict.';
105
+ const partsUsage='Usage: rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n A directory holding parts.json (or a build root whose rig/ holds it) opens in parts mode, before rigging; a review package or check/ folder opens its atlas.\n The sign-off is written to parts-review.json beside parts.json (or the model), or to --verdict.';
99
106
  /** `rig-review parts` (#348): the parts and atlas view, served in the foreground; exits when its last tab closes. */
100
107
  async function partsCommand(args:string[]){
101
108
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(partsUsage);return;}
102
109
  const options:PartsViewOptions={};let port=4317,format:'json'|'issue'|null=null;const seen=new Set<string>();
110
+ let itemId:string|undefined,partNote:string|undefined,inventory:string|undefined;
103
111
  while(args.length){const flag=args.shift()!;if(flag==='--help'||flag==='-h'){console.log(partsUsage);return;}if(seen.has(flag))throw new Error(`parts: duplicate option ${flag}`);seen.add(flag);const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);
104
112
  if(flag==='--format'){if(value!=='json'&&value!=='issue')throw new Error('--format: expected json or issue');format=value;}else if(flag==='--painting')options.painting=value;else if(flag==='--rig')options.rig=value;else if(flag==='--mesh-report')options.meshReport=value;else if(flag==='--check')options.check=value;else if(flag==='--verdict')options.verdict=value;
113
+ else if(flag==='--correction')itemId=value;else if(flag==='--part-note')partNote=value;else if(flag==='--parts-file')inventory=value;
105
114
  else if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0..65535');}
106
115
  else throw new Error(`Unknown option ${flag}\n${partsUsage}`);}
116
+ if((itemId||partNote||inventory)&&(!format||!itemId||!inventory))throw new Error('CORRECTION_SELECTOR_INVALID: parts correction requires --format, --correction and --parts-file');
107
117
  const pkg=await loadPartsView(input,options);
118
+ if(format&&itemId&&inventory){
119
+ const saved=await readVerdict(pkg);
120
+ if(!saved.verdict)throw new Error('PARTS_VERDICT_UNAVAILABLE: save a current verdict first');
121
+ await assertPartsUnchanged(pkg);
122
+ const verdict=saved.verdict;
123
+ const projected=projectPartsDescription({verdict,source:verdict.source,selector:{stage:'parts-review',kind:'parts',inventory},selection:partNote?{kind:'note',itemId,part:partNote}:{kind:'comment',itemId}});
124
+ process.stdout.write(format==='json'?exportPartsCorrection(verdict,projected):formatCorrectionIssue(projected)+'\n');
125
+ return;
126
+ }
108
127
  if(format){const saved=await readVerdict(pkg);if(!saved.verdict)throw new Error('PARTS_VERDICT_UNAVAILABLE: save a verdict first');process.stdout.write(exportPartsVerdict(saved.verdict,format));return;}
109
128
  const capability=randomBytes(32).toString('hex'),server=await startPartsServer(pkg,{port,capability,exitOnClose:true});
110
129
  const stop=(sig:string)=>{server.stop(true);console.log(`review parts: exiting — received ${sig}.`);process.exit(0);};process.once('SIGINT',()=>stop('SIGINT'));process.once('SIGTERM',()=>stop('SIGTERM'));
@@ -117,13 +136,15 @@ export async function main(args:string[],options:{stateDir?:string}={}){
117
136
  if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
118
137
  console.log(result.url);if(result.build)console.error(buildOpenDiagnostic(result.build));if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[]),...handoffWords(result.inputs)].map(shellWord).join(' ')}`);return;}
119
138
  if(args[0]==='parts')return partsCommand(args.slice(1));
139
+ if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
120
140
  if(args[0]==='strip'){args.shift();if(args.includes('--help')){console.log(usage+'\nStrip: strip <package> --reference <declared-video-id> --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out path]\n strip compare <a> <b> --reference <video> --animation <name> --basis a|b (--frames FIRST:LAST | --all-feedback) [--json] [--out path]');return;}return stripCommand(args,options);}let command:'review'|'check'|'feedback'='review';if(args[0]==='check'||args[0]==='feedback'){command=args.shift() as 'check'|'feedback';}
121
141
  if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
122
- let format:'json'|'issue'='json';if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;}
142
+ let format:'json'|'issue'='json',correctionId:string|undefined;if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;correctionId=parsed.correctionId;}
123
143
  // Feedback formatting assigns --format/value ownership before the help pass.
124
144
  if(commandHelpRequested(args,command)){console.log(usage);return;}
125
145
  const printFeedback=(session:Parameters<typeof formatFeedbackIssues>[0])=>{const exported=commentCropPaths(session,options.stateDir);console.log(format==='issue'?formatFeedbackIssues(exported).trimEnd():JSON.stringify(feedbackWithCommentGroups(exported),null,2));};
126
146
  if(args[0]==='compare'){
147
+ if(correctionId)throw new Error('CORRECTION_COMPARE_UNSUPPORTED: select a single reviewed package');
127
148
  args.shift();const a=args.shift(),b=args.shift();if(!a||!b)throw new Error(usage);let reference:string|undefined,animation:string|undefined,port=4317;
128
149
  while(args.length){const flag=args.shift(),value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(flag==='--reference')reference=value;else if(flag==='--animation')animation=value;else if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else throw new Error(`Unknown compare option ${flag}`);}
129
150
  if(!reference)throw new Error('compare: --reference and --animation are required');
@@ -139,10 +160,26 @@ export async function main(args:string[],options:{stateDir?:string}={}){
139
160
  const input=args.shift();if(!input)throw new Error(usage);let port=4317;let checkpoint:string|undefined,reference:string|undefined,compare:string|undefined,animation:string|undefined,viewOnly=false;const handoff:OpenInputs={input};
140
161
  while(args.length){const flag=args.shift();if(flag==='--view-only'){if(command!=='review')throw new Error(`Unknown option ${flag}\n${usage}`);viewOnly=true;continue;}const value=args.shift();if(!value)throw new Error(`Missing value for ${flag}`);if(handoffOption(flag!)){handoff[handoffOption(flag!)!]=value;continue;}if(flag==='--port'){port=Number(value);if(!Number.isInteger(port)||port<0||port>65535)throw new Error('--port: expected integer 0…65535');}else if(flag==='--checkpoint')checkpoint=value;else if(flag==='--reference')reference=value;else if(flag==='--compare')compare=value;else if(flag==='--animation')animation=value;else throw new Error(`Unknown option ${flag}\n${usage}`);}
141
162
  const handoffProblem=checkHandoffFlags(handoff);if(handoffProblem)throw new Error(handoffProblem);if(compare&&handoffFlags(handoff))throw new Error('--config: compare takes no producer handoff');
142
- if(compare){if(command!=='feedback')throw new Error('--compare: use open or feedback');const loaded=await loadOpenPackage({input,compare,reference,animation});if(loaded.mode!=='compare')throw new Error('Expected comparison');printFeedback(await readFeedbackCompareSession(loaded.p,options.stateDir));return;}
163
+ if(compare){if(correctionId)throw new Error('CORRECTION_COMPARE_UNSUPPORTED: select a single reviewed package');if(command!=='feedback')throw new Error('--compare: use open or feedback');const loaded=await loadOpenPackage({input,compare,reference,animation});if(loaded.mode!=='compare')throw new Error('Expected comparison');printFeedback(await readFeedbackCompareSession(loaded.p,options.stateDir));return;}
143
164
  const p=await loadReferencedReview(input,reference,handoffFlags(handoff));if(viewOnly)p.viewOnly=true;// Serving starts on the report's clip when it names one; check and feedback validate only an explicit flag.
144
165
  const fromReport=command==='review'&&animation===undefined&&p.report?.animation!==undefined;
145
- const selection=animation!==undefined||fromReport?selectAnimation([{label:'single',catalog:p.feedbackCatalog,report:p.report}],animation,true):null;const initialAnimation=selection?.name;if(command==='feedback'){const saved=await readFeedbackSession(p,options.stateDir);await assertReviewUnchanged(p);printFeedback(saved);return;}if(command==='check'){console.log(`Package valid: ${p.manifest.title}\nRevision: ${p.manifest.revision}\nSource SHA-256: ${p.sourceHash}\nDeclared files: ${p.files.size}\nPlayback: ${p.manifest.model?'compiled model present':'unavailable (no model)'}`);return;}
166
+ const selection=animation!==undefined||fromReport?selectAnimation([{label:'single',catalog:p.feedbackCatalog,report:p.report}],animation,true):null;const initialAnimation=selection?.name;if(command==='feedback'&&correctionId){
167
+ const stateDir=options.stateDir!;
168
+ const bytes=await readFile(sessionFile(p,stateDir)).catch(error=>{if(error.code==='ENOENT')throw new Error('CORRECTION_ITEM_INVALID: save a correction first');throw error;});
169
+ const session=parseSession(JSON.parse(bytes.toString('utf8')),p,false);
170
+ const item=session.feedback.find(row=>row.id===correctionId);
171
+ const correction=parseCorrection((item?.context as any)?.correction);
172
+ if(!item||!correction||session.feedbackWarnings.some(warning=>warning.id===item.id))throw new Error('CORRECTION_ITEM_INVALID: expected a valid saved correction');
173
+ const source={id:p.manifest.id,revision:p.manifest.revision,sourceHash:p.sourceHash,reviewedSource:p.reviewedSource};
174
+ await assertReviewUnchanged(p);
175
+ const rebuilds=createRebuilds(p,{stateDir,starts:[p.root,process.cwd()],unchanged:()=>assertReviewUnchanged(p),bones:p.feedbackCatalog.bones});
176
+ const settled=correction.path==='made'&&correction.selector.kind!=='post'?await rebuilds.correctionEvidence(appliedValue(item)):undefined;
177
+ const projected=projectSessionCorrection({...correction,session,sessionBytes:bytes,source,itemId:item.id,settled});
178
+ if(projected.kind==='unsupported')console.error('CORRECTION_OPERATION_UNSUPPORTED: '+projected.operation);
179
+ process.stdout.write(format==='json'?bytes:formatCorrectionIssue(projected,item.context)+'\n');
180
+ return;
181
+ }
182
+ if(command==='feedback'){const saved=await readFeedbackSession(p,options.stateDir);await assertReviewUnchanged(p);printFeedback(saved);return;}if(command==='check'){console.log(`Package valid: ${p.manifest.title}\nRevision: ${p.manifest.revision}\nSource SHA-256: ${p.sourceHash}\nDeclared files: ${p.files.size}\nPlayback: ${p.manifest.model?'compiled model present':'unavailable (no model)'}`);return;}
146
183
  if(checkpoint&&!p.manifest.checkpoints.some(v=>v.id===checkpoint))throw new Error(`Unknown checkpoint ${checkpoint}`);
147
184
  // Foreground serving uses the same `#cap=` fragment handoff as open: the printed link alone can submit.
148
185
  const capability=randomBytes(32).toString('hex'),server=await startServer(p,{port,stateDir:options.stateDir,initialAnimation,capability,exitOnClose:true,viewOnly});const url=new URL(`http://127.0.0.1:${server.port}/`);if(checkpoint)url.searchParams.set('checkpoint',checkpoint);url.hash='cap='+capability;
@@ -0,0 +1,186 @@
1
+ /** Internal projection from canonical Review evidence. No filesystem, wire format or create invocation. */
2
+ import { isDeepStrictEqual } from 'node:util';
3
+ import { APPLIED_ANIMATION_SCHEMA, APPLIED_DELTA_SCHEMA, APPLIED_PATCH_SCHEMA, APPLIED_RETARGET_SCHEMA, parseAppliedContext, type AppliedPatch } from './applied-context.ts';
4
+ import { patchSha256, patchText } from './config-patch.ts';
5
+ import type { PartsVerdict } from './parts-view.ts';
6
+ import type { Feedback, ReviewSession } from './session.ts';
7
+
8
+ type Selector =
9
+ | { stage: 'parts-review'; kind: 'parts'; inventory: string }
10
+ | { stage: 'parts-review'; kind: 'draft'; id: string }
11
+ | { stage: 'rig-review'; kind: 'rig'; version: number }
12
+ | { stage: 'direction-review'; kind: 'post'; version: number; modelFile: string };
13
+
14
+ type SessionSource = Pick<ReviewSession, 'id' | 'revision' | 'sourceHash' | 'reviewedSource'>;
15
+ type SessionSelector = Exclude<Selector, { kind: 'parts' }>;
16
+
17
+ /**
18
+ * The caller must obtain this from the verified server-side settled Apply and
19
+ * independently verify the retained operation and result bytes. Client context
20
+ * or a status flag cannot establish this precondition.
21
+ */
22
+ interface SettledEvidence {
23
+ source: SessionSource;
24
+ applied: unknown;
25
+ operationSha256: string;
26
+ modelSha256: string;
27
+ }
28
+
29
+ type SessionInput = {
30
+ // Already read and validated through Review's canonical saved-session path.
31
+ session: ReviewSession;
32
+ // Exact bytes of the same retained session, validated by the reader.
33
+ sessionBytes: Uint8Array;
34
+ source: SessionSource;
35
+ selector: SessionSelector;
36
+ itemId: string;
37
+ } & ({ path: 'described' } | { path: 'made'; settled?: SettledEvidence });
38
+
39
+ const hash = (value: string) => /^[a-f0-9]{64}$/.test(value);
40
+ const id = (value: string) => /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value);
41
+ const checkStatuses = new Set(['PASS', 'SKIP', 'WARN', 'CLEAR', 'REPORTED', 'UNCLASSIFIED']);
42
+ const nonblank = (value: string) => value.trim().length > 0;
43
+
44
+ function refuse(code: string, reason: string): never {
45
+ throw new Error(`${code}: ${reason}`);
46
+ }
47
+
48
+ export function parseCorrection(value: unknown): { path: 'described' | 'made'; selector: SessionSelector } | undefined {
49
+ if (value === undefined) return undefined;
50
+ const invalid = () => refuse('CORRECTION_SELECTOR_INVALID', 'expected explicit correction path and create selector');
51
+ if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 2) return invalid();
52
+ const { path, selector } = value as { path?: unknown; selector?: unknown };
53
+ if ((path !== 'described' && path !== 'made') || !selector || typeof selector !== 'object' || Array.isArray(selector)) return invalid();
54
+ const v = selector as Record<string, unknown>;
55
+ if (v.kind === 'draft' && v.stage === 'parts-review' && typeof v.id === 'string' && id(v.id) && Object.keys(v).length === 3) {
56
+ return { path, selector: { kind: 'draft', stage: 'parts-review', id: v.id } };
57
+ }
58
+ if (typeof v.version === 'number' && Number.isSafeInteger(v.version) && v.version > 0) {
59
+ if (v.kind === 'rig' && v.stage === 'rig-review' && Object.keys(v).length === 3) return { path, selector: { kind: 'rig', stage: 'rig-review', version: v.version } };
60
+ if (v.kind === 'post' && v.stage === 'direction-review' && portablePath(v.modelFile) && Object.keys(v).length === 4) {
61
+ return { path, selector: { kind: 'post', stage: 'direction-review', version: v.version, modelFile: v.modelFile } };
62
+ }
63
+ }
64
+ return invalid();
65
+ }
66
+
67
+ function portablePath(value: unknown): value is string {
68
+ return typeof value === 'string' && value.length <= 512 && /^[A-Za-z0-9_. /-]+$/.test(value) &&
69
+ value.split('/').every(part => nonblank(part) && part !== '.' && part !== '..' && !part.startsWith('-'));
70
+ }
71
+
72
+ function selectorArgs(selector: Selector): readonly string[] {
73
+ if (selector.kind === 'parts' && selector.stage === 'parts-review' && portablePath(selector.inventory)) return ['--parts-file', selector.inventory];
74
+ if (selector.kind === 'draft' && selector.stage === 'parts-review' && id(selector.id)) return ['--draft', selector.id];
75
+ if ((selector.kind === 'rig' || selector.kind === 'post') && Number.isSafeInteger(selector.version) && selector.version > 0) {
76
+ const version = ['--version', String(selector.version)];
77
+ if (selector.kind === 'rig' && selector.stage === 'rig-review') return version;
78
+ if (selector.kind === 'post' && selector.stage === 'direction-review' && portablePath(selector.modelFile)) return [...version, '--model-file', selector.modelFile];
79
+ }
80
+ return refuse('CORRECTION_SELECTOR_INVALID', 'explicit create identity for this stage required');
81
+ }
82
+
83
+ function itemWords(itemId: string, summary: string): string {
84
+ if (!id(itemId) || !nonblank(summary) || Buffer.from(summary).toString('utf8') !== summary) {
85
+ return refuse('CORRECTION_ITEM_INVALID', 'create-compatible id and nonblank UTF-8 words required');
86
+ }
87
+ return summary;
88
+ }
89
+
90
+ function sessionSource({ id, revision, sourceHash, reviewedSource }: SessionSource): SessionSource {
91
+ return { id, revision, sourceHash, reviewedSource };
92
+ }
93
+
94
+ export function appliedValue(item: Feedback): unknown {
95
+ const { context } = item;
96
+ return context && typeof context === 'object' && !Array.isArray(context) ? context.applied : null;
97
+ }
98
+
99
+ function unsupportedOperation(schema: string): string {
100
+ switch (schema) {
101
+ case APPLIED_DELTA_SCHEMA: return 'mesh-delta';
102
+ case APPLIED_RETARGET_SCHEMA: return 'retarget';
103
+ case APPLIED_ANIMATION_SCHEMA: return 'keyed-animation';
104
+ default: return 'other';
105
+ }
106
+ }
107
+
108
+ export function projectSessionCorrection(input: SessionInput) {
109
+ const { session, sessionBytes, selector, source, itemId } = input;
110
+ const on = selectorArgs(selector);
111
+ if (!hash(source.sourceHash) || !isDeepStrictEqual(sessionSource(session), source)) {
112
+ return refuse('CORRECTION_SOURCE_STALE', 'saved session differs from verified source');
113
+ }
114
+ const matches = session.feedback.filter(item => item.id === itemId);
115
+ const item = matches[0];
116
+ if (matches.length !== 1 || !item) return refuse('CORRECTION_ITEM_INVALID', 'expected one saved feedback item');
117
+ const verbatim = itemWords(itemId, item.summary);
118
+ const common = { itemId, verbatim, stage: selector.stage, on, source, target: item.target };
119
+ if (input.path === 'described') return { ...common, kind: 'described' as const, outcome: null };
120
+
121
+ const value = appliedValue(item);
122
+ if (value == null) return refuse('CORRECTION_APPLY_PENDING', 'no settled Apply in the saved item');
123
+ try {
124
+ parseAppliedContext(value);
125
+ } catch (error) {
126
+ return refuse('CORRECTION_APPLY_INVALID', error instanceof Error ? error.message : String(error));
127
+ }
128
+ const { schema } = value as { schema: string };
129
+ if (schema !== APPLIED_PATCH_SCHEMA || selector.kind === 'post') {
130
+ return { ...common, kind: 'unsupported' as const, operation: unsupportedOperation(schema), applied: value, sessionBytes, outcome: null };
131
+ }
132
+
133
+ const applied = value as AppliedPatch;
134
+ const { settled } = input;
135
+ if (!settled) return refuse('CORRECTION_APPLY_PENDING', 'verified server-side settled evidence is required');
136
+ if (!isDeepStrictEqual(source, settled.source) || !isDeepStrictEqual(applied, settled.applied) ||
137
+ applied.configHash !== source.reviewedSource.handoff?.config.sha256) {
138
+ return refuse('CORRECTION_APPLY_STALE', 'saved Apply differs from settled source or operation');
139
+ }
140
+ const { rig, motion, handoff } = source.reviewedSource;
141
+ if (!rig || motion !== null || !handoff || handoff.missing.length) {
142
+ return refuse('CORRECTION_SOURCE_UNSUPPORTED', 'create requires a compiled source with a complete supported handoff');
143
+ }
144
+ if (!applied.diff) return refuse('CORRECTION_APPLY_INVALID', 'create requires the retained rig diff');
145
+ const { check, patch, producer } = applied;
146
+ if (!check || check.pass !== true || check.exitCode !== 0 || check.gate !== true ||
147
+ (check.source !== 'retune' && check.source !== 'remesh' && check.source !== 'check') ||
148
+ !check.line?.trim() || !Object.values(check.bars).includes('PASS') ||
149
+ Object.values(check.bars).some(status => !checkStatuses.has(status)) ||
150
+ /\b\d+ of \d+ bar\(s\) measured, \d+ skipped \(([^)]*)\)/.exec(check.line)?.[1]?.split(', ').some(name => check.bars[name] === 'PASS')) {
151
+ return refuse('CORRECTION_CHECK_FAILED', 'the settled Apply requires a passing producer check');
152
+ }
153
+ if (!applied.line?.trim() || producer.package !== patch.producer.name || producer.version !== patch.producer.version ||
154
+ patchSha256(patch) !== applied.patchSha256 || settled.operationSha256 !== applied.patchSha256) {
155
+ return refuse('CORRECTION_ARTIFACT_MISMATCH', 'producer or canonical patch binding differs');
156
+ }
157
+ if (settled.modelSha256 !== applied.modelHash || (selector.kind === 'rig' && rig.sha256 === applied.modelHash)) {
158
+ return refuse('CORRECTION_OUTCOME_MISMATCH', 'expected the bound scratch result');
159
+ }
160
+ return { ...common, kind: 'checked-patch' as const, applied, sessionBytes, patchBytes: patchText(patch), outcome: null };
161
+ }
162
+
163
+ /** Standalone parts notes and pointed comments keep their original parts identity. */
164
+ export function projectPartsDescription(input: {
165
+ verdict: PartsVerdict;
166
+ source: PartsVerdict['source'];
167
+ selector: Extract<Selector, { kind: 'parts' }>;
168
+ selection: { kind: 'comment'; itemId: string } | { kind: 'note'; itemId: string; part: string };
169
+ }) {
170
+ const { verdict, source, selector, selection } = input;
171
+ const on = selectorArgs(selector);
172
+ if (verdict.mode !== 'parts' || !hash(source.sha256) || !isDeepStrictEqual(verdict.source, source)) {
173
+ return refuse('CORRECTION_SOURCE_STALE', 'saved parts verdict differs from verified parts');
174
+ }
175
+ const { itemId } = selection;
176
+ if (selection.kind === 'comment') {
177
+ const matches = verdict.comments.filter(comment => comment.id === itemId);
178
+ const item = matches[0];
179
+ if (matches.length !== 1 || !item || item.sourceHash !== source.sha256) {
180
+ return refuse('CORRECTION_ITEM_INVALID', 'expected one source-bound parts comment');
181
+ }
182
+ return { kind: 'described' as const, itemId, verbatim: itemWords(itemId, item.summary), stage: selector.stage, on, source, part: item.part, imageHash: item.imageHash, comment: item, outcome: null };
183
+ }
184
+ if (!Object.hasOwn(verdict.parts, selection.part)) return refuse('CORRECTION_ITEM_INVALID', 'expected a saved part note');
185
+ return { kind: 'described' as const, itemId, verbatim: itemWords(itemId, verdict.parts[selection.part]!.note), stage: selector.stage, on, source, part: selection.part, outcome: null };
186
+ }
@@ -0,0 +1,65 @@
1
+ import { numberField, object, packagePath } from './manifest.ts';
2
+
3
+ export const DIRECTION_MAX_BYTES = 256 * 1024;
4
+
5
+ type Binding = { path: string; sha256: string };
6
+ export interface DirectionInspection {
7
+ file: Binding;
8
+ rigVersion: number;
9
+ camera: { space: 'rig-world-y-up'; keys: { time: number; easing: string; box: { x: number; y: number; width: number; height: number } }[] };
10
+ take: { duration: number; loop: boolean };
11
+ timing: { time: number; source_time: number; easing: string }[];
12
+ }
13
+
14
+ /** Read the inspection subset of Create's direction@1. Create validates project history and citations. */
15
+ export function readDirectionInspection(value: unknown, file: Binding, model: Binding | null): DirectionInspection {
16
+ const doc = object(value, 'direction');
17
+ if (doc.schema !== 'rig-create/direction@1') throw new Error('DIRECTION_SCHEMA: expected rig-create/direction@1');
18
+ const rig = object(doc.rig, 'direction.rig');
19
+ const binding = object(rig.model, 'direction.rig.model');
20
+ const path = packagePath(binding.path, 'direction.rig.model.path');
21
+ if (!model || path !== model.path || binding.sha256 !== model.sha256)
22
+ throw new Error('DIRECTION_MODEL_MISMATCH: expected the inspected model path and SHA-256');
23
+ const rigVersion = numberField(rig.version, 'direction.rig.version', 1);
24
+ if (!Number.isSafeInteger(rigVersion)) throw new Error('DIRECTION_SCHEMA: expected integer rig version');
25
+ const take = object(doc.take, 'direction.take');
26
+ const duration = numberField(take.duration, 'direction.take.duration');
27
+ if (duration === 0 || typeof take.loop !== 'boolean') throw new Error('DIRECTION_SCHEMA: expected positive duration and loop boolean');
28
+ const camera = object(doc.camera, 'direction.camera');
29
+ const timing = object(doc.timing, 'direction.timing');
30
+ if (camera.space !== 'rig-world-y-up') throw new Error('DIRECTION_SCHEMA: expected rig-world-y-up camera');
31
+ function keys<T>(value: unknown, section: string, min: number, parse: (key: Record<string, unknown>, field: string) => T) {
32
+ if (!Array.isArray(value) || value.length < min || value.length > 256)
33
+ throw new Error(`DIRECTION_SCHEMA: invalid ${section} key count`);
34
+ let previous = -Infinity;
35
+ return value.map((raw, index) => {
36
+ const field = `direction.${section}.keys[${index}]`;
37
+ const key = object(raw, field);
38
+ const time = numberField(key.time, field + '.time');
39
+ if (time <= previous || time > duration || (index === 0 && time !== 0))
40
+ throw new Error('DIRECTION_SCHEMA: expected increasing keys within the take starting at zero');
41
+ previous = time;
42
+ const easing = key.easing;
43
+ if (easing !== 'linear' && easing !== 'hold' && easing !== 'smoothstep')
44
+ throw new Error('DIRECTION_SCHEMA: unknown easing');
45
+ return { time, easing, ...parse(key, field) };
46
+ });
47
+ }
48
+ const cameraKeys = keys(camera.keys, 'camera', 1, (key, field) => {
49
+ const box = object(key.box, field + '.box');
50
+ const x = numberField(box.x, field + '.box.x', -Infinity);
51
+ const y = numberField(box.y, field + '.box.y', -Infinity);
52
+ const width = numberField(box.width, field + '.box.width');
53
+ const height = numberField(box.height, field + '.box.height');
54
+ if (width === 0 || height === 0) throw new Error('DIRECTION_SCHEMA: expected positive camera box dimensions');
55
+ return { box: { x, y, width, height } };
56
+ });
57
+ let previousSource = 0;
58
+ const timingKeys = keys(timing.keys, 'timing', 2, (key, field) => {
59
+ const source_time = numberField(key.source_time, field + '.source_time', previousSource);
60
+ previousSource = source_time;
61
+ return { source_time };
62
+ });
63
+ if (timingKeys.at(-1)?.time !== duration) throw new Error('DIRECTION_SCHEMA: timing must end at take duration');
64
+ return { file, rigVersion, camera: { space: camera.space, keys: cameraKeys }, take: { duration, loop: take.loop }, timing: timingKeys };
65
+ }
@@ -244,3 +244,17 @@ export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
244
244
  }
245
245
  return lines.join('\n') + '\n';
246
246
  }
247
+
248
+ /** Selected handoff uses the existing issue export surface with exact JSON-escaped words and evidence. */
249
+ export function formatCorrectionIssue(
250
+ correction: {kind:string;itemId:string;stage:string;on:readonly string[];verbatim:string;source:unknown;operation?:string;patchBytes?:string;target?:unknown;part?:string;imageHash?:string;comment?:import('./parts-comment.ts').PartsComment},
251
+ context?:Json,
252
+ ): string {
253
+ const state=correction.kind==='described'?'Unresolved request':
254
+ correction.kind==='unsupported'?'CORRECTION_OPERATION_UNSUPPORTED — '+correction.operation:'Checked scratch Apply — create result pending';
255
+ const comment=correction.comment;
256
+ const evidence=comment?{...comment,crop:{...comment.crop,png:undefined}}:undefined;
257
+ return ['## Correction handoff','',state,'',
258
+ jsonBlock({itemId:correction.itemId,stage:correction.stage,selectorArgs:correction.on,
259
+ source:correction.source,verbatim:correction.verbatim,target:correction.target,part:correction.part,imageHash:correction.imageHash,comment:evidence,...(correction.patchBytes===undefined?{}:{patchBytes:correction.patchBytes}),context})].join('\n');
260
+ }
package/src/handoff.ts CHANGED
@@ -35,7 +35,8 @@ export const MODELING_INPUT_UNAVAILABLE = `MODELING_INPUT_UNAVAILABLE: config.js
35
35
  export const BUILD_DISCOVERY_PLACES = ['../config.json (in the build root)', '../../config.json (beside the build root)'] as const;
36
36
  export const BUILD_MODELING_INPUT_UNAVAILABLE = `MODELING_INPUT_UNAVAILABLE: config.json — looked at ${[...DISCOVERY_PLACES.slice(0, 2), ...BUILD_DISCOVERY_PLACES].join(', ')}; declare it with ${HANDOFF_DECLARATION}`;
37
37
  /** Files the producer reads by the config's own naming, resolved against the config's directory (rig-parts `relativeConfigPaths`). */
38
- export const CONFIG_NAMED_FILES = [['motion', 'animations_from'], ['generation', 'control', 'skeleton']] as const;
38
+ export const CONFIG_NAMED_FILES = [['requirements'], ['motion', 'animations_from'], ['generation', 'control', 'skeleton']] as const;
39
+ export const CONFIG_SKELETON_NAMES = ['stand_sides', 'stand_clasp'] as const;
39
40
  /** What `rig-parts rig` writes into its --out and remesh reads from --rig: the rig spec, its motion, the mesh report and the part images. */
40
41
  export const RIG_FILES = ['rig.json', 'motion.json', 'mesh_report.json'] as const;
41
42
  const MAX_LISTED = 4096;
@@ -190,10 +191,19 @@ async function record(root: string, base: string, how: HandoffRecord['how'], via
190
191
  let value: unknown = parsed;
191
192
  for (const k of keys) value = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>)[k] : undefined;
192
193
  if (typeof value !== 'string' || !value) continue;
194
+ if (keys.length === 3 && (CONFIG_SKELETON_NAMES as readonly string[]).includes(value)) continue;
193
195
  const field = `config ${keys.join('.')}`, lexical = resolve(dirname(config), value);
194
196
  if (!inside(base, lexical)) throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${value} resolves outside ${base}`);
197
+ if (keys[0] === 'requirements' && (isAbsolute(value) || /[:\\%?#\x00-\x1f]/.test(value) ||
198
+ value.split('/').some(part => !part || part === '.' || part === '..'))) {
199
+ throw new HandoffError('HANDOFF_PATH_INVALID', field, 'expected a literal portable config-relative path');
200
+ }
195
201
  if (!(await exists(lexical))) { missing.push(`${keys.join('.')} ${show(lexical)}`); continue; }
196
- await add(await contained(base, lexical, field, 'file', true));
202
+ const file = await contained(base, lexical, field, 'file', true);
203
+ if (keys[0] === 'requirements' && file !== lexical) {
204
+ throw new HandoffError('HANDOFF_PATH_INVALID', field, 'expected a regular file without a symlink alias');
205
+ }
206
+ await add(file);
197
207
  }
198
208
  let parts: string | null = null, rig: string | null = null;
199
209
  if (partsPath && (partsDeclared || await exists(partsPath))) {