@rig-c/review 0.0.0-stage → 0.2.1

package/src/feedback-export.ts

@@ -0,0 +1,197 @@
+import type { Json, ReviewedSource } from './manifest.ts';
+import type { Feedback, FeedbackWarning, ReviewSession } from './session.ts';
+import type { CompareBinding } from './compare.ts';
+import type { CompareSession } from './compare-session.ts';
+import type { FeedbackHistory, HistoryRetrieval } from './session-history.ts';
+import type { ReferenceBinding } from './reference.ts';
+type Category = Feedback['category'];
+type Side = 'single' | 'a' | 'b';
+type ParsedFeedbackSession = FeedbackHistory<ReviewSession | CompareSession>;
+interface Counts { defect: number; quality: number; total: number }
+interface BuildCount {
+  side: Side;
+  sourceHash: string;
+  reviewedSource: ReviewedSource;
+  counts: Counts;
+}
+interface ExportItem {
+  id: string;
+  side: Side;
+  frameStart: number;
+  frameEnd: number;
+  target: Feedback['target'];
+  category: Category;
+  summary: string;
+  context?: Json;
+  warnings: FeedbackWarning[];
+  selectedSource: { sourceHash: string; reviewedSource: ReviewedSource; referenceBinding?: ReferenceBinding };
+}
+interface TargetGroup {
+  target: Feedback['target'];
+  items: ExportItem[];
+}
+interface CategoryGroup {
+  category: Category;
+  count: number;
+  targets: TargetGroup[];
+}
+export interface FeedbackIssueExport {
+  schema: 'rig-review-issue-export/1';
+  session: {
+    schema: ReviewSession['schema'] | CompareSession['schema'];
+    id: string;
+    revision: string;
+    sourceHash: string;
+    status: ReviewSession['status'];
+    updatedAt: string | null;
+  };
+  counts: Counts;
+  builds: BuildCount[];
+  categories: CategoryGroup[];
+  pairedBinding: CompareBinding | null;
+  referenceBinding: ReferenceBinding | null;
+  feedbackWarnings: FeedbackWarning[];
+  retrieval?: HistoryRetrieval;
+  historyWarnings: { file: string; error: string }[];
+}
+const categories: readonly Category[] = ['defect', 'quality'];
+const sideOrder: Record<Side, number> = { single: 0, a: 1, b: 2 };
+const compareText = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0;
+const emptyCounts = (): Counts => ({ defect: 0, quality: 0, total: 0 });
+function cloneSource(source: ReviewedSource): ReviewedSource {
+  return { ...source, rig: source.rig ? { ...source.rig } : null, motion: source.motion ? { ...source.motion } : null };
+}
+function cloneJson(value: Json): Json {
+  if (Array.isArray(value)) return value.map(cloneJson);
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cloneJson(child)]));
+  return value;
+}
+function cloneReference(binding: ReferenceBinding): ReferenceBinding {
+  return { packageSourceHash: binding.packageSourceHash, reference: { ...binding.reference } };
+}
+function cloneBinding(binding: CompareBinding): CompareBinding {
+  return {
+    a: { sourceHash: binding.a.sourceHash, reviewedSource: cloneSource(binding.a.reviewedSource) },
+    b: { sourceHash: binding.b.sourceHash, reviewedSource: cloneSource(binding.b.reviewedSource) },
+    reference: { ...binding.reference }, animation: binding.animation,
+  };
+}
+
+/** Counts records once; never validates/migrates a submission or expands frames. */
+export function groupFeedbackIssues(input: ParsedFeedbackSession): FeedbackIssueExport {
+  const referenceBinding = input.schema === 'rig-review-session/1' && input.referenceBinding ? cloneReference(input.referenceBinding) : null;
+  const pairedBinding = input.schema === 'rig-review-compare-session/1' ? cloneBinding(input.binding) : null;
+  const builds: BuildCount[] = input.schema === 'rig-review-compare-session/1'
+    ? (['a', 'b'] as const).map(side => ({ side, sourceHash: input.binding[side].sourceHash, reviewedSource: cloneSource(input.binding[side].reviewedSource), counts: emptyCounts() }))
+    : [{ side: 'single', sourceHash: input.sourceHash, reviewedSource: cloneSource(input.reviewedSource), counts: emptyCounts() }];
+  const bySide = new Map(builds.map(build => [build.side, build]));
+  const warningMap = new Map<string, FeedbackWarning[]>();
+  for (const warning of input.feedbackWarnings) {
+    const list = warningMap.get(warning.id) ?? [];
+    list.push({ ...warning }); warningMap.set(warning.id, list);
+  }
+  const grouped = new Map<Category, Map<string, TargetGroup>>(categories.map(category => [category, new Map()]));
+  const counts = emptyCounts();
+  const seen = new Set<string>();
+  for (const feedback of input.feedback) {
+    // Parsers already enforce these invariants. Named failures prevent silent
+    // omission if a future CLI accidentally bypasses the parsed-input boundary.
+    if (seen.has(feedback.id)) throw new Error(`feedback export.id: duplicate ${JSON.stringify(feedback.id)}`);
+    seen.add(feedback.id);
+    const side: Side = input.schema === 'rig-review-compare-session/1'
+      ? (feedback as Feedback & { side: 'a' | 'b' }).side : 'single';
+    const build = bySide.get(side);
+    if (!build) throw new Error(`feedback export.side: unavailable ${JSON.stringify(side)}`);
+    const targetGroups = grouped.get(feedback.category);
+    if (!targetGroups) throw new Error(`feedback export.category: unavailable ${JSON.stringify(feedback.category)}`);
+    const targetKey = JSON.stringify([feedback.target.kind, feedback.target.name]);
+    let target = targetGroups.get(targetKey);
+    if (!target) { target = { target: { ...feedback.target }, items: [] }; targetGroups.set(targetKey, target); }
+    target.items.push({
+      id: feedback.id, side, frameStart: feedback.frameStart, frameEnd: feedback.frameEnd,
+      target: { ...feedback.target }, category: feedback.category, summary: feedback.summary,
+      ...(feedback.context === undefined ? {} : { context: cloneJson(feedback.context) }),
+      warnings: [...(warningMap.get(feedback.id) ?? [])].sort((a, b) => compareText(a.error, b.error)),
+      selectedSource: { sourceHash: build.sourceHash, reviewedSource: cloneSource(build.reviewedSource), ...(referenceBinding ? { referenceBinding: cloneReference(referenceBinding) } : {}) },
+    });
+    counts[feedback.category]++; counts.total++;
+    build.counts[feedback.category]++; build.counts.total++;
+  }
+  const categoryGroups: CategoryGroup[] = categories.map(category => {
+    const targets = [...grouped.get(category)!.values()].sort((a, b) => compareText(a.target.kind, b.target.kind) || compareText(a.target.name, b.target.name));
+    for (const target of targets) target.items.sort((a, b) => sideOrder[a.side] - sideOrder[b.side] || compareText(a.id, b.id));
+    return { category, count: counts[category], targets };
+  });
+  return {
+    schema: 'rig-review-issue-export/1',
+    session: { schema: input.schema, id: input.id, revision: input.revision, sourceHash: input.sourceHash, status: input.status, updatedAt: input.updatedAt },
+    counts, builds, categories: categoryGroups, pairedBinding, referenceBinding,
+    feedbackWarnings: input.feedbackWarnings.map(warning => ({ ...warning })).sort((a, b) => compareText(a.id, b.id) || compareText(a.error, b.error)),
+    ...(input.retrieval ? { retrieval: { ...input.retrieval, currentTools: 'a' in input.retrieval.currentTools ? { a: { ...input.retrieval.currentTools.a }, b: { ...input.retrieval.currentTools.b } } : { ...input.retrieval.currentTools } } } : {}),
+    historyWarnings: (input.historyWarnings ?? []).map(warning => ({ ...warning })).sort((a, b) => compareText(a.file, b.file) || compareText(a.error, b.error)),
+  };
+}
+
+/** Entity-escape text in Markdown syntax positions; no raw HTML/line injection. */
+export function feedbackMarkdownText(value: string): string {
+  return value.replace(/[&<>\\`*_{}\[\]()#+.!|~\-\r\n\u0000-\u001f\u007f]/g, char => `&#${char.charCodeAt(0)};`);
+}
+function stableJson(value: unknown): string {
+  const order = (item: unknown): unknown => {
+    if (Array.isArray(item)) return item.map(order);
+    if (item !== null && typeof item === 'object') return Object.fromEntries(Object.entries(item).sort(([a], [b]) => compareText(a, b)).map(([key, child]) => [key, order(child)]));
+    return item;
+  };
+  const serialized = JSON.stringify(order(value), null, 2);
+  if (serialized === undefined) throw new Error('feedback export: expected serializable parsed evidence');
+  return serialized;
+}
+/** A data-owned backtick run can never close the generated fenced JSON block. */
+function jsonBlock(value: unknown): string {
+  const json = stableJson(value);
+  let longest = 0;
+  for (const run of json.matchAll(/`+/g)) longest = Math.max(longest, run[0].length);
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}json\n${json}\n${fence}`;
+}
+
+/** Local issue-ready text only. No issue creation, clock inference or source IO. */
+export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
+  const model = groupFeedbackIssues(input), md = feedbackMarkdownText;
+  const lines = [
+    '# Feedback issue export', '',
+    `Session: ${md(model.session.id)} · revision ${md(model.session.revision)}`,
+    `Recorded status: ${md(model.session.status)} · saved: ${model.session.updatedAt === null ? 'not submitted' : md(model.session.updatedAt)}`,
+    `Source SHA-256: ${md(model.session.sourceHash)}`, '',
+    `Items: ${model.counts.total} · defect: ${model.counts.defect} · quality: ${model.counts.quality}`, '',
+    '| Build | Revision | Defect | Quality | Total | Source SHA-256 |',
+    '| --- | --- | ---: | ---: | ---: | --- |',
+  ];
+  for (const build of model.builds) lines.push(`| ${md(build.side)} | ${md(build.reviewedSource.packageRevision)} | ${build.counts.defect} | ${build.counts.quality} | ${build.counts.total} | ${md(build.sourceHash)} |`);
+  lines.push('', '## Recorded provenance', '', jsonBlock({ builds: model.builds.map(({ counts: _counts, ...build }) => build), pairedBinding: model.pairedBinding, referenceBinding: model.referenceBinding }));
+  if (model.retrieval) lines.push('', '## Historical retrieval', '', 'This is a prior-tools record; its recorded approval is not a current-tools approval.', '', jsonBlock(model.retrieval));
+  if (model.historyWarnings.length) lines.push('', '## History read warnings', '', jsonBlock(model.historyWarnings));
+  // Keep the complete warning list, including unmatched ids, without duplicating
+  // issue items or quietly hiding evidence supplied by the parsed reader.
+  if (model.feedbackWarnings.length) lines.push('', '## Feedback validation warnings', '', jsonBlock(model.feedbackWarnings));
+  for (const category of model.categories) {
+    lines.push('', `## ${category.category} (${category.count})`);
+    if (!category.targets.length) lines.push('', 'No feedback items.');
+    for (const group of category.targets) {
+      lines.push('', `### ${md(group.target.kind)}: ${md(group.target.name)}`);
+      for (const item of group.items) {
+        lines.push('', `#### Feedback ${md(item.id)}`, '',
+          `- Category: ${item.category}`,
+          `- Target: ${md(item.target.kind)}: ${md(item.target.name)}`,
+          `- Inclusive frames: ${item.frameStart}–${item.frameEnd}`,
+          `- Side: ${item.side}`,
+          `- Summary: ${md(item.summary)}`, '',
+          'Selected build identity:', '', jsonBlock(item.selectedSource));
+        if (model.pairedBinding) lines.push('', 'Paired comparison binding:', '', jsonBlock(model.pairedBinding));
+        if (item.warnings.length) lines.push('', 'Validation warnings (record retained):', '', jsonBlock(item.warnings));
+        if (item.context !== undefined) lines.push('', 'Original inspection context (separate from chosen inclusive frames):', '', jsonBlock(item.context));
+      }
+    }
+  }
+  return lines.join('\n') + '\n';
+}

package/src/feedback-validation.ts

@@ -0,0 +1,38 @@
+import { lastFrame, timeAtFrame, type FrameClock } from './frame-clock.ts';
+
+/** Null names mean unavailable metadata; an empty list means known empty. */
+export interface FeedbackCatalog {
+  rig:string;bones:string[]|null;slots:string[]|null;
+  animations:{name:string;duration:number}[]|null;
+  clock:FrameClock|null;clockAnimation:string|null;
+}
+export type FeedbackTargetKind='bone'|'slot'|'rig';
+export interface FeedbackSelection {frameStart:number;frameEnd:number;target:{kind:FeedbackTargetKind;name:string};animation:string|null}
+export function feedbackTargetNames(catalog:FeedbackCatalog,kind:FeedbackTargetKind):string[]|null {
+  return kind==='rig'?[catalog.rig]:kind==='bone'?catalog.bones:catalog.slots;
+}
+/** Clip end restricts declared samples; it never creates a rate or a frame. */
+export function feedbackLastFrame(catalog:FeedbackCatalog,animation:string|null):number|null {
+  const last=lastFrame(catalog.clock);if(last===null)return null;
+  if(catalog.animations===null)return catalog.clockAnimation===null||animation===null||animation===catalog.clockAnimation?last:null;
+  if(!animation||catalog.clockAnimation!==animation)return null;
+  const clip=catalog.animations.find(value=>value.name===animation);if(!clip)return null;
+  let low=0,high=last;
+  while(low<=high){const middle=low+Math.floor((high-low)/2),time=timeAtFrame(catalog.clock,middle);if(time!==null&&time<=clip.duration)low=middle+1;else high=middle-1;}
+  // -1 is a known empty clip/sample intersection, not an unknown clock.
+  return high;
+}
+export function validateFeedbackSelection(catalog:FeedbackCatalog,value:FeedbackSelection):void {
+  if(!value.target||!['bone','slot','rig'].includes(value.target.kind))throw new Error('feedback.target.kind: expected bone | slot | rig');
+  if(typeof value.target.name!=='string'||!value.target.name.trim())throw new Error('feedback.target.name: expected nonempty model or package name');
+  if(value.animation!==null&&typeof value.animation!=='string')throw new Error('feedback.context.animation: expected animation name or null');
+  if(!Number.isSafeInteger(value.frameStart)||!Number.isSafeInteger(value.frameEnd)||value.frameStart<0||value.frameEnd<value.frameStart)throw new Error('feedback frames: expected inclusive integer 0 <= frameStart <= frameEnd');
+  const names=feedbackTargetNames(catalog,value.target.kind);
+  if(names===null)throw new Error(`feedback.target.name: ${value.target.kind} validation unavailable without model ${value.target.kind} names`);
+  if(!names.includes(value.target.name))throw new Error(`feedback.target.name: ${value.target.kind} ${JSON.stringify(value.target.name)} not in ${value.target.kind==='rig'?'package':'model'}`);
+  if(value.animation!==null&&catalog.animations!==null&&!catalog.animations.some(clip=>clip.name===value.animation))throw new Error(`feedback.context.animation: ${JSON.stringify(value.animation)} not in model`);
+  if(catalog.animations===null&&lastFrame(catalog.clock)!==null&&catalog.clockAnimation!==null&&value.animation!==null&&value.animation!==catalog.clockAnimation)throw new Error('feedback.context.animation: does not match source report frame clock');
+  if(catalog.animations!==null&&lastFrame(catalog.clock)!==null&&catalog.clockAnimation!==null&&value.animation===null)throw new Error('feedback.context.animation: required to bind declared report frame clock');
+  const last=feedbackLastFrame(catalog,value.animation);
+  if(last!==null&&value.frameEnd>last)throw new Error(`feedback.frameEnd: ${value.frameEnd} beyond clip last frame ${last}`);
+}

package/src/frame-clock.ts

@@ -0,0 +1,36 @@
+/** Explicit producer clock only. No duration, event spacing or video-rate fallback. */
+export type FrameClock =
+  | {kind:'uniform';fps:number;frame0:number;frameCount?:number}
+  | {kind:'samples';frameTimes:number[]};
+
+/** Source-only time remains usable; a player must identify the matching output. */
+export function clockForAnimation(clock:FrameClock|null|undefined,animation:string|undefined,activeAnimation:string,hasPlayer=true):FrameClock|null {
+  if(!clock)return null;
+  return !hasPlayer||(animation&&animation===activeAnimation)?clock:null;
+}
+
+export function lastFrame(clock:FrameClock|null|undefined):number|null {
+  if(!clock)return null;
+  const count=clock.kind==='samples'?clock.frameTimes.length:clock.frameCount;
+  return count!==undefined&&Number.isSafeInteger(count)&&count>0?count-1:null;
+}
+
+/** Return exactly the declared sample time; invalid/noninteger frames stay unknown. */
+export function timeAtFrame(clock:FrameClock|null|undefined,frame:number):number|null {
+  const last=lastFrame(clock);
+  if(!clock||last===null||!Number.isSafeInteger(frame)||frame<0||frame>last)return null;
+  const time=clock.kind==='samples'?clock.frameTimes[frame]!:clock.frame0+frame/clock.fps;
+  return Number.isFinite(time)?time:null;
+}
+
+/** The latest sample at or before time, only inside the closed declared domain. */
+export function frameAtTime(clock:FrameClock|null|undefined,time:number):number|null {
+  const last=lastFrame(clock);if(last===null||!Number.isFinite(time))return null;
+  const firstTime=timeAtFrame(clock,0),lastTime=timeAtFrame(clock,last);
+  if(firstTime===null||lastTime===null||time<firstTime||time>lastTime)return null;
+  // Search the declared times directly: avoids both interpolation and floating
+  // multiplication rounding a mathematically exact uniform sample down a frame.
+  let low=0,high=last;
+  while(low<=high){const middle=low+Math.floor((high-low)/2);const sample=timeAtFrame(clock,middle);if(sample===null)return null;if(sample<=time)low=middle+1;else high=middle-1;}
+  return high>=0?high:null;
+}

package/src/front-worker.ts

@@ -0,0 +1,2 @@
+import {runFront} from './front.ts';
+if(import.meta.main)runFront(Bun.argv[2]??'').catch(error=>{console.error(error instanceof Error?error.message:String(error));process.exit(1);});

package/src/front.ts

@@ -0,0 +1,127 @@
+/** Managed loopback front: one stable origin (127.0.0.1:4318 by default) routing `/instances/<key>/…` to the
+ * worker named by that key's private open record. It is a router, not an authority: it never reads packages,
+ * never serves or logs a capability, and forwards a mutation (rewriting Origin) only with the page capability. */
+import {randomUUID} from 'node:crypto';
+import {spawn} from 'node:child_process';
+import {lstat,readFile,readdir,realpath,rename,unlink,writeFile,open as openFile} from 'node:fs/promises';
+import {dirname,join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {acquireClaim,alive,openFingerprint,readRecord,releaseClaim,running,smallJson,type RecordFile} from './open.ts';
+import {capabilityHeader,openKeyHeader,openNonceHeader,sameSecret} from './open-protocol.ts';
+export const defaultFrontPort=4318; // Foreground `review <dir>` keeps 4317.
+interface FrontRecord {schema:'rig-review-front/1';origin:string;port:number;nonce:string;fingerprint:string;pid:number}
+interface FrontRequest {schema:'rig-review-front-request/1';control:string;request:string;record:string;port:number;nonce:string;fingerprint:string;idleMs:number}
+const appRoot=fileURLToPath(new URL('..',import.meta.url));
+const sleep=(ms:number)=>new Promise(resolveSleep=>setTimeout(resolveSleep,ms));
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/,hex64=/^[a-f0-9]{64}$/;
+const frontName=(port:number)=>`front-${port}`;
+const noStore={'Cache-Control':'no-store','X-Content-Type-Options':'nosniff','Referrer-Policy':'no-referrer'};
+const refuse=(error:string,status:number)=>Response.json({error},{status,headers:noStore});
+export function frontPort(value?:number):number{const raw=value??(process.env.RIG_REVIEW_FRONT_PORT===undefined?defaultFrontPort:Number(process.env.RIG_REVIEW_FRONT_PORT));if(!Number.isSafeInteger(raw)||raw<1||raw>65535)throw new Error('FRONT_PORT: RIG_REVIEW_FRONT_PORT expects an integer 1..65535');return raw;}
+function frontValue(value:unknown,port:number):FrontRecord|null{if(!value||typeof value!=='object'||Array.isArray(value))return null;const v=value as Partial<FrontRecord>;return v.schema==='rig-review-front/1'&&v.port===port&&v.origin===`http://127.0.0.1:${port}`&&uuid.test(v.nonce??'')&&hex64.test(v.fingerprint??'')&&Number.isSafeInteger(v.pid)&&v.pid!>0?v as FrontRecord:null;}
+async function readFront(file:string,port:number):Promise<FrontRecord|null>{try{return frontValue(await smallJson(file),port);}catch(e){if(['ENOENT','ELOOP'].includes((e as NodeJS.ErrnoException).code??'')||e instanceof SyntaxError)return null;throw e;}}
+async function frontAlive(row:FrontRecord):Promise<boolean>{try{const response=await fetch(row.origin+'/api/front-status',{headers:{authorization:'Bearer '+row.nonce},redirect:'error',signal:AbortSignal.timeout(1500)});if(!response.ok){void response.body?.cancel();return false;}const v=await response.json() as {schema?:string;nonce?:string;fingerprint?:string};return v.schema==='rig-review-front-status/1'&&v.nonce===row.nonce&&v.fingerprint===row.fingerprint;}catch{return false;}}
+/** Ensure this state directory's front on `port`; reuse a verified live one. A front from another tool
+ * build is ours (verified nonce) and is replaced. Any other listener is FRONT_PORT_BUSY, never a fallback. */
+export async function ensureFront(options:{control:string;port:number;fingerprint:string;idleMs?:number}):Promise<string>{
+ const {control,port,fingerprint}=options,name=frontName(port),recordPath=join(control,name+'.json'),nonce=randomUUID(),deadline=performance.now()+20000,idleMs=options.idleMs??30*60*1000;
+ const reuse=async()=>{const row=await readFront(recordPath,port);if(!row||!await frontAlive(row))return null;if(row.fingerprint===fingerprint)return row;
+  try{process.kill(row.pid,'SIGTERM');}catch{}for(let n=0;n<100&&await frontAlive(row);n++)await sleep(30);return null;};
+ const ready=await reuse();if(ready)return ready.origin;
+ const claimed=await acquireClaim(control,name,nonce,reuse,deadline,'FRONT_BUSY: front startup claim did not become ready');if('row' in claimed)return claimed.row.origin;
+ let request:string|undefined,child:ReturnType<typeof spawn>|undefined,handedOff=false;
+ try{
+  const row=await reuse();if(row)return row.origin;
+  request=join(control,`${name}.${nonce}.request.json`);const log=join(control,`${name}.${nonce}.log`);
+  const spec:FrontRequest={schema:'rig-review-front-request/1',control,request,record:recordPath,port,nonce,fingerprint,idleMs};await writeFile(request,JSON.stringify(spec),{mode:0o600,flag:'wx'});
+  const logHandle=await openFile(log,'a',0o600);try{child=spawn(process.execPath,[join(appRoot,'src/front-worker.ts'),request],{cwd:control,detached:true,stdio:['ignore',logHandle.fd,logHandle.fd],env:process.env});child.unref();}finally{await logHandle.close();}
+  let exited:string|undefined;child.on('error',error=>{exited=error.message;});child.on('exit',(code,signal)=>{exited=`exit ${code} ${signal??''}`;});
+  while(performance.now()<deadline){const live=await reuse();if(live){handedOff=true;return live.origin;}
+   if(exited){if(/FRONT_PORT_BUSY/.test(await readFile(log,'utf8').catch(()=>'')))throw new Error(`FRONT_PORT_BUSY: 127.0.0.1:${port} is held by another listener; use --direct (or set RIG_REVIEW_FRONT_PORT)`);throw new Error(`FRONT_START: ${exited}; front log ${log}`);}
+   await sleep(30);}
+  throw new Error(`FRONT_TIMEOUT: front did not become ready; log ${log}`);
+ }finally{if(child&&!handedOff&&child.exitCode===null&&child.signalCode===null)child.kill('SIGTERM');await releaseClaim(join(control,name+'.claim'),nonce);if(request)await unlink(request).catch(e=>{if(e.code!=='ENOENT')throw e;});}
+}
+interface Route {mutation:boolean;limit:number;timeoutMs:number;control:boolean}
+/** Closed allowlist per method. Agent control endpoints, open-status and anything unlisted are refused. */
+export function frontRoute(mode:'single'|'compare',method:string,path:string):Route|null{
+ const read=method==='GET'||method==='HEAD',get:Route={mutation:false,limit:0,timeoutMs:30000,control:false};
+ if(['/','/index.html','/main.js','/styles.css','/api/access'].includes(path))return read?get:null;
+ if(path==='/api/control/config')return method==='GET'?{...get,control:true}:null;
+ if(['/api/control/register','/api/control/poll','/api/control/ack','/api/control/close'].includes(path))return method==='POST'?{mutation:true,limit:16384,timeoutMs:10000,control:true}:null;
+ const session=mode==='single'?'/api/session':'/api/compare/session',strip=mode==='single'?'/api/strip':'/api/compare/strip';
+ if(path===session)return read?get:method==='PUT'?{mutation:true,limit:1024*1024,timeoutMs:30000,control:false}:null;
+ if(path===strip)return method==='POST'?{mutation:true,limit:1024*1024,timeoutMs:120000,control:false}:null;
+ const reads=mode==='single'?['/api/review','/review-reference']:['/api/compare','/api/compare/reference-frames','/compare-reference'];
+ if(reads.includes(path))return read?get:null;
+ if((mode==='single'?/^\/assets\/[^/]/:/^\/compare-assets\/(a|b)\/[^/]/).test(path))return read?get:null;
+ return null;
+}
+async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{
+ if(!/^application\/json(?:\s*;|$)/i.test(req.headers.get('content-type')??''))throw new Error('FRONT_JSON_REQUIRED');
+ const declared=req.headers.get('content-length');if(declared!==null&&(!/^\d+$/.test(declared)||Number(declared)>limit))throw new Error('FRONT_BODY_LIMIT');
+ if(!req.body)throw new Error('FRONT_JSON_REQUIRED');const reader=req.body.getReader();let timer:ReturnType<typeof setTimeout>|undefined;
+ try{return await Promise.race([(async()=>{const chunks:Uint8Array[]=[];let size=0;while(true){const next=await reader.read();if(next.done)break;size+=next.value.length;if(size>limit)throw new Error('FRONT_BODY_LIMIT');chunks.push(next.value);}const bytes=new Uint8Array(size);let at=0;for(const chunk of chunks){bytes.set(chunk,at);at+=chunk.length;}return bytes.buffer;})(),new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new Error('FRONT_BODY_TIMEOUT')),timeoutMs);})]);}
+ finally{if(timer)clearTimeout(timer);void reader.cancel().catch(()=>{});}
+}
+/** Owner-only regular record for this key, or null. */
+async function instanceRecord(control:string,key:string):Promise<RecordFile|null>{const file=join(control,key+'.json');try{const info=await lstat(file);if(!info.isFile()||(info.mode&0o077)!==0)return null;}catch(e){if((e as NodeJS.ErrnoException).code==='ENOENT')return null;throw e;}return readRecord(file,key);}
+/** Worker statuses map to named front codes; worker text never reaches the client. */
+const upstreamFailure:Record<number,string>={400:'FRONT_UPSTREAM_REJECTED',403:'FRONT_UPSTREAM_FORBIDDEN',404:'FRONT_UPSTREAM_NOT_FOUND',405:'FRONT_UPSTREAM_METHOD',409:'FRONT_UPSTREAM_CONFLICT'};
+const responseHeaders=['content-type','content-length','content-range','accept-ranges','content-disposition','cache-control','content-security-policy','x-content-type-options','referrer-policy'];
+export const maximumUpstreamStreams=32;
+export function startFront(options:{control:string;port:number;nonce:string;fingerprint:string}){
+ const origin=`http://127.0.0.1:${options.port}`;let active=0,last=performance.now();
+ const server=Bun.serve({hostname:'127.0.0.1',port:options.port,async fetch(req){
+  last=performance.now();
+  try{
+   const url=new URL(req.url);if(url.origin!==origin)return refuse('FRONT_LOOPBACK_REQUIRED',403);
+   if(url.pathname==='/api/front-status'){if(req.method!=='GET'||!sameSecret(req.headers.get('authorization'),'Bearer '+options.nonce))return refuse('FRONT_STATUS_CAPABILITY_REQUIRED',403);return Response.json({schema:'rig-review-front-status/1',nonce:options.nonce,fingerprint:options.fingerprint},{headers:noStore});}
+   const match=/^\/instances\/([a-f0-9]{64})(\/.*)$/.exec(url.pathname);if(!match)return refuse('FRONT_ROUTE_REFUSED',404);
+   const key=match[1]!,path=match[2]!,sentOrigin=req.headers.get('origin');
+   if(req.headers.get('sec-fetch-site')==='cross-site'||sentOrigin!==null&&sentOrigin!==origin)return refuse('FRONT_SAME_ORIGIN_REQUIRED',403);
+   const record=await instanceRecord(options.control,key);if(!record)return refuse('FRONT_INSTANCE_UNKNOWN: reopen with rig-review open',404);
+   const route=frontRoute(record.mode,req.method,path);if(!route)return refuse('FRONT_ROUTE_REFUSED',404);
+   const landing=path==='/'||path==='/index.html';if(!landing&&url.search)return refuse('FRONT_QUERY_REFUSED',400);
+   let body:ArrayBuffer|undefined;
+   if(route.mutation){
+    // Never rewrite Origin without this instance's capability; the worker compares it again itself.
+    if(sentOrigin!==origin)return refuse('FRONT_SAME_ORIGIN_REQUIRED',403);
+    if(!sameSecret(req.headers.get(capabilityHeader),record.capability))return refuse('FRONT_CAPABILITY_REQUIRED: reopen with rig-review open to edit',403);
+    body=await boundedBody(req,route.limit);
+    if(!await alive(record))return refuse('FRONT_INSTANCE_EXPIRED: reopen with rig-review open',410);
+   }
+   if(active>=maximumUpstreamStreams)return refuse('FRONT_BUSY: too many concurrent upstream streams',503);
+   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);}
+   if(route.mutation){headers.set('origin',record.origin);headers.set(capabilityHeader,record.capability);}
+   active++;let released=false;const abort=new AbortController(),timer=setTimeout(()=>abort.abort(),route.timeoutMs);const release=()=>{if(released)return;released=true;active--;clearTimeout(timer);};
+   req.signal.addEventListener('abort',()=>abort.abort(),{once:true});
+   let upstream:Response;
+   try{upstream=await fetch(record.origin+path+(landing?url.search:''),{method:req.method,headers,...(body?{body}:{}),redirect:'manual',signal:abort.signal});}
+   catch{release();return abort.signal.aborted&&!req.signal.aborted?refuse('FRONT_UPSTREAM_TIMEOUT',504):refuse('FRONT_INSTANCE_EXPIRED: reopen with rig-review open',410);}
+   if(upstream.headers.get(openKeyHeader)!==key){void upstream.body?.cancel().catch(()=>{});release();return refuse('FRONT_INSTANCE_REPLACED: reopen with rig-review open',410);}
+   if(upstream.status>=400&&upstream.status!==416){void upstream.body?.cancel().catch(()=>{});release();const code=upstreamFailure[upstream.status];return refuse(code??'FRONT_UPSTREAM_FAILED',code?upstream.status:502);}
+   const out=new Headers();for(const name of responseHeaders){const value=upstream.headers.get(name);if(value!==null)out.set(name,value);}
+   if(!upstream.body||req.method==='HEAD'){void upstream.body?.cancel().catch(()=>{});release();return new Response(null,{status:upstream.status,headers:out});}
+   clearTimeout(timer);const reader=upstream.body.getReader();
+   // Media/model streams stay counted until finished or cancelled by the browser.
+   const stream=new ReadableStream<Uint8Array>({async pull(controller){try{const next=await reader.read();if(next.done){controller.close();release();}else controller.enqueue(next.value);}catch(error){release();controller.error(error);}},cancel(reason){release();abort.abort();return reader.cancel(reason).catch(()=>{});}});
+   return new Response(stream,{status:upstream.status,headers:out});
+  }catch(error){const message=error instanceof Error?error.message:'';return refuse(message.startsWith('FRONT_')?message:'FRONT_REQUEST_FAILED',message==='FRONT_BODY_LIMIT'?413:message==='FRONT_BODY_TIMEOUT'?408:400);}
+ }});
+ return {origin,stop:()=>server.stop(true),idleMs:()=>performance.now()-last,active:()=>active};
+}
+async function liveInstances(control:string):Promise<boolean>{for(const name of await readdir(control))if(/^[a-f0-9]{64}\.json$/.test(name)){const row=await readRecord(join(control,name),name.slice(0,64)).catch(()=>null);if(row&&running(row.pid))return true;}return false;}
+export async function runFront(requestPath:string):Promise<void>{
+ const spec=await smallJson(requestPath) as FrontRequest;if(spec?.schema!=='rig-review-front-request/1'||!uuid.test(spec.nonce??'')||!hex64.test(spec.fingerprint??'')||!Number.isSafeInteger(spec.port)||spec.port<1||spec.port>65535||!Number.isSafeInteger(spec.idleMs)||spec.idleMs<100)throw new Error('front: invalid request');
+ const control=await realpath(spec.control);if(dirname(await realpath(requestPath))!==control||spec.request!==requestPath||spec.record!==join(control,frontName(spec.port)+'.json'))throw new Error('front: invalid state locations');
+ if(await openFingerprint()!==spec.fingerprint)throw new Error('front: tool changed before startup');
+ let front:ReturnType<typeof startFront>;
+ try{front=startFront({control,port:spec.port,nonce:spec.nonce,fingerprint:spec.fingerprint});}catch(error){if((error as NodeJS.ErrnoException).code==='EADDRINUSE'||/in use/i.test(error instanceof Error?error.message:''))throw new Error(`FRONT_PORT_BUSY: 127.0.0.1:${spec.port}`);throw error;}
+ const record:FrontRecord={schema:'rig-review-front/1',origin:front.origin,port:spec.port,nonce:spec.nonce,fingerprint:spec.fingerprint,pid:process.pid},tmp=spec.record+'.'+spec.nonce+'.tmp';await writeFile(tmp,JSON.stringify(record),{mode:0o600,flag:'wx'});await rename(tmp,spec.record);
+ await unlink(requestPath).catch(e=>{if(e.code!=='ENOENT')throw e;});
+ let stopped=false;const stop=async()=>{if(stopped)return;stopped=true;clearInterval(timer);front.stop();const current=await readFront(spec.record,spec.port).catch(()=>null);if(current?.nonce===spec.nonce)await unlink(spec.record).catch(()=>{});process.exit(0);};
+ // Idle exit only once no request arrived for idleMs and no live worker record remains.
+ const timer=setInterval(()=>{if(front.idleMs()>=spec.idleMs&&front.active()===0)void liveInstances(control).then(live=>{if(!live)void stop();}).catch(()=>{});},Math.min(1000,spec.idleMs));
+ process.on('SIGTERM',()=>{void stop();});process.on('SIGINT',()=>{void stop();});
+}

