rig-review 1.14.1 → 1.16.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/PANELS.md CHANGED
@@ -475,12 +475,12 @@ Reset returns to the inspected revision. New scratch reads and made-mesh feedbac
475
475
  submissions recheck pinned producer inputs, revision files and compiled files.
476
476
  A changed scratch input cannot inherit clean checked evidence.
477
477
 
478
- The embedding is read-only: original verdicts and comments are never copied onto
478
+ The compiled inspection embedding is read-only: original verdicts and comments are never copied onto
479
479
  scratch geometry or saved by navigating. Use the standalone `parts` command for
480
480
  its separate explicit original-parts sign-off. Parts-only inputs remain
481
481
  inspectable and name `STAGE_DRAFT_UNAVAILABLE` for direct correction. A missing
482
482
  handoff keeps the inspected atlas available where supplied. Compare retains its
483
- read-only, side-specific inspected atlas. Neither flow guesses a sibling draft.
483
+ read-only, side-specific inspected atlas. Neither flow guesses a sibling draft. A [joined Create draft](WORKFLOWS.md#open-a-recorded-draft-before-rig-review) displays its recorded parts and mesh without a production rig package. A pending parts review with an explicit output directory can save a separate verdict here.
484
484
 
485
485
  Named draft boundaries are `STAGE_DRAFT_UNAVAILABLE`, `STAGE_DRAFT_MISMATCH`,
486
486
  `STAGE_DRAFT_STALE`, `STAGE_DRAFT_CHANGED`, `STAGE_DRAFT_UNCHECKED` and
@@ -932,6 +932,21 @@ inspection context. To import into Create:
932
932
  `on.model` and `on.direction`, and an open description (`outcome: null`).
933
933
  Create retains `source` as opaque text. Review runs no Create command.
934
934
 
935
+ For a joined Create project, `--project-version` selects the recorded rig
936
+ package and optional `--post-version` selects its authored post. Review checks
937
+ the package inventory and derives the exact project-relative path from the
938
+ inspected package model inside that inventory. The direction document must
939
+ bind this path and its SHA-256. The project's direction stays outside the
940
+ package asset routes. The joined session source binds the project digest,
941
+ package source, rig version, selected post and direction file. Reopen if any
942
+ of these inputs change.
943
+
944
+ In Review's correction form use the selected post and the inspected
945
+ package-relative model path. In the issue export, `selectorArgs` and
946
+ `createSource.model` use the original Create project-relative model path.
947
+ `createSource.inspectedModel` retains the package-relative binding. Use the
948
+ same joined arguments on the feedback command to retrieve the joined session.
949
+
935
950
  Packages without authored direction continue to use their explicit legacy
936
951
  selector. Direction patch Apply is unavailable. Existing supported rig and
937
952
  draft Apply records keep their producer and result evidence.
package/docs/WORKFLOWS.md CHANGED
@@ -378,6 +378,34 @@ requires reopening and a project without interview content reports
378
378
  Use **Save explicit picks** to persist pending choices. Historical answers
379
379
  remain read-only and opening or saving picks does not sign off any stage.
380
380
 
381
+ To inspect authored direction in **4 Direction**, add `--post-version <post>`
382
+ to the joined command. The post must explicitly name the selected
383
+ `--project-version` rig and bind an authored direction document. Reuse the
384
+ printed feedback command, including the project, rig, post and picks arguments,
385
+ to export from that session.
386
+
387
+ ### Open a recorded draft before rig review
388
+
389
+ Select a Create draft explicitly and open its recorded compiled check directory.
390
+ Create the picks directory and, for a pending parts verdict, a separate verdict
391
+ directory inside the project before opening the host.
392
+
393
+ ```sh
394
+ rig-review open /path/to/project/derived/drafts/chain/out/check \
395
+ --project /path/to/project --project-draft chain --picks-dir scratch/review-picks \
396
+ --parts-verdict-dir scratch/review-verdicts
397
+ ```
398
+
399
+ **1 Parts + mesh** displays the draft's recorded parts and matching mesh.
400
+ Use **Save sign-off** to write a standard parts verdict with the part and mesh
401
+ outcomes and notes. Its filename is bound to the inspected project and source.
402
+ Keep the JSON file at its saved location for Create to resolve the source paths.
403
+ The verdict does not sign the Create project. A closed parts review or an open
404
+ without `--parts-verdict-dir` keeps this surface read-only. **2 Interview**
405
+ offers the registered pending sets and displays historical answers read-only.
406
+ **3 Rig + animation** and **4 Direction** report that the recorded rig review
407
+ package is unavailable. Reopen with a rig version once Create records one.
408
+
381
409
  From a create project with retained choice sets, create a dedicated output
382
410
  directory and open the foreground Stage 2 view:
383
411
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "1.14.1",
3
+ "version": "1.16.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,6 +2,7 @@
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 {joinProject} from './joined-project.ts';
5
6
  import {appliedValue,parseCorrection,projectPartsDescription,projectSessionCorrection} from './correction-handoff.ts';
6
7
  import {createRebuilds} from './rebuild.ts';
7
8
  import {readFile} from 'node:fs/promises';
@@ -24,7 +25,7 @@ import { readCompareSession } from './compare-session.ts';
24
25
  import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
25
26
  import type { StripInterval, StripRequest } from './strip.ts';
26
27
  const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]]';
27
- const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> --project-version <n> --picks-dir <dir>] '+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';
28
+ const usage='Usage: rig-review open <dir> [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+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+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--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';
28
29
  async function stripCommand(args:string[],options:{stateDir?:string}){
29
30
  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)');
30
31
  let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -44,17 +45,26 @@ async function stripCommand(args:string[],options:{stateDir?:string}){
44
45
  }
45
46
  /** `--config` → `config` for the producer handoff flags (#101), else null. */
46
47
  function handoffOption(flag:string):(typeof HANDOFF_FLAGS)[number]|null {const name=flag.slice(2);return flag.startsWith('--')&&(HANDOFF_FLAGS as readonly string[]).includes(name)?name as (typeof HANDOFF_FLAGS)[number]:null;}
47
- const projectFlags = ['--project','--project-version','--picks-dir'];
48
+ const projectFlags = ['--project','--project-version','--picks-dir','--post-version','--project-draft','--parts-verdict-dir'];
48
49
  /** The retrieval words for the handoff flags, in their fixed order. */
50
+ const projectWords=(inputs:OpenInputs)=>{const p=inputs.project;return p?[
51
+ '--project',p.root,...(p.draftId===undefined?['--project-version',String(p.version)]:['--project-draft',p.draftId]),'--picks-dir',p.picksDir,
52
+ ...(p.partsVerdictDir===undefined?[]:['--parts-verdict-dir',p.partsVerdictDir]),
53
+ ...(p.postVersion===undefined?[]:['--post-version',String(p.postVersion)]),
54
+ ]:[];};
49
55
  const handoffWords=(inputs:OpenInputs)=>HANDOFF_FLAGS.flatMap(f=>inputs[f]!==undefined?['--'+f,inputs[f]!]:[]);
50
56
  export function parseOpenInputs(args:string[]):OpenInputs {
51
57
  const input=args.shift();if(!input||input.startsWith('--'))throw new Error(usage);const result:OpenInputs={input},seen=new Set<string>();
52
- let root:string|undefined,version:string|undefined,picksDir:string|undefined;
53
- while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}if(flag==='--view-only'){result.viewOnly=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else if(flag==='--project')root=value;else if(flag==='--project-version')version=value;else if(flag==='--picks-dir')picksDir=value;else if(handoffOption(flag))result[handoffOption(flag)!]=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}
54
- if(root!==undefined||version!==undefined||picksDir!==undefined){
55
- if(!root||!picksDir||!version||!/^\d+$/.test(version)||!Number.isSafeInteger(Number(version))||Number(version)<1||result.compare!==undefined)
56
- throw new Error('OPEN_OPTION_INVALID --project: single-package open requires --project, --project-version and --picks-dir together');
57
- result.project={root,version:Number(version),picksDir};
58
+ let root:string|undefined,version:string|undefined,postVersion:string|undefined,picksDir:string|undefined,draftId:string|undefined,partsVerdictDir:string|undefined;
59
+ while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}if(flag==='--view-only'){result.viewOnly=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else if(flag==='--project')root=value;else if(flag==='--project-version')version=value;else if(flag==='--picks-dir')picksDir=value;else if(flag==='--project-draft')draftId=value;else if(flag==='--parts-verdict-dir')partsVerdictDir=value;else if(flag==='--post-version')postVersion=value;else if(handoffOption(flag))result[handoffOption(flag)!]=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}
60
+ if(root!==undefined||version!==undefined||picksDir!==undefined||postVersion!==undefined||draftId!==undefined||partsVerdictDir!==undefined){
61
+ if(!root||!picksDir||(Boolean(version)===Boolean(draftId))||result.compare!==undefined||version!==undefined&&(!/^\d+$/.test(version)||!Number.isSafeInteger(Number(version))||Number(version)<1))
62
+ throw new Error('OPEN_OPTION_INVALID --project: single-package open requires --project, --picks-dir and one of --project-version or --project-draft together');
63
+ if(postVersion!==undefined&&(!/^\d+$/.test(postVersion)||!Number.isSafeInteger(Number(postVersion))||Number(postVersion)<1))
64
+ throw new Error('OPEN_OPTION_INVALID --post-version: expected a positive Create post version');
65
+ if(draftId&&postVersion)throw new Error('OPEN_OPTION_INVALID --post-version: requires --project-version');
66
+ if(partsVerdictDir&&(!draftId||result.viewOnly))throw new Error('OPEN_OPTION_INVALID --parts-verdict-dir: requires a writable --project-draft');
67
+ result.project=draftId?{root,draftId,picksDir,...(partsVerdictDir?{partsVerdictDir}:{})}:{root,version:Number(version),picksDir,...(postVersion!==undefined?{postVersion:Number(postVersion)}:{})};
58
68
  }
59
69
  const problem=checkHandoffFlags(result);if(problem)throw new Error(`OPEN_OPTION_INVALID ${problem.split(':')[0]}: ${problem.slice(problem.indexOf(':')+2)}`);
60
70
  if(result.compare!==undefined&&handoffFlags(result))throw new Error('OPEN_OPTION_INVALID --config: compare takes no producer handoff; open one package with --config');
@@ -104,7 +114,7 @@ export function feedbackFormat(args:string[]):{args:string[];format:'json'|'issu
104
114
  function commandHelpRequested(args:readonly string[],command:'open'|'review'|'check'|'feedback'):boolean {
105
115
  if(args[0]==='--help'||args[0]==='-h')return true;
106
116
  const compare=command!=='open'&&args[0]==='compare';
107
- const handoff=HANDOFF_FLAGS.map(f=>'--'+f),flags=command==='open'?['--reference','--compare','--animation',...projectFlags,...handoff]:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation',...handoff];
117
+ const handoff=HANDOFF_FLAGS.map(f=>'--'+f),flags=command==='open'?['--reference','--compare','--animation',...projectFlags,...handoff]:compare?['--reference','--animation','--port']:['--port','--checkpoint','--reference','--compare','--animation',...handoff,...(command==='feedback'?projectFlags:[])];
108
118
  for(let i=compare?3:1;i<args.length;){
109
119
  const flag=args[i];if(flag==='--help'||flag==='-h')return true;
110
120
  if((command==='open'&&(flag==='--control'||flag==='--direct'||flag==='--view-only'))||(command==='review'&&flag==='--view-only')){i++;continue;}if(!flags.includes(flag!))return false;i+=2;
@@ -143,7 +153,7 @@ export async function main(args:string[],options:{stateDir?:string}={}){
143
153
  if(args[0]==='--version'||args[0]==='-v'){console.log((JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')) as {version:string}).version);return;}
144
154
  if(args[0]==='control')return controlCommand(args.slice(1),options.stateDir);
145
155
  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.
146
- 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;}
156
+ 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),...projectWords(result.inputs)].map(shellWord).join(' ')}`);return;}
147
157
  if(args[0]==='parts')return partsCommand(args.slice(1));
148
158
  if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
149
159
  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';}
@@ -166,13 +176,18 @@ export async function main(args:string[],options:{stateDir?:string}={}){
166
176
  const stop=(sig:string)=>{server.stop(true);console.log(`review compare: exiting — received ${sig}.`);process.exit(0);};process.once('SIGINT',()=>stop('SIGINT'));process.once('SIGTERM',()=>stop('SIGTERM'));
167
177
  console.log(`Compare ready: http://127.0.0.1:${server.port}/#cap=${capability}\nComparison: ${p.response.title}\nSource SHA-256: ${p.response.sourceHash}\nPress Ctrl+C to stop.`);return;
168
178
  }
169
- 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};
170
- 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}`);}
179
+ 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},projectOptions:string[]=[];
180
+ 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(command==='feedback'&&projectFlags.includes(flag!)){projectOptions.push(flag!,value);continue;}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}`);}
171
181
  const handoffProblem=checkHandoffFlags(handoff);if(handoffProblem)throw new Error(handoffProblem);if(compare&&handoffFlags(handoff))throw new Error('--config: compare takes no producer handoff');
