@rig-c/review 0.7.1 → 0.8.1

package/src/front.ts

@@ -61,11 +61,14 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
  // Bones check (#109, single only): one typed request {ops, configHash}, answered in the response.
  if(mode==='single'&&path==='/api/bones-check')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:60000,control:false}:null;
  // Readings (#108, single only): one typed request, then its job's status.
- if(mode==='single'&&path==='/api/readings')return method==='POST'?{mutation:true,limit:16*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&path==='/api/readings')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
  if(mode==='single'&&/^\/api\/readings\/[a-f0-9]{64}$/.test(path))return read?get:null;
  // Declared requirements (#113, single only): the stage's catalog, one typed request, then its job's status.
  if(mode==='single'&&path==='/api/requirements')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
  if(mode==='single'&&/^\/api\/requirements\/[a-f0-9]{64}$/.test(path))return read?get:null;
+ // Check under this world (#112, single only): one typed request {build, schedule}, then its job's status.
+ if(mode==='single'&&path==='/api/environment-check')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&/^\/api\/environment-check\/[a-f0-9]{64}$/.test(path))return read?get:null;
  return null;
 }
 async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{

package/src/handoff.ts

@@ -25,9 +25,9 @@ export const CONFIG_NAMED_FILES = [['motion', 'animations_from'], ['generation',
 export const RIG_FILES = ['rig.json', 'motion.json', 'mesh_report.json'] as const;
 const MAX_LISTED = 4096;
 
-export interface HandoffDeclaration { config: string; parts?: string; source?: string; full?: string; head?: string }
+export interface HandoffDeclaration { config: string; parts?: string; source?: string; full?: string; head?: string; keypoints?: string }
 export type HandoffFlags = HandoffDeclaration;
-export const HANDOFF_FLAGS = ['config', 'parts', 'source', 'full', 'head'] as const;
+export const HANDOFF_FLAGS = ['config', 'parts', 'source', 'full', 'head', 'keypoints'] as const;
 export interface HandoffFile { path: string; sha256: string }
 /** The identity record: paths relative to the package root (`../` only for the discovered parent config), every hashed file. */
 export interface HandoffRecord {
@@ -37,13 +37,16 @@ export interface HandoffRecord {
   outside: boolean;
   config: HandoffFile;
   parts: string | null; rig: string | null; source: HandoffFile | null; full: string | null; head: string | null;
+  /** #111: the declared body-18 keypoint file `rig-parts propose --keypoints` reads; the key is absent when none is declared, so an undeclared handoff's identity is unchanged. */
+  keypoints?: HandoffFile;
   files: HandoffFile[];
   missing: string[];
 }
 /** The record plus the absolute paths the producer is run with (never served, never in the identity). */
 /** `source` (#109): the declared source painting's absolute path, which `propose --from-config` reads; null when none was declared. */
 /** `full` / `head` (#115): the declared See-through runs' absolute paths, which `rig-parts build` reads; null when none was declared. */
-export interface Handoff { record: HandoffRecord; config: string; parts: string | null; rig: string | null; root: string; flags?: HandoffFlags; source?: string | null; full?: string | null; head?: string | null }
+/** `keypoints` (#111): the declared keypoint file's absolute path, which a cloth recipe Apply's `propose --keypoints` reads; null when none was declared. */
+export interface Handoff { record: HandoffRecord; config: string; parts: string | null; rig: string | null; root: string; flags?: HandoffFlags; source?: string | null; full?: string | null; head?: string | null; keypoints?: string | null }
 
 export class HandoffError extends Error {
   constructor(readonly code: string, readonly field: string, readonly detail: string) { super(`${code} ${field}: ${detail}`); }
@@ -87,15 +90,15 @@ async function blockPath(root: string, value: unknown, field: string, kind: 'fil
   return contained(root, join(root, value), field, kind, true);
 }
 
-/** `producer: {config, parts?, source?, full?, head?}` — strings only, no other key. Paths are checked at load. */
+/** `producer: {config, parts?, source?, full?, head?, keypoints?}` — strings only, no other key. Paths are checked at load. */
 export function parseHandoffDeclaration(value: unknown): HandoffDeclaration | undefined {
   if (value === undefined) return undefined;
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HandoffError('HANDOFF_PATH_INVALID', 'producer', 'expected an object {config, parts?, source?, full?, head?}');
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HandoffError('HANDOFF_PATH_INVALID', 'producer', 'expected an object {config, parts?, source?, full?, head?, keypoints?}');
   const v = value as Record<string, unknown>;
-  for (const key of Object.keys(v)) if (!(HANDOFF_FLAGS as readonly string[]).includes(key)) throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'unknown key; expected config, parts, source, full, head');
+  for (const key of Object.keys(v)) if (!(HANDOFF_FLAGS as readonly string[]).includes(key)) throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'unknown key; expected config, parts, source, full, head, keypoints');
   if (typeof v.config !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', 'producer.config', 'required: the producer config path');
   const out: HandoffDeclaration = { config: v.config };
-  for (const key of ['parts', 'source', 'full', 'head'] as const) if (v[key] !== undefined) { if (typeof v[key] !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'expected a string path'); out[key] = v[key] as string; }
+  for (const key of ['parts', 'source', 'full', 'head', 'keypoints'] as const) if (v[key] !== undefined) { if (typeof v[key] !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'expected a string path'); out[key] = v[key] as string; }
   return out;
 }
 /** `--source` and `--full` travel together, `--head` only with them, and everything else only with `--config`. */
@@ -119,7 +122,7 @@ async function listed(base: string, dir: string, field: string): Promise<string[
 }
 
 /** Hash every handoff file and build the record. `root` is the package root (display paths are relative to it). */
-async function record(root: string, base: string, how: HandoffRecord['how'], via: HandoffRecord['via'], config: string, partsPath: string | null, extra: { source?: string; full?: string; head?: string }, partsDeclared: boolean): Promise<Handoff> {
+async function record(root: string, base: string, how: HandoffRecord['how'], via: HandoffRecord['via'], config: string, partsPath: string | null, extra: { source?: string; full?: string; head?: string; keypoints?: string }, partsDeclared: boolean): Promise<Handoff> {
   const show = (path: string) => relative(root, path).split(sep).join('/') || '.';
   const files = new Map<string, string>(), missing: string[] = [];
   const add = async (path: string) => { files.set(show(path), await hashFile(path)); };
@@ -154,10 +157,12 @@ async function record(root: string, base: string, how: HandoffRecord['how'], via
   let source: HandoffFile | null = null;
   if (extra.source) { await add(extra.source); source = { path: show(extra.source), sha256: files.get(show(extra.source))! }; }
   for (const dir of [extra.full, extra.head]) if (dir) for (const file of await listed(base, dir, show(dir))) await add(file);
+  // #111: hashed only when declared — an undeclared handoff's record (and so its identity) holds no keypoints key at all.
+  if (extra.keypoints) await add(extra.keypoints);
   const sorted = [...files].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, hash]) => ({ path, sha256: hash }));
   return {
-    record: { schema: HANDOFF_SCHEMA, how, via, outside: !inside(root, config), config: { path: show(config), sha256: files.get(show(config))! }, parts: parts ? show(parts) : null, rig: rig ? show(rig) : null, source, full: extra.full ? show(extra.full) : null, head: extra.head ? show(extra.head) : null, files: sorted, missing },
-    config, parts, rig, root: base, source: extra.source ?? null, full: extra.full ?? null, head: extra.head ?? null,
+    record: { schema: HANDOFF_SCHEMA, how, via, outside: !inside(root, config), config: { path: show(config), sha256: files.get(show(config))! }, parts: parts ? show(parts) : null, rig: rig ? show(rig) : null, source, full: extra.full ? show(extra.full) : null, head: extra.head ? show(extra.head) : null, ...(extra.keypoints ? { keypoints: { path: show(extra.keypoints), sha256: files.get(show(extra.keypoints))! } } : {}), files: sorted, missing },
+    config, parts, rig, root: base, source: extra.source ?? null, full: extra.full ?? null, head: extra.head ?? null, keypoints: extra.keypoints ?? null,
   };
 }
 
@@ -175,9 +180,10 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
     const source = flags.source !== undefined ? await flagPath(root, flags.source, '--source', 'file') : undefined;
     const full = flags.full !== undefined ? await flagPath(root, flags.full, '--full', 'dir') : undefined;
     const head = flags.head !== undefined ? await flagPath(root, flags.head, '--head', 'dir') : undefined;
-    const handoff = await record(root, root, 'declared', 'open --config', config, parts, { source, full, head }, flags.parts !== undefined);
+    const keypoints = flags.keypoints !== undefined ? await flagPath(root, flags.keypoints, '--keypoints', 'file') : undefined;
+    const handoff = await record(root, root, 'declared', 'open --config', config, parts, { source, full, head, keypoints }, flags.parts !== undefined);
     // Canonical absolute flags: the background worker and later reloads read exactly these.
-    handoff.flags = { config, ...(flags.parts !== undefined ? { parts } : {}), ...(source ? { source } : {}), ...(full ? { full } : {}), ...(head ? { head } : {}) };
+    handoff.flags = { config, ...(flags.parts !== undefined ? { parts } : {}), ...(source ? { source } : {}), ...(full ? { full } : {}), ...(head ? { head } : {}), ...(keypoints ? { keypoints } : {}) };
     return { handoff, reason: null };
   }
   if (declared) {
@@ -186,8 +192,9 @@ export async function resolveHandoff(root: string, declared: HandoffDeclaration
     const source = declared.source !== undefined ? await blockPath(root, declared.source, 'producer.source', 'file') : undefined;
     const full = declared.full !== undefined ? await blockPath(root, declared.full, 'producer.full', 'dir') : undefined;
     const head = declared.head !== undefined ? await blockPath(root, declared.head, 'producer.head', 'dir') : undefined;
+    const keypoints = declared.keypoints !== undefined ? await blockPath(root, declared.keypoints, 'producer.keypoints', 'file') : undefined;
     if ((source === undefined) !== (full === undefined) || (head !== undefined && full === undefined)) throw new HandoffError('HANDOFF_FLAGS_INVALID', 'producer', 'source and full are given together, head only with them');
-    return { handoff: await record(root, root, 'declared', 'review.json producer', config, parts, { source, full, head }, declared.parts !== undefined), reason: null };
+    return { handoff: await record(root, root, 'declared', 'review.json producer', config, parts, { source, full, head, keypoints }, declared.parts !== undefined), reason: null };
   }
   for (const name of ['config.json', 'rig/config.json']) {
     const path = join(root, name);

package/src/open-protocol.ts

@@ -18,10 +18,11 @@ export const capabilityHeader='X-Review-Capability',openNonceHeader='X-Review-Op
 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{
+ * Origin check. GET /api/access only says whether one is required; no endpoint ever returns it. It also says
+ * whether this instance serves agent control, so a page without it never probes `/api/control/config` (#164). */
+export function accessGate(req:Request,capability:string|undefined,control=false):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(url.pathname==='/api/access')return req.method==='GET'||req.method==='HEAD'?Response.json({schema:'rig-review-access/1',capabilityRequired:!!capability,control},{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});
 }

package/src/open.ts

@@ -18,7 +18,7 @@ import {ensureFront,frontPort} from './front.ts';
 import {playPackagePath} from './versions.ts';
 import {HandoffError,HANDOFF_FLAGS,type HandoffFlags} from './handoff.ts';
 /** `direct` chooses how the page is reached (own port instead of the managed front); it is not part of the instance identity. */
-export interface OpenInputs {input:string;compare?:string;reference?:string;animation?:string;control?:boolean;direct?:boolean;config?:string;parts?:string;source?:string;full?:string;head?:string}
+export interface OpenInputs {input:string;compare?:string;reference?:string;animation?:string;control?:boolean;direct?:boolean;config?:string;parts?:string;source?:string;full?:string;head?:string;keypoints?:string}
 /** The producer handoff flags (#101) among the inputs, or undefined when none was given. */
 export function handoffFlags(inputs:OpenInputs):HandoffFlags|undefined{const present=HANDOFF_FLAGS.filter(f=>inputs[f]!==undefined);if(!present.length)return undefined;return Object.fromEntries(present.map(f=>[f,inputs[f]])) as unknown as HandoffFlags;}
 export type OpenPackage=({mode:'single';p:ReviewPackage;inputs:OpenInputs;contentHash:string}|{mode:'compare';p:ComparePackage;inputs:OpenInputs;contentHash:string})&{selection:AnimationSelection|null};

package/src/readings-run.ts

@@ -10,6 +10,7 @@ import { copyFile, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promise
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { safeFile, type ReviewPackage } from './manifest.ts';
 import { resolveCompiler, runTool, type InstalledTool } from './producer.ts';
+import { scheduleText, type EnvironmentSchedule } from './environment-schedule.ts';
 import { environmentSchedule, helpHasEnvironment, parseReadingsRequest, READING_FILE, readingLabel, readingResult, READINGS_SCHEMA, READINGS_SINCE, ReadingsError, renderArgs, type ReadingBuild, type ReadingRequest, type ReadingResult, type ReadingsRequest } from './readings.ts';
 
 const sha256 = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
@@ -39,7 +40,7 @@ export async function runReading(r: ReadingRequest, animation: string, candidate
   try { const stored = JSON.parse(await readFile(resultFile, 'utf8')) as { key: string; result: ReadingResult }; if (stored.key === key) return stored.result; } catch { /* not run yet */ }
   await rm(dir, { recursive: true, force: true });
   await mkdir(dir, { recursive: true, mode: 0o700 });
-  if (schedule) await writeFile(join(dir, 'environment.json'), JSON.stringify(schedule, null, 1) + '\n', { mode: 0o600 });
+  if (schedule) await writeFile(join(dir, 'environment.json'), scheduleText(schedule as EnvironmentSchedule), { mode: 0o600 });
   const run = await runTool(compiler.bin, renderArgs(r, animation, { candidate, out: 'render', environment: schedule ? 'environment.json' : null }), { cwd: dir });
   let json: unknown = null, fps: number | null = null;
   if (run.exitCode === 0) {

package/src/readings.ts

@@ -7,6 +7,7 @@
  * Review judges nothing here: a reading is not a gate, and an unknown slot or bone is rigc's to refuse.
  */
 import { firstRefusal } from './producer.ts';
+import { parseSchedule, ScheduleError, standingSchedule, type EnvironmentSchedule } from './environment-schedule.ts';
 
 export const READINGS_SCHEMA = 'rig-review-readings/1';
 /** The first `rig-c` release with all five readings (its CHANGELOG: 2.63.0, "render: --overlaps names which slot covers which"). */
@@ -24,7 +25,8 @@ export type ReadingKind = ReadingRequest['kind'];
 export const READING_KINDS: readonly ReadingKind[] = ['folds', 'pass-through', 'seam', 'overlaps', 'angle-range'];
 /** The world the physics answers while the readings are posed: the Environment block's wind and gravity as they stand (x right, y down). */
 export interface ReadingEnvironment { wind: [number, number]; gravity: [number, number] }
-export interface ReadingsRequest { animation: string; readings: ReadingRequest[]; environment: ReadingEnvironment | null }
+/** #112: with "Use for readings" on, the Environment block's exported `rigc-environment/1` schedule goes in its place. */
+export interface ReadingsRequest { animation: string; readings: ReadingRequest[]; environment: ReadingEnvironment | EnvironmentSchedule | null }
 
 export class ReadingsError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
 const bad = (detail: string): never => { throw new ReadingsError('READINGS_REQUEST_INVALID', detail); };
@@ -57,8 +59,12 @@ export function parseReadingsRequest(input: unknown): ReadingsRequest {
   const readings = (v.readings as unknown[]).map((r, i) => parseReading(r, `readings[${i}]`));
   const labels = readings.map(readingLabel);
   if (new Set(labels).size !== labels.length) bad('readings: one entry named twice');
-  let environment: ReadingEnvironment | null = null;
-  if (v.environment !== null) { const e = record(v.environment, 'environment'); exactly(e, ['wind', 'gravity'], 'environment'); environment = { wind: pair(e.wind, 'environment.wind'), gravity: pair(e.gravity, 'environment.gravity') }; }
+  let environment: ReadingsRequest['environment'] = null;
+  if (v.environment !== null) {
+    const e = record(v.environment, 'environment');
+    if (Object.hasOwn(e, 'spec')) { try { environment = parseSchedule(e); } catch (error) { if (error instanceof ScheduleError) bad(`environment: ${error.message}`); throw error; } }
+    else { exactly(e, ['wind', 'gravity'], 'environment'); environment = { wind: pair(e.wind, 'environment.wind'), gravity: pair(e.gravity, 'environment.gravity') }; }
+  }
   return { animation, readings, environment };
 }
 
@@ -88,8 +94,8 @@ export interface RenderPaths { candidate: string; out: string; environment: stri
 export function renderArgs(r: ReadingRequest, animation: string, paths: RenderPaths): string[] {
   return ['render', '--candidate', paths.candidate, '--animation', animation, ...(paths.environment ? ['--environment', paths.environment] : []), ...readingFlag(r), '--out', paths.out];
 }
-/** The schedule file `--environment` reads: the world as it stands, from t = 0. */
-export const environmentSchedule = (e: ReadingEnvironment) => ({ spec: 'rigc-environment/1', steps: [{ t: 0, wind: e.wind, gravity: e.gravity }] });
+/** The schedule file `--environment` reads: the world as it stands, from t = 0 — or, #112, the exported schedule as sent. */
+export const environmentSchedule = (e: ReadingEnvironment | EnvironmentSchedule): EnvironmentSchedule => ('spec' in e ? e : standingSchedule(e));
 /** Whether this rigc's `render --help` lists `--environment` (the schedule is passed only then). */
 export const helpHasEnvironment = (lines: readonly string[]) => lines.some(l => /^\s*--environment\s/.test(l));
 
@@ -216,7 +222,7 @@ export function ticksOnClip(ticks: readonly ReadingTick[], jobAnimation: string,
 
 /** `context.readings`: the pairs chosen and where they ran (the builds' identities), never the results' bytes. */
 export interface ReadingsContext {
-  schema: typeof READINGS_SCHEMA; animation: string; requests: ReadingRequest[]; environment: ReadingEnvironment | null; environmentPassed: boolean;
+  schema: typeof READINGS_SCHEMA; animation: string; requests: ReadingRequest[]; environment: ReadingsRequest['environment']; environmentPassed: boolean;
   builds: { inspected: string; scratch: string | null }; compiler: { package: string; version: string };
   ticks: { inspected: number; scratch: number | null };
 }