package/src/manifest.ts

@@ -0,0 +1,140 @@
+import { createHash } from 'node:crypto';
+import { toolVersions } from './versions.ts';
+import type { FeedbackCatalog } from './feedback-validation.ts';
+import { validatePoseSequence } from './pose.ts';
+import { parseReport, type ReportSeeds } from './report.ts';
+import { readFile, realpath, stat, lstat, readdir } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, posix } from 'node:path';
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export interface Reference { id: string; label: string; type: 'image' | 'video' | 'pose'; path: string; width?: number; height?: number }
+export interface Checkpoint { id: string; title: string; time?: number; animation?: string; reference?: string; note?: string; workspace?: 'modeling' | 'motion'; camera?: { zoom: number; x: number; y: number }; axis?: {id:string;value:number} }
+export interface ReviewManifest {
+  schema: 'rig-review/1'; id: string; title: string; revision: string; model?: string; motion?: string;
+  references: Reference[]; animations: { id: string; label?: string; duration?: number }[];
+  checkpoints: Checkpoint[]; authoring: { label: string; path: string }[];
+  axes: { id: string; label: string; animation: string; min: number; max: number }[];
+  audio: { clips: { id: string; label?: string; path: string }[]; cues: { id: string; clip: string; time: number; animation?: string }[] };
+}
+export interface ReviewedSource { readonly packageRevision:string; readonly viewerVersion:string; readonly runtimeVersion:string; readonly rig:{readonly path:string;readonly sha256:string}|null; readonly motion:{readonly path:string;readonly sha256:string}|null }
+export interface ReviewPackage { root: string; manifestPath: string; manifest: ReviewManifest; sourceHash: string; reviewedSource:ReviewedSource; files: Set<string>; report:ReportSeeds|null; feedbackCatalog:FeedbackCatalog }
+function fail(field: string, expected: string): never { throw new Error(`${field}: expected ${expected}`); }
+export function object(value: unknown, field: string): Record<string, unknown> { if (!value || typeof value !== 'object' || Array.isArray(value)) fail(field, 'object'); return value as Record<string, unknown>; }
+export function string(value: unknown, field: string): string { if (typeof value !== 'string' || !value.trim() || value.length > 10000) fail(field, 'nonempty string (at most 10000 characters)'); return value; }
+function id(value: unknown, field: string): string { const s = string(value, field); if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(s)) fail(field, 'identifier [A-Za-z0-9][A-Za-z0-9._-], at most 128 characters'); return s; }
+export function choice<T extends string>(value: unknown, choices: readonly T[], field: string): T { if (!choices.includes(value as T)) fail(field, choices.join(' | ')); return value as T; }
+function number(value: unknown, field: string, min = 0): number { if (typeof value !== 'number' || !Number.isFinite(value) || value < min) fail(field, `finite number >= ${min}`); return value; }
+function optionalString(value: unknown, field: string): string | undefined { return value === undefined ? undefined : string(value, field); }
+function optionalNumber(value: unknown, field: string): number | undefined { return value === undefined ? undefined : number(value, field); }
+function list<T>(value: unknown, field: string, parse: (v: Record<string, unknown>, field: string) => T): T[] {
+  if (value === undefined) return []; if (!Array.isArray(value) || value.length > 10000) fail(field, 'array of at most 10000 entries');
+  const result = value.map((v, i) => parse(object(v, `${field}[${i}]`), `${field}[${i}]`));
+  const ids = result.filter((v): v is T & { id: string } => !!v && typeof v === 'object' && 'id' in v);
+  if (new Set(ids.map(v => v.id)).size !== ids.length) fail(field, 'unique ids'); return result;
+}
+/** Manifest paths are literal portable relative paths, never encoded URLs. */
+export function packagePath(value: unknown, field = 'path'): string {
+  const p = string(value, field);
+  if (isAbsolute(p) || /^[a-zA-Z]:/.test(p) || /[:\\%?#\x00-\x1f]/.test(p) || p.split('/').some(s => !s || s === '.' || s === '..') || posix.normalize(p) !== p) fail(field, 'literal relative path inside package; no traversal, encoding, backslash, query or fragment');
+  return p;
+}
+export async function safeFile(root: string, path: string): Promise<string> {
+  packagePath(path); const full = await realpath(resolve(root, path)); const rel = relative(root, full);
+  if (!rel || rel.startsWith('..' + '/') || rel === '..' || isAbsolute(rel)) fail(path, 'file inside package (symlinks may not escape)');
+  if (!(await stat(full)).isFile()) fail(path, 'regular file'); return full;
+}
+export function parseManifest(input: unknown): ReviewManifest {
+  const m = object(input, 'review'); if (m.schema !== 'rig-review/1') fail('schema', 'rig-review/1');
+  const audio = m.audio === undefined ? {} : object(m.audio, 'audio');
+  const manifest: ReviewManifest = {
+    schema: 'rig-review/1', id: id(m.id, 'id'), title: string(m.title, 'title'), revision: string(m.revision, 'revision'),
+    model: m.model === undefined ? undefined : packagePath(m.model, 'model'),
+    motion:m.motion===undefined?undefined:packagePath(m.motion,'motion'),
+    references: list(m.references, 'references', (v,f) => ({ id:id(v.id,f+'.id'), label:string(v.label,f+'.label'), type:choice(v.type,['image','video','pose'],f+'.type'), path:packagePath(v.path,f+'.path'), width:v.width===undefined?undefined:number(v.width,f+'.width',Number.EPSILON), height:v.height===undefined?undefined:number(v.height,f+'.height',Number.EPSILON) })),
+    animations: list(m.animations,'animations',(v,f) => ({id:id(v.id,f+'.id'),label:optionalString(v.label,f+'.label'),duration:optionalNumber(v.duration,f+'.duration')})),
+    checkpoints: list(m.checkpoints,'checkpoints',(v,f) => ({id:id(v.id,f+'.id'),title:string(v.title,f+'.title'),time:optionalNumber(v.time,f+'.time'),animation:optionalString(v.animation,f+'.animation'),reference:optionalString(v.reference,f+'.reference'),note:optionalString(v.note,f+'.note'),workspace:v.workspace === undefined ? undefined : choice(v.workspace,['modeling','motion'] as const,f+'.workspace'),axis:v.axis===undefined?undefined:(()=>{const a=object(v.axis,f+'.axis');return {id:id(a.id,f+'.axis.id'),value:number(a.value,f+'.axis.value',-Number.MAX_VALUE)};})(),camera:v.camera === undefined ? undefined : (() => {const c=object(v.camera,f+'.camera'); const zoom=number(c.zoom,f+'.camera.zoom',Number.EPSILON); return {zoom,x:number(c.x,f+'.camera.x',-Number.MAX_VALUE),y:number(c.y,f+'.camera.y',-Number.MAX_VALUE)};})()})),
+    authoring:list(m.authoring,'authoring',(v,f)=>({label:string(v.label,f+'.label'),path:packagePath(v.path,f+'.path')})),
+    axes:list(m.axes,'axes',(v,f)=>({id:id(v.id,f+'.id'),label:string(v.label,f+'.label'),animation:string(v.animation,f+'.animation'),min:number(v.min,f+'.min',-Number.MAX_VALUE),max:number(v.max,f+'.max',-Number.MAX_VALUE)})),
+    audio:{clips:list(audio.clips,'audio.clips',(v,f)=>({id:id(v.id,f+'.id'),label:optionalString(v.label,f+'.label'),path:packagePath(v.path,f+'.path')})),cues:list(audio.cues,'audio.cues',(v,f)=>({id:id(v.id,f+'.id'),clip:string(v.clip,f+'.clip'),time:number(v.time,f+'.time'),animation:optionalString(v.animation,f+'.animation')}))}
+  };
+  if(manifest.model&&!manifest.model.endsWith('.model.json'))fail('model','compiled model path ending .model.json (the play runtime input)');
+  for (const c of manifest.checkpoints) { if(c.reference && !manifest.references.some(r=>r.id===c.reference)) fail(`checkpoint ${c.id}.reference`,'declared reference id'); if(c.animation && !manifest.animations.some(a=>a.id===c.animation)) fail(`checkpoint ${c.id}.animation`,'declared animation id'); }
+  for (const c of manifest.audio.cues) { if(!manifest.audio.clips.some(a=>a.id===c.clip)) fail(`cue ${c.id}.clip`,'declared audio clip id'); if(c.animation && !manifest.animations.some(a=>a.id===c.animation)) fail(`cue ${c.id}.animation`,'declared animation id'); }
+  for (const a of manifest.axes) { if(a.min >= a.max) fail(`axis ${a.id}`,'min < max'); if(!manifest.animations.some(v=>v.id===a.animation)) fail(`axis ${a.id}.animation`,'declared animation id'); }
+  for(const c of manifest.checkpoints) if(c.axis){const a=manifest.axes.find(a=>a.id===c.axis!.id);if(!a)fail(`checkpoint ${c.id}.axis`,'declared axis id');if(c.axis.value<a.min||c.axis.value>a.max)fail(`checkpoint ${c.id}.axis.value`,`number in [${a.min}, ${a.max}]`);}
+  return manifest;
+}
+export async function loadReview(input: string): Promise<ReviewPackage> {
+  const inputPath=await realpath(resolve(input));const directory=(await stat(inputPath)).isDirectory();
+  if(directory){try{await stat(resolve(inputPath,'review.json'));return loadReview(resolve(inputPath,'review.json'));}catch(e){if((e as NodeJS.ErrnoException).code!=='ENOENT')throw e;}}
+  const manifestPath=inputPath;const root=directory?inputPath:await realpath(dirname(inputPath));
+  const manifest=directory?await folderManifest(root):parseManifest(JSON.parse(await readFile(manifestPath,'utf8')));
+  const files = new Set([...(directory?[]:[relative(root,manifestPath)]),...manifest.references.map(v=>v.path),...manifest.authoring.map(v=>v.path),...manifest.audio.clips.map(v=>v.path)]);
+  const rootFile=async(name:string):Promise<string|undefined>=>{try{await safeFile(root,name);return name;}catch(e){if((e as NodeJS.ErrnoException).code==='ENOENT')return undefined;throw e;}};
+  const authoringPath=(name:string):string|undefined=>{const paths=manifest.authoring.filter(v=>posix.basename(v.path)===name);return paths.length===1?paths[0].path:undefined;};
+  const rigPath=manifest.model??await rootFile('skeleton.json')??authoringPath('skeleton.json')??await rootFile('skeleton.skel')??authoringPath('skeleton.skel');
+  const motionPath=manifest.motion??await rootFile('motion.json')??authoringPath('motion.json');
+  if(rigPath)files.add(rigPath);if(motionPath)files.add(motionPath);
+  let modelBytesHash:string|null=null;
+  if(manifest.model) {
+    files.add(manifest.model); const bytes=await readFile(await safeFile(root,manifest.model));modelBytesHash=createHash('sha256').update(bytes).digest('hex');const model = object(JSON.parse(bytes.toString('utf8')),'model');
+    if(model.spec !== 'rigc-compiled/3') fail('model.spec','rigc-compiled/3, produced by a gated rigc build');
+    if(!Array.isArray(model.pages)) fail('model.pages','array');
+    for(const page of model.pages) { const p = object(page,'model.pages[]'); const name = string(p.name,'model.pages[].name'); if(isAbsolute(name)||/[:\\%?#\x00-\x1f]/.test(name)||name.split('/').some(v=>!v))fail('model.pages[].name','literal relative model page path'); files.add(packagePath(posix.join(posix.dirname(manifest.model),name),'model page resolved inside package')); }
+  }
+  for(const r of manifest.references.filter(r=>r.type==='pose')) {
+    const pose=object(JSON.parse(await readFile(await safeFile(root,r.path),'utf8')),`pose ${r.id}`);
+    if(pose.spec==='rig-pose-sequence/1'){validatePoseSequence(pose,`pose ${r.id}`);continue;}
+    if(pose.schema!=='rig-review-pose/1'||pose.coordinateSystem!=='image-pixels-y-down') fail(`pose ${r.id}`,'rig-review-pose/1 with image-pixels-y-down coordinates');
+    number(pose.width,`pose ${r.id}.width`,Number.EPSILON); number(pose.height,`pose ${r.id}.height`,Number.EPSILON);
+    const joints=list(pose.joints,`pose ${r.id}.joints`,(v,f)=>({id:id(v.id,f+'.id'),x:number(v.x,f+'.x',-Number.MAX_VALUE),y:number(v.y,f+'.y',-Number.MAX_VALUE),parent:optionalString(v.parent,f+'.parent')}));
+    for(const j of joints) if(j.parent&&!joints.some(v=>v.id===j.parent&&v.id!==j.id)) fail(`pose ${r.id} joint ${j.id}.parent`,'another declared joint id');
+  }
+  const reportPath=files.has('report.json')?'report.json':authoringPath('report.json');let report:ReportSeeds|null=null;let modelMetadata:Record<string,unknown>|null=null;
+  const hash = createHash('sha256');hash.update(JSON.stringify(manifest));hash.update('\0');const fileHashes=new Map<string,string>();
+  for(const p of [...files].sort()) { const full=await safeFile(root,p); const before=await stat(full); hash.update(p);hash.update('\0');hash.update(String(before.size));hash.update('\0'); const fileHash=createHash('sha256');const metadataChunks:Buffer[]=[];for await(const chunk of createReadStream(full)){hash.update(chunk);fileHash.update(chunk);if(p===reportPath||p===manifest.model)metadataChunks.push(chunk);}fileHashes.set(p,fileHash.digest('hex')); const after=await stat(full); if(before.size!==after.size||before.mtimeMs!==after.mtimeMs) throw new Error(`Asset ${p} changed while hashing; retry with stable package inputs`);
+    // The parser and package hash consume the same bytes, never two file reads.
+    if(p===manifest.model){if(fileHashes.get(p)!==modelBytesHash)throw new Error(`Model ${p} changed while hashing; retry with stable package inputs`);modelMetadata=object(JSON.parse(Buffer.concat(metadataChunks).toString('utf8')),'model');}
+    if(p===reportPath){let value:unknown;try{value=JSON.parse(Buffer.concat(metadataChunks).toString('utf8'));}catch(e){throw new Error(`${p}: ${e instanceof Error?e.message:String(e)}`);}report=parseReport(value,p);}
+  }
+  const reviewedSource:ReviewedSource={packageRevision:manifest.revision,...await toolVersions(),rig:rigPath?{path:rigPath,sha256:fileHashes.get(rigPath)!}:null,motion:motionPath?{path:motionPath,sha256:fileHashes.get(motionPath)!}:null};
+  const feedbackCatalog:FeedbackCatalog={rig:manifest.id,bones:modelNames(modelMetadata,'bones'),slots:modelNames(modelMetadata,'slots'),animations:modelAnimations(modelMetadata),clock:report?.clock??null,clockAnimation:report?.animation??null};
+  return {root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog};
+}
+
+/** An adapter over an existing output directory; never writes a manifest there. */
+async function folderManifest(root:string):Promise<ReviewManifest>{
+  const entries=(await readdir(root,{withFileTypes:true})).filter(v=>v.isFile()||v.isSymbolicLink()).map(v=>v.name).sort();
+  const has=(name:string)=>entries.includes(name);const references:Reference[]=[];
+  let model:string|undefined;
+  // These are named layouts, not a recursive search. Check existence separately
+  // so an existing broken symlink is refused rather than treated as absent.
+  for(const candidate of ['skeleton.model.json','build/skeleton.model.json']){
+    try{await lstat(resolve(root,candidate));}catch(e){if((e as NodeJS.ErrnoException).code==='ENOENT')continue;throw e;}
+    await safeFile(root,candidate);model=candidate;break;
+  }
+  for(const name of entries){
+    if(/\.(mp4|webm|mov)$/i.test(name))references.push({id:`video-${references.length+1}`,label:name,type:'video',path:name});
+    if(/(strip|contact|sheet|띠|filmstrip)/i.test(name)&&/\.(png|jpe?g|webp|svg)$/i.test(name))references.push({id:`strip-${references.length+1}`,label:name,type:'image',path:name});
+    if(/pose/i.test(name)&&/\.json$/i.test(name)){const value=JSON.parse(await readFile(await safeFile(root,name),'utf8'));if(value?.spec==='rig-pose-sequence/1'||value?.schema==='rig-review-pose/1')references.push({id:`pose-${references.length+1}`,label:name,type:'pose',path:name});}
+  }
+  const name=basename(root);const packageId=name.replace(/[^a-zA-Z0-9._-]+/g,'-').replace(/^[^a-zA-Z0-9]+/,'').slice(0,128)||'output-bundle';
+  const authoring=entries.filter(n=>n==='motion.json'||n==='report.json'||(/^skeleton\./i.test(n)&&n!=='skeleton.model.json')).map(path=>({label:path+' · read only',path}));
+  if(!references.length&&!authoring.length&&!model)throw new Error('Output folder: no recognized skeleton.*, build/skeleton.model.json, motion.json, report.json, source video, pose sequence or contact strip');
+  return parseManifest({schema:'rig-review/1',id:packageId,title:name,revision:'folder-adapter/1',model,motion:has('motion.json')?'motion.json':undefined,references,authoring,checkpoints:references.map(r=>({id:r.id,title:'Inspect '+r.label,reference:r.id,workspace:'motion'}))});
+}
+
+/** Exact hashed model bytes supply names; absent metadata stays unavailable. */
+function modelNames(model:Record<string,unknown>|null,field:'bones'|'slots'):string[]|null {
+  if(model===null||model[field]===undefined)return null;
+  const entries=model[field];if(!Array.isArray(entries))fail(`model.${field}`,'array');
+  const names=entries.map((value,i)=>string(object(value,`model.${field}[${i}]`).name,`model.${field}[${i}].name`));
+  if(new Set(names).size!==names.length)fail(`model.${field}`,'unique names');return names;
+}
+function modelAnimations(model:Record<string,unknown>|null):FeedbackCatalog['animations'] {
+  if(model===null||model.animations===undefined)return null;
+  if(!Array.isArray(model.animations))fail('model.animations','array');
+  const animations=model.animations.map((value,i)=>{const v=object(value,`model.animations[${i}]`);return {name:string(v.name,`model.animations[${i}].name`),duration:number(v.duration,`model.animations[${i}].duration`)};});
+  if(new Set(animations.map(value=>value.name)).size!==animations.length)fail('model.animations','unique names');return animations;
+}

package/src/open-protocol.ts

@@ -0,0 +1,31 @@
+/** Fixed-instance handshake and enforced landing binding; no filesystem control API. */
+import {timingSafeEqual} from 'node:crypto';
+export interface OpenIdentity {key:string;contentHash:string;nonce:string;fingerprint:string}
+export function openGate(req:Request,identity:OpenIdentity|undefined):Response|null{
+ if(!identity)return null;const url=new URL(req.url);
+ if(url.pathname==='/api/open-status'){
+  if(req.method!=='GET')return Response.json({error:'Method not allowed'},{status:405});
+  if(req.headers.get('authorization')!==`Bearer ${identity.nonce}`)return Response.json({error:'Open instance capability required'},{status:403});
+  return Response.json({schema:'rig-review-open-status/1',...identity},{headers:{'Cache-Control':'no-store'}});
+ }
+ if((url.pathname==='/'||url.pathname==='/index.html')&&(url.searchParams.get('input')!==identity.contentHash||url.searchParams.get('handoff')!==identity.key))return Response.json({error:'Open URL binding does not match this review instance'},{status:409});
+ return null;
+}
+
+export function staleOpenStatus(identity:OpenIdentity):Response{return Response.json({schema:'rig-review-open-status/1',...identity,ready:false,error:'Inputs changed; open a new review binding'},{status:409,headers:{'Cache-Control':'no-store'}});}
+/** Header names shared by the worker, the managed front and the page. */
+export const capabilityHeader='X-Review-Capability',openNonceHeader='X-Review-Open-Nonce',openKeyHeader='X-Review-Open-Key';
+export const capabilityPattern=/^[a-f0-9]{64}$/;
+export function sameSecret(actual:string|null,expected:string):boolean{const a=Buffer.from(actual??''),b=Buffer.from(expected);return a.length===b.length&&timingSafeEqual(a,b);}
+/** Every non-GET request needs this instance's page capability, compared in constant time before any
+ * Origin check. GET /api/access only says whether one is required; no endpoint ever returns it. */
+export function accessGate(req:Request,capability:string|undefined):Response|null{
+ const url=new URL(req.url),headers={'Cache-Control':'no-store','X-Content-Type-Options':'nosniff'};
+ if(url.pathname==='/api/access')return req.method==='GET'||req.method==='HEAD'?Response.json({schema:'rig-review-access/1',capabilityRequired:!!capability},{headers}):Response.json({error:'Method not allowed'},{status:405,headers});
+ if(!capability||req.method==='GET'||req.method==='HEAD')return null;
+ return sameSecret(req.headers.get(capabilityHeader),capability)?null:Response.json({error:'REVIEW_CAPABILITY_REQUIRED: reopen with rig-review open to edit'},{status:403,headers});
+}
+/** The front forwards the open record's nonce on every request; a replaced worker refuses it. */
+export function openNonceGate(req:Request,identity:OpenIdentity|undefined):Response|null{const sent=req.headers.get(openNonceHeader);if(sent===null||!identity)return null;return sameSecret(sent,identity.nonce)?null:Response.json({error:'OPEN_INSTANCE_REPLACED'},{status:409,headers:{'Cache-Control':'no-store'}});}
+/** Proof for the front that this exact worker answered, not whatever now holds the port. */
+export function stampOpen(req:Request,response:Response,identity:OpenIdentity|undefined):Response{if(identity&&sameSecret(req.headers.get(openNonceHeader),identity.nonce))response.headers.set(openKeyHeader,identity.key);return response;}

package/src/open-selection.ts

@@ -0,0 +1,11 @@
+import type {ReviewManifest} from './manifest.ts';
+/** An explicit CLI video wins automatic startup, never a human/deep-link choice. */
+export function initialReviewSelection(manifest:Pick<ReviewManifest,'checkpoints'|'references'>&Partial<Pick<ReviewManifest,'axes'>>,requestedId:string|null,explicitId?:string,selectedAnimation?:string){
+ const automatic=manifest.checkpoints[0];
+ // Both the checkpoint and its optional axis must stay on the selected clip.
+ const axisAnimation=automatic?.axis?manifest.axes?.find(axis=>axis.id===automatic.axis!.id)?.animation:undefined;
+ const compatible=!selectedAnimation||(automatic?.animation===selectedAnimation&&(!automatic.axis||axisAnimation===selectedAnimation));
+ const checkpoint=requestedId?manifest.checkpoints.find(point=>point.id===requestedId):compatible?automatic:undefined;
+ const referenceId=requestedId&&checkpoint?.reference?checkpoint.reference:explicitId??checkpoint?.reference??manifest.references[0]?.id;
+ return {checkpoint,referenceId,updateUrl:!!requestedId||(!explicitId&&!selectedAnimation)};
+}