182
+ if(projectOptions.length)handoff.project=parseOpenInputs([input,...projectOptions,...(compare?['--compare',compare]:[])]).project;
172
183
  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;}
173
- 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.
184
+ const base=await loadReferencedReview(input,reference,handoffFlags(handoff));
185
+ const joined=handoff.project?joinProject(base,handoff.project):undefined,p=joined?.review??base;
186
+ const unchanged=()=>joined?.assertCurrent()??assertReviewUnchanged(p);
187
+ if(viewOnly)p.viewOnly=true;// Serving starts on the report's clip when it names one; check and feedback validate only an explicit flag.
174
188
  const fromReport=command==='review'&&animation===undefined&&p.report?.animation!==undefined;
175
189
  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){
190
+ await unchanged();
176
191
  const stateDir=options.stateDir!;
177
192
  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;});
178
193
  const session=parseSession(JSON.parse(bytes.toString('utf8')),p,false);
@@ -180,15 +195,15 @@ export async function main(args:string[],options:{stateDir?:string}={}){
180
195
  const correction=parseCorrection((item?.context as any)?.correction);
181
196
  if(!item||!correction||session.feedbackWarnings.some(warning=>warning.id===item.id))throw new Error('CORRECTION_ITEM_INVALID: expected a valid saved correction');
182
197
  const source={id:p.manifest.id,revision:p.manifest.revision,sourceHash:p.sourceHash,reviewedSource:p.reviewedSource};
183
- await assertReviewUnchanged(p);
184
- const rebuilds=createRebuilds(p,{stateDir,starts:[p.root,process.cwd()],unchanged:()=>assertReviewUnchanged(p),bones:p.feedbackCatalog.bones});
198
+ const rebuilds=createRebuilds(p,{stateDir,starts:[p.root,process.cwd()],unchanged,bones:p.feedbackCatalog.bones});
185
199
  const settled=correction.path==='made'&&correction.selector.kind!=='post'?await rebuilds.correctionEvidence(appliedValue(item)):undefined;
186
200
  const projected=projectSessionCorrection({...correction,session,sessionBytes:bytes,source,itemId:item.id,settled,direction:p.direction});
201
+ await unchanged();
187
202
  if(projected.kind==='unsupported')console.error('CORRECTION_OPERATION_UNSUPPORTED: '+projected.operation);
188
203
  process.stdout.write(format==='json'?bytes:formatCorrectionIssue(projected,item.context)+'\n');
189
204
  return;
190
205
  }
191
- 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;}
206
+ if(command==='feedback'){const saved=await readFeedbackSession(p,options.stateDir);await unchanged();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;}
192
207
  if(checkpoint&&!p.manifest.checkpoints.some(v=>v.id===checkpoint))throw new Error(`Unknown checkpoint ${checkpoint}`);
193
208
  // Foreground serving uses the same `#cap=` fragment handoff as open: the printed link alone can submit.
194
209
  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;
@@ -110,6 +110,11 @@ function unsupportedOperation(schema: string): string {
110
110
 
111
111
  export function projectSessionCorrection(input: SessionInput) {
112
112
  const { session, sessionBytes, selector, source, itemId } = input;
113
+ const joined = input.direction?.joined;
114
+ if (selector.kind === 'post' && joined && selector.version !== joined.postVersion)
115
+ return refuse('CORRECTION_DIRECTION_SOURCE', 'select the joined Create post version');
116
+ if (selector.kind === 'post' && joined && input.path === 'made')
117
+ return refuse('CAMERA_APPLY_UNSUPPORTED', 'joined direction supports described requests only');
113
118
  const on = selectorArgs(selector);
114
119
  if (!hash(source.sourceHash) || !isDeepStrictEqual(sessionSource(session), source)) {
115
120
  return refuse('CORRECTION_SOURCE_STALE', 'saved session differs from verified source');
@@ -129,7 +134,8 @@ export function projectSessionCorrection(input: SessionInput) {
129
134
  const context = item.context as Record<string, unknown> | undefined;
130
135
  const comment = hasStageComment(context?.comment) ? parseStageComment(context?.comment) : null;
131
136
  const createSource = JSON.stringify({
132
- source, post: selector.version, model, direction,
137
+ source, post: selector.version, model: joined?.projectModel ?? model, direction,
138
+ ...(joined ? {binding: joined, rigVersion: input.direction!.rigVersion, inspectedModel: model} : {}),
133
139
  animation: comment ? comment.animation : context?.animation,
134
140
  time: comment ? comment.time : context?.time,
135
141
  sourceTime: context?.sourceTime,
@@ -144,7 +150,8 @@ export function projectSessionCorrection(input: SessionInput) {
144
150
  if (Buffer.byteLength(createSource) > 32 * 1024) {
145
151
  return refuse('CORRECTION_DIRECTION_CONTEXT_SIZE', 'direction correction source exceeds 32 KiB');
146
152
  }
147
- return { ...common, kind: 'described' as const, outcome: null, createSource };
153
+ return { ...common, on: joined ? selectorArgs({...selector, modelFile: joined.projectModel.path}) : on,
154
+ kind: 'described' as const, outcome: null, createSource };
148
155
  }
149
156
 
150
157
  const value = appliedValue(item);
@@ -5,6 +5,13 @@ export const DIRECTION_MAX_BYTES = 256 * 1024;
5
5
  type Binding = { path: string; sha256: string };
6
6
  export interface DirectionInspection {
7
7
  file: Binding;
8
+ joined?: {
9
+ postVersion: number;
10
+ projectHash: string;
11
+ packageSourceHash: string;
12
+ packageRoot: string;
13
+ projectModel: Binding;
14
+ };
8
15
  rigVersion: number;
9
16
  camera: { space: 'rig-world-y-up'; keys: { time: number; easing: string; box: { x: number; y: number; width: number; height: number } }[] };
10
17
  take: { duration: number; loop: boolean };
package/src/front.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { interviewRefusals, interviewRequest } from './interview-routes.ts';
2
- import { interviewStale } from './joined-project.ts';
2
+ import { directionStale, interviewStale } from './joined-project.ts';
3
3
  import { picksLimit } from './interview-picks.ts';
4
- import {stageDraftRefusals} from './stage-parts.ts';
4
+ import {stageDraftRefusals,stageVerdictLimit,stageVerdictRefusals} from './stage-parts.ts';
5
5
  /** Managed loopback front: one stable origin (127.0.0.1:4318 by default) routing `/instances/<key>/…` to the
6
6
  * worker named by that key's private open record. It is a router, not an authority: it never reads packages,
7
7
  * never serves or logs a capability, and forwards a mutation (rewriting Origin) only with the page capability. */
@@ -57,6 +57,8 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
57
57
  if(['/stage-parts.html','/parts.js','/parts.css'].includes(path))return read?get:null;
58
58
  if((mode==='single'?/^\/api\/stage-parts(?:\/(?:image|page)\/\d+)?$/:/^\/api\/compare\/(?:a|b)\/stage-parts(?:\/(?:image|page)\/\d+)?$/).test(path))return read?get:null;
59
59
  if(mode==='single'){
60
+ if(path==='/api/stage-parts/verdict')return method==='POST'?{...get,mutation:true,limit:stageVerdictLimit}:null;
61
+ if(path==='/api/stage-parts/export/json'||path==='/api/stage-parts/export/issue')return read?get:null;
60
62
  if(['/stage-interview.html','/interview.js','/interview.css'].includes(path))return method==='GET'?get:null;
61
63
  if(interviewRequest(path))return path==='/api/interview/picks'?
62
64
  method==='POST'?{...get,mutation:true,limit:picksLimit}:null:method==='GET'?get:null;
@@ -107,10 +109,14 @@ export function stageFrameQuery(mode:'single'|'compare',search:string):boolean {
107
109
  return keys.length===allowed.length&&new Set(keys).size===keys.length&&keys.every(k=>allowed.includes(k))&&params.get('stageEmbed')==='1'&&['en','ko'].includes(params.get('lang')??'')&&(mode==='single'||['a','b'].includes(params.get('side')??''));
108
110
  }
109
111
  /** Preserve only closed, bounded inspection refusals. */
110
- async function inspectionRefusal(mode:'single'|'compare',method:string,path:string,response:Response):Promise<string|null>{
112
+ async function inspectionRefusal(mode:'single'|'compare',method:string,path:string,response:Response,sameFingerprint:boolean):Promise<string|null>{
111
113
  const stageData=mode==='single'?path==='/api/stage-parts':/^\/api\/compare\/(?:a|b)\/stage-parts$/.test(path);
112
114
  const interview=mode==='single'&&interviewRequest(path)&&[400,404,409].includes(response.status);
113
- if(!(interview||stageData&&method==='GET'&&response.status===409)||!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type')??''))return null;
115
+ // Both reads race during the single-package page bootstrap.
116
+ const direction=sameFingerprint&&mode==='single'&&method==='GET'&&response.status===409&&
117
+ (path==='/api/review'||path==='/api/session');
118
+ const verdict=mode==='single'&&['/api/stage-parts/verdict','/api/stage-parts/export/json','/api/stage-parts/export/issue'].includes(path)&&[400,409].includes(response.status);
119
+ if(!(direction||interview||verdict||stageData&&method==='GET'&&response.status===409)||!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type')??''))return null;
114
120
  const limit=512,declared=response.headers.get('content-length');if(declared!==null&&(!/^\d+$/.test(declared)||Number(declared)>limit))return null;
115
121
  const reader=response.body?.getReader();if(!reader)return null;
116
122
  try{
@@ -120,7 +126,8 @@ async function inspectionRefusal(mode:'single'|'compare',method:string,path:stri
120
126
  const data:unknown=JSON.parse(new TextDecoder().decode(body)),named='PARTS_ATLAS_UNAVAILABLE: the inspected package has no usable atlas or its source changed.';
121
127
  if(data===null||typeof data!=='object'||Array.isArray(data)||Object.keys(data).length!==1)return null;
122
128
  const error=(data as {error?:unknown}).error;
123
- return typeof error==='string'&&(interview?[...interviewRefusals]:[named,interviewStale,...Object.values(stageDraftRefusals)] as readonly string[]).some(code=>code===error)?error:null;
129
+ if(direction)return error===directionStale?directionStale:null;
130
+ return typeof error==='string'&&(interview?[...interviewRefusals]:[...(stageData&&response.status===409?[named,...Object.values(stageDraftRefusals),...stageVerdictRefusals]:[]),interviewStale,...(verdict?stageVerdictRefusals:[])] as readonly string[]).some(code=>code===error)?error:null;
124
131
  }catch{return null;}finally{reader.releaseLock();}
125
132
  }
126
133
  export const maximumUpstreamStreams=32;
@@ -178,11 +185,11 @@ export function startFront(options:{control:string;port:number;nonce:string;fing
178
185
  body=await boundedBody(req,route.limit);
179
186
  // A stale interview worker must still prove its identity before it receives picks.
180
187
  // It revalidates the join before saving and returns the specific stale refusal.
181
- if(!await alive(record,path==='/api/interview/picks'))return refuse('FRONT_INSTANCE_EXPIRED: reopen with rig-review open',410);
188
+ if(!await alive(record,(path==='/api/interview/picks'||path==='/api/stage-parts/verdict')))return refuse('FRONT_INSTANCE_EXPIRED: reopen with rig-review open',410);
182
189
  }
183
190
  if(active>=maximumUpstreamStreams)return refuse('FRONT_BUSY: too many concurrent upstream streams',503);
184
191
  const headers=new Headers({[openNonceHeader]:record.nonce});for(const name of ['accept','range','if-range',...(route.mutation?['content-type']:[]),...(route.control?['authorization']:[])]){const value=req.headers.get(name);if(value!==null)headers.set(name,value);}
185
- if(/^\/api\/stage-parts(?:\/(?:image|page)\/\d+)?$/.test(path)){const build=req.headers.get('X-Review-Stage-Build');if(build!==null){if(build!=='inspected'&&!/^[a-f0-9]{64}$/.test(build))return refuse('FRONT_QUERY_REFUSED',400);headers.set('X-Review-Stage-Build',build);}}
192
+ if(/^\/api\/stage-parts(?:\/(?:image|page)\/\d+|\/verdict|\/export\/(?:json|issue))?$/.test(path)){const build=req.headers.get('X-Review-Stage-Build');if(build!==null){if(build!=='inspected'&&!/^[a-f0-9]{64}$/.test(build))return refuse('FRONT_QUERY_REFUSED',400);headers.set('X-Review-Stage-Build',build);}}
186
193
  if(route.mutation){headers.set('origin',record.origin);headers.set(capabilityHeader,record.capability);}
187
194
  active++;let released=false;const abort=new AbortController(),timer=setTimeout(()=>abort.abort(),route.timeoutMs);const release=()=>{if(released)return;released=true;active--;clearTimeout(timer);};
188
195
  req.signal.addEventListener('abort',()=>abort.abort(),{once:true});
@@ -190,7 +197,7 @@ export function startFront(options:{control:string;port:number;nonce:string;fing
190
197
  try{upstream=await fetch(record.origin+path+(landing||stageFrame?url.search:''),{method:req.method,headers,...(body?{body}:{}),redirect:'manual',signal:abort.signal});}
191
198
  catch{release();return abort.signal.aborted&&!req.signal.aborted?refuse('FRONT_UPSTREAM_TIMEOUT',504):refuse('FRONT_INSTANCE_EXPIRED: reopen with rig-review open',410);}
192
199
  if(upstream.headers.get(openKeyHeader)!==key){void upstream.body?.cancel().catch(()=>{});release();return refuse('FRONT_INSTANCE_REPLACED: reopen with rig-review open',410);}
193
- if(upstream.status>=400&&upstream.status!==416){const named=await inspectionRefusal(record.mode,req.method,path,upstream);void upstream.body?.cancel().catch(()=>{});release();if(named)return refuse(named,upstream.status);const code=upstreamFailure[upstream.status];return refuse(code??'FRONT_UPSTREAM_FAILED',code?upstream.status:502);}
200
+ if(upstream.status>=400&&upstream.status!==416){const named=await inspectionRefusal(record.mode,req.method,path,upstream,record.fingerprint===options.fingerprint);void upstream.body?.cancel().catch(()=>{});release();if(named)return refuse(named,upstream.status);const code=upstreamFailure[upstream.status];return refuse(code??'FRONT_UPSTREAM_FAILED',code?upstream.status:502);}
194
201
  const out=new Headers();for(const name of responseHeaders){const value=upstream.headers.get(name);if(value!==null)out.set(name,value);}
195
202
  if(!upstream.body||req.method==='HEAD'){void upstream.body?.cancel().catch(()=>{});release();return new Response(null,{status:upstream.status,headers:out});}
196
203
  if(timer)clearTimeout(timer);const reader=upstream.body.getReader();
@@ -43,7 +43,7 @@ export function interviewRequest(path: string) {
43
43
  }
44
44
 
45
45
  export function interviewRoutes(root: string, output: string, capability: string,
46
- joined?: {opened: ReturnType<typeof readProject>; assertCurrent: () => Promise<void>; available: boolean; sourceHash: string; version: number}) {
46
+ joined?: {opened: ReturnType<typeof readProject>; assertCurrent: () => Promise<void>; available: boolean; sourceHash: string; version?: number; draftId?:string}) {
47
47
  const opened = joined?.opened ?? readProject(root);
48
48
  const outputPath = outputDirectory(opened.root, output, opened.project);
49
49
  const openedOutput = lstatSync(outputPath);
@@ -67,7 +67,7 @@ export function interviewRoutes(root: string, output: string, capability: string
67
67
  if (req.method === 'GET' && url.pathname === '/api/interview') {
68
68
  await current();
69
69
  const dir = destination();
70
- return json({...(joined ? {binding:{projectHash:opened.hash, sourceHash:joined.sourceHash, version:joined.version}} : {}), historical:opened.historical, questions:opened.questions.map(question => ({
70
+ return json({...(joined ? {binding:{projectHash:opened.hash, sourceHash:joined.sourceHash, ...(joined.draftId===undefined?{version:joined.version}:{draftId:joined.draftId})}} : {}), historical:opened.historical, questions:opened.questions.map(question => ({
71
71
  ...question, saved:question.editable ? readPicks(dir, question) : null,
72
72
  images:question.images.map(({name}, index) => ({name, url:'/api/interview/image/' + question.ref.sha256 + '/' + index})),
73
73
  }))});
@@ -1,23 +1,45 @@
1
- import { readdirSync } from 'node:fs';
1
+ import { lstatSync, readdirSync } from 'node:fs';
2
2
  import { join, relative, sep } from 'node:path';
3
- import { boundBytes, checkedPath, digest, literalPath, object, readProject, readRegular } from './interview-project.ts';
3
+ import { boundBytes, checkedPath, digest, jsonObject, literalPath, object, readProject, readRegular } from './interview-project.ts';
4
+ import { DIRECTION_MAX_BYTES, readDirectionInspection } from './direction-inspection.ts';
4
5
  import { outputDirectory } from './interview-picks.ts';
5
6
  import { packagePath, type ReviewPackage } from './manifest.ts';
6
- import { assertReviewUnchanged } from './reference.ts';
7
+ import { assertReviewUnchanged, withReviewAssertion } from './reference.ts';
7
8
 
8
- export interface ProjectDesignation {root: string; version: number; picksDir: string}
9
+ export type ProjectDesignation={root:string;picksDir:string}&(
10
+ {version:number;postVersion?:number;draftId?:never;partsVerdictDir?:never} |
11
+ {draftId:string;partsVerdictDir?:string;version?:never;postVersion?:never}
12
+ );
13
+ interface DraftSource {
14
+ parts:string;
15
+ rig:string;
16
+ meshReport:string;
17
+ model:string;
18
+ files:ReadonlyMap<string,string>;
19
+ }
20
+ interface JoinedSource {
21
+ review:ReviewPackage;
22
+ opened:ReturnType<typeof readProject>;
23
+ designation:ProjectDesignation;
24
+ assertCurrent:()=>Promise<void>;
25
+ available:boolean;
26
+ draft?:DraftSource;
27
+ verdictDirectory?:()=>string;
28
+ }
9
29
  export const interviewUnavailable = 'INTERVIEW_UNAVAILABLE';
10
30
  export const interviewMismatch = 'INTERVIEW_SOURCE_MISMATCH';
11
31
  export const interviewStale = 'INTERVIEW_OPTIONS_STALE';
32
+ export const directionStale = 'DIRECTION_SOURCE_STALE';
12
33
 
13
- export function joinProject(p: ReviewPackage, designation: ProjectDesignation) {
34
+ export function joinProject(p: ReviewPackage, designation: ProjectDesignation):JoinedSource {
35
+ if(designation.draftId!==undefined)return joinDraft(p,designation);
14
36
  const opened = readProject(designation.root);
15
37
  const {root, hash, project} = opened;
16
38
  const {version} = designation;
17
39
  const fail = (): never => {throw new Error(interviewMismatch + ': expected the designated Create version’s recorded review package');};
18
40
  if (!Number.isSafeInteger(version) || version < 1) return fail();
19
- const matches = (Array.isArray(project.versions) ? project.versions : []).map(object)
20
- .filter(entry => entry.n === version && entry.kind === 'rig');
41
+ const versions = (Array.isArray(project.versions) ? project.versions : []).map(object);
42
+ const matches = versions.filter(entry => entry.n === version && entry.kind === 'rig');
21
43
  const record = object(matches[0]?.review_package);
22
44
  const path = 'derived/review/v' + version;
23
45
  const files = new Map<string, string>();
@@ -37,9 +59,9 @@ export function joinProject(p: ReviewPackage, designation: ProjectDesignation) {
37
59
  const expected = files.get(relative(pkg, absolute).split(sep).join('/'));
38
60
  return expected !== undefined && (sha256 === undefined || sha256 === expected);
39
61
  };
40
- if (![...p.files].every(file => covered(join(p.root, file))) ||
62
+ if (!p.reviewedSource.rig || ![...p.files].every(file => covered(join(p.root, file))) ||
41
63
  !p.handoff.record.files.every(file => covered(join(p.root, file.path), file.sha256)) ||
42
- !covered(join(p.root, p.manifest.model), p.reviewedSource.rig?.sha256) ||
64
+ !covered(join(p.root, p.manifest.model), p.reviewedSource.rig.sha256) ||
43
65
  !files.has('out/parts.json') || ![...files.keys()].some(file => file.startsWith('out/parts/'))) return fail();
44
66
  } catch {return fail();}
45
67
 
@@ -62,14 +84,150 @@ export function joinProject(p: ReviewPackage, designation: ProjectDesignation) {
62
84
  try {assertInventory();} catch {return fail();}
63
85
  outputDirectory(root, designation.picksDir, project);
64
86
 
87
+ // The existing join has already matched the exact recorded package inventory.
88
+ // Derive the project-relative model from the inspected asset, never from a SHA search.
89
+ let direction: ReviewPackage['direction'];
90
+ const postVersion = designation.postVersion;
91
+ const readDirection = (path: string) => readRegular(checkedPath(root, path), DIRECTION_MAX_BYTES);
92
+ if (postVersion !== undefined) {
93
+ const posts = versions.filter(entry => entry.n === postVersion);
94
+ const post = posts[0];
95
+ if (!Number.isSafeInteger(postVersion) || postVersion < 1 || posts.length !== 1 || post?.kind !== 'post')
96
+ throw new Error('DIRECTION_VERSION: select a recorded Create post version');
97
+ if (post.rig_version !== version)
98
+ throw new Error('DIRECTION_RIG_MISMATCH: selected post names a different rig version');
99
+ const provenance = object(post.provenance);
100
+ if (provenance.direction === undefined)
101
+ throw new Error('DIRECTION_DOCUMENT_REQUIRED: selected post has no authored direction');
102
+ const {path: directionPath, sha256} = object(provenance.direction);
103
+ const bindsDirection = (value: unknown) => {
104
+ const binding = object(value);
105
+ return binding.path === directionPath && binding.sha256 === sha256;
106
+ };
107
+ if (directionPath !== `evidence/direction/v${postVersion}.json` ||
108
+ typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(sha256) ||
109
+ !bindsDirection(provenance.config) || !Array.isArray(post.outputs) || !post.outputs.some(bindsDirection))
110
+ throw new Error('DIRECTION_VERSION: selected post must bind its exact direction document');
111
+ const file = {path: directionPath, sha256};
112
+ let bytes: Buffer;
113
+ try {
114
+ bytes = readDirection(file.path);
115
+ if (digest(bytes) !== file.sha256) throw new Error('SHA mismatch');
116
+ } catch {
117
+ throw new Error('DIRECTION_SOURCE_MISMATCH: selected direction is missing, unsafe or differs from its recorded SHA-256');
118
+ }
119
+ const model = p.reviewedSource.rig!;
120
+ const projectModel = {...model, path: relative(root, join(p.root, model.path)).split(sep).join('/')};
121
+ let document: unknown;
122
+ try { document = jsonObject(bytes); }
123
+ catch { throw new Error('DIRECTION_SCHEMA: expected a UTF-8 JSON direction object'); }
124
+ const inspected = readDirectionInspection(document, file, projectModel);
125
+ if (inspected.rigVersion !== version)
126
+ throw new Error('DIRECTION_RIG_MISMATCH: authored direction names a different rig version');
127
+ direction = {...inspected, joined: {postVersion, projectHash:hash, packageSourceHash:p.sourceHash, packageRoot:path, projectModel}};
128
+ }
65
129
  const assertCurrent = async () => {
66
130
  try {
67
131
  await assertReviewUnchanged(p);
68
132
  assertInventory();
69
133
  if (digest(readRegular(checkedPath(root, 'project.json'), 8 * 1024 * 1024)) !== hash) throw new Error('Project changed');
70
134
  } catch {throw new Error(interviewStale + ': project or review package changed; reopen the project');}
135
+ if (direction) {
136
+ try {
137
+ if (digest(readDirection(direction.file.path)) !== direction.file.sha256) throw new Error('SHA mismatch');
138
+ } catch {
139
+ throw new Error(directionStale);
140
+ }
141
+ }
71
142
  };
72
- return {opened, designation:{...designation, root}, assertCurrent,
143
+ const review = direction ? withReviewAssertion({
144
+ ...p, direction,
145
+ sourceHash:digest(JSON.stringify({schema:'rig-review-joined-direction/1', direction:direction.file, rigVersion:version, ...direction.joined})),
146
+ }, assertCurrent) : p;
147
+ return {review, opened, designation:{...designation, root}, assertCurrent,
73
148
  available:opened.questions.length > 0 || opened.historical.length > 0};
74
149
  }
150
+ /** Match the draft writer's explicit parts and rig inventories, independently of a production version. */
151
+ function joinDraft(p:ReviewPackage,designation:Extract<ProjectDesignation,{draftId:string}>):JoinedSource {
152
+ const opened=readProject(designation.root);
153
+ const {root,hash,project}=opened;
154
+ const {draftId}=designation;
155
+ const path='derived/drafts/'+draftId;
156
+ const fail=():never=>{throw new Error('INTERVIEW_SOURCE_MISMATCH: expected the selected Create pre-rig draft and exact recorded files');};
157
+ if(!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(draftId)||!Array.isArray(project.versions)||project.versions.length||
158
+ !Array.isArray(project.drafts)||!Array.isArray(project.signoffs)||!p.manifest.model||!p.reviewedSource.rig||
159
+ p.direction||p.handoffInputs)return fail();
160
+ const matches=project.drafts.map(object).filter(draft=>draft.id===draftId);
161
+ const record=matches[0],parts=object(record?.parts);
162
+ if(matches.length!==1||record?.kind!=='draft-rig'||!literalPath(parts.path)||!parts.path.startsWith(path+'/')||
163
+ !Array.isArray(parts.files)||!Array.isArray(record.files)||
164
+ (record.config_inputs!==undefined&&!Array.isArray(record.config_inputs)))return fail();
165
+ const files=new Map<string,string>();
166
+ const inventory=(refs:unknown[],prefix:string)=>{
167
+ const paths:string[]=[];
168
+ for(const ref of refs){
169
+ const {path,sha256}=object(ref);
170
+ if(!literalPath(path)||!path.startsWith(prefix+'/')||typeof sha256!=='string'||!/^[a-f0-9]{64}$/.test(sha256))return fail();
171
+ packagePath(path);
172
+ if(paths.includes(path)||(files.has(path)&&files.get(path)!==sha256))return fail();
173
+ paths.push(path);
174
+ files.set(path,sha256);
175
+ }
176
+ return paths;
177
+ };
178
+ let draft:DraftSource;
179
+ try{
180
+ inventory([record.config,...(record.config_inputs??[])],path);
181
+ const input=inventory(parts.files,parts.path);
182
+ if(!input.includes(parts.path+'/parts.json')||!input.some(file=>file.startsWith(parts.path+'/parts/')))return fail();
183
+ const output=inventory(record.files,path);
184
+ const rigs=output.filter(file=>file.endsWith('/rig.json'));
185
+ if(rigs.length!==1)return fail();
186
+ const rig=rigs[0]!,dir=rig.slice(0,-'/rig.json'.length);
187
+ const meshReport=dir+'/mesh_report.json';
188
+ const model=relative(root,join(p.root,p.manifest.model)).split(sep).join('/');
189
+ const checkRoot=dir.endsWith('/rig')?dir.slice(0,-'/rig'.length):dir;
190
+ if(!output.includes(meshReport)||!output.includes(dir+'/motion.json')||
191
+ !model.startsWith(checkRoot+'/check/')||!output.includes(model)||files.get(model)!==p.reviewedSource.rig.sha256||
192
+ ![...p.files].every(file=>output.includes(relative(root,join(p.root,file)).split(sep).join('/'))))return fail();
193
+ draft={parts:checkedPath(root,parts.path,true),rig:checkedPath(root,rig),meshReport:checkedPath(root,meshReport),
194
+ model:checkedPath(root,model),files:new Map([...files].map(([file,sha])=>[checkedPath(root,file),sha]))};
195
+ for(const [path,sha256] of files)boundBytes(root,{path,sha256});
196
+ }catch{return fail();}
197
+ outputDirectory(root,designation.picksDir,project);
198
+ const assertCurrent=async()=>{
199
+ try{
200
+ await assertReviewUnchanged(p);
201
+ for(const [path,sha256] of files)boundBytes(root,{path,sha256});
202
+ if(digest(readRegular(checkedPath(root,'project.json'),8*1024*1024))!==hash)throw new Error('Project changed');
203
+ }catch{throw new Error(interviewStale+': project or draft changed; reopen the project');}
204
+ };
205
+ const dir=designation.partsVerdictDir;
206
+ // An explicit output selects the write surface. A recorded parts approval closes it.
207
+ const pending=['parts','parts-review'].includes(String(project.stage))&&
208
+ !project.signoffs.map(object).some(signoff=>signoff.stage==='parts-review');
209
+ let verdictDirectory:JoinedSource['verdictDirectory'];
210
+ if(dir!==undefined){
211
+ const locate=()=>{
212
+ const portable=(value:string)=>value.normalize('NFC').toLowerCase();
213
+ const overlaps=(a:string,b:string)=>a===b||a.startsWith(b+'/')||b.startsWith(a+'/');
214
+ if(overlaps(portable(dir),portable(path))||overlaps(portable(dir),portable(designation.picksDir)))
215
+ throw new Error('PARTS_VERDICT_OUTPUT');
216
+ try{return outputDirectory(root,dir,project);}
217
+ catch{throw new Error('PARTS_VERDICT_OUTPUT');}
218
+ };
219
+ const original=lstatSync(locate());
220
+ if(pending)verdictDirectory=()=>{
221
+ const output=locate(),stat=lstatSync(output);
222
+ if(stat.dev!==original.dev||stat.ino!==original.ino)throw new Error('PARTS_VERDICT_OUTPUT');
223
+ return output;
224
+ };
225
+ }
226
+ const review=withReviewAssertion({...p,manifest:{...p.manifest,model:undefined},handoff:null,report:null,
227
+ feedbackCatalog:{rig:p.feedbackCatalog.rig,bones:null,slots:null,animations:null,clock:null,clockAnimation:null},
228
+ sourceHash:digest(JSON.stringify({schema:'rig-review-joined-draft/1',draftId,projectHash:hash,packageSourceHash:p.sourceHash})),
229
+ },assertCurrent);
230
+ return {review,opened,designation:{...designation,root},assertCurrent,draft,verdictDirectory,
231
+ available:opened.questions.length>0||opened.historical.length>0};
232
+ }
75
233
  export type JoinedProject = ReturnType<typeof joinProject>;
package/src/open.ts CHANGED
@@ -44,7 +44,7 @@ const sleep=(ms:number)=>new Promise(resolveSleep=>setTimeout(resolveSleep,ms));
44
44
  export const defaultStateDir=()=>process.env.RIG_REVIEW_STATE_DIR??join(homedir(),'.local','state','rig-c-review');
45
45
  export async function loadOpenPackage(inputs:OpenInputs):Promise<OpenPackage>{
46
46
  // Handoff flags become canonical absolute paths here, so the worker and every reload read exactly these files.
47
- if(!inputs.compare){const p=await loadReferencedReview(inputs.input,inputs.reference,handoffFlags(inputs)),selection=selectAnimation([{label:'single',catalog:p.feedbackCatalog,report:p.report}],inputs.animation,true);const joined=inputs.project?joinProject(p,inputs.project):undefined;if(inputs.viewOnly)p.viewOnly=true;return {mode:'single',p,selection,contentHash:p.sourceHash,...(joined?{joined}:{}),inputs:{input:p.manifestPath,...(joined?{project:joined.designation}:{}),...(selectedReference(p)?{reference:selectedReference(p)!.path}:{}),...(selection?{animation:selection.name}:{}),...(inputs.control?{control:true}:{}),...(p.handoffInputs??{})}};}
47
+ if(!inputs.compare){const base=await loadReferencedReview(inputs.input,inputs.reference,handoffFlags(inputs));const joined=inputs.project?joinProject(base,inputs.project):undefined;const p=joined?.review??base,selection=selectAnimation([{label:'single',catalog:p.feedbackCatalog,report:p.report}],inputs.animation,true);if(inputs.viewOnly)p.viewOnly=true;return {mode:'single',p,selection,contentHash:p.sourceHash,...(joined?{joined}:{}),inputs:{input:p.manifestPath,...(joined?{project:joined.designation}:{}),...(selectedReference(p)?{reference:selectedReference(p)!.path}:{}),...(selection?{animation:selection.name}:{}),...(inputs.control?{control:true}:{}),...(p.handoffInputs??{})}};}
48
48
  if(inputs.project)throw new Error('INTERVIEW_SOURCE_MISMATCH: compare takes no joined project');
49
49
  if(handoffFlags(inputs))throw new HandoffError('HANDOFF_FLAGS_INVALID','--config','compare takes no producer handoff; open one package with --config');
50
50
  if(!inputs.reference)throw new Error('open compare: explicit --reference required');
@@ -110,6 +110,8 @@ async function openRefusal(error:unknown,inputs:OpenInputs):Promise<unknown>{
110
110
  }
111
111
  async function verifyOpenLoad(p:OpenPackage,viewOnly:boolean,cwd=process.cwd()):Promise<void>{
112
112
  if(p.mode==='single'){
113
+ // A recorded pre-rig draft has a bound model for Stage 1 mesh mapping only.
114
+ if(p.joined?.draft)return;
113
115
  try{await verifyCompiledModel(p.p.root,p.p.manifest.model,p.selection?.name,p.p.manifest.sets);}
114
116
  catch(error){throw new Error(`OPEN_MODEL_UNAVAILABLE: ${error instanceof Error?error.message:String(error)}`,{cause:error});}
115
117
  const handoffReason=await verifyHandoffReadiness(p.p,[p.p.root,cwd],viewOnly);