spine-rigc 2.47.0 → 2.48.0

package/src/guide.ts

@@ -0,0 +1,438 @@
+/**
+ * `rigc guide` — read exactly the row of the guide a failure line names, or one
+ * numbered section of it, from the shipped `docs/AUTHORING.md` at the moment of
+ * the call (issue #1397, the form shared word for word with rig-c/parts#343).
+ *
+ * ⭐ **The guide stays one ledger.** Nothing here keeps a copy, an index or a
+ * generated split of it: every read is a slice of the file's text as it is on
+ * disk when the command runs, so there is nothing to drift. The one other file
+ * read is the one a code's row lives in when that is not AUTHORING — `ingest`'s
+ * finding codes, whose table is `docs/INGEST.md`'s *Every finding code* — and
+ * the output names the file it read.
+ *
+ * Pure: the texts come in as arguments and the lines go out as values, so the
+ * CLI owns the reading of the files and the selftest can plant on a text.
+ *
+ * 📐 What counts as a **rule row** is grammar, not a hand-kept list of tables: a
+ * table row (outside a code fence) whose first cell is one code span naming a
+ * rule — `` `A20_MESH_WEIGHTS_COHERENT` ``, optionally after its web anchor. In
+ * AUTHORING a rule name carries an underscore, which is what tells a rule from
+ * the other upper-case words tables there key on (the `BLOCK`/`JUDGE`/`LOSS`
+ * gutters, a picture's `REFERENCE` pane); in INGEST's finding-code table every
+ * row is a rule, `DURATION` included. A row whose code holds a `<WORD>` is a
+ * **family** — `ATTACHMENT_<TYPE>` — and answers for every code it spells
+ * (`ATTACHMENT_POINT`) that has no row of its own.
+ *
+ * 📐 A section is addressed the way the shared form fixes it (HQ's ruling on
+ * rig-c/parts#343): `§<n>` is the `## <n>.` heading, and `§<n>.<m>` is the m-th
+ * `###` under it, **counted** when the guide is read — never a number read off
+ * the heading. AUTHORING also writes the number into each `###`, so the two
+ * must agree, and `numberingFaults` is what says where they do not.
+ */
+
+/** The command a pointer names — `rigc` here, `rig-parts` in the sibling package. */
+export const GUIDE_BIN = 'rigc';
+
+/** The guide, relative to the package root — what every read is a slice of. */
+export const GUIDE_FILE = 'docs/AUTHORING.md';
+
+/**
+ * The shipped documents a rule's row may live in other than the guide, and the
+ * heading that opens the one table of rules each holds. Only a code with no row
+ * in the guide is looked for here (issue #1397, change 7).
+ */
+export const GUIDE_RULE_TABLES_ELSEWHERE: ReadonlyArray<{ file: string; heading: string }> = [
+  { file: 'docs/INGEST.md', heading: '#### Every finding code' },
+];
+
+/**
+ * The end of every failure line that names a rule: ` (see rigc guide <RULE>)` —
+ * that text, that spacing. The one writer of it; `failLine` and the finding
+ * line are the two callers that put it on a line.
+ */
+export function guidePointer(rule: string): string {
+  return ` (see ${GUIDE_BIN} guide ${rule})`;
+}
+
+/**
+ * The section a compile error points at (HQ's ruling on rig-c/parts#343): no compile error names a rule — 0 of
+ * the 463 throw sites carry a code, and §5.1's tables are keyed on the message — and §5.1 has no #### a thrower
+ * could name, so every one points at the section its row is in. When §5.1 grows #### families a thrower can
+ * name, this is where `§5.1.<k>` goes.
+ */
+export const COMPILE_ERROR_SECTION = '§5.1';
+
+/** A compile error as the CLI prints it: the prefix, the message, and the pointer to §5.1. */
+export function compileErrorLine(message: string): string {
+  return `rigc compile error: ${message}${guidePointer(COMPILE_ERROR_SECTION)}`;
+}
+
+/** A refusal naming its rule, unindented, as `guide` prints its own: `FAIL  <RULE>: <detail> (see rigc guide <RULE>)`. */
+export function refusalLine(rule: string, detail: string): string {
+  return `FAIL  ${rule}: ${detail}${guidePointer(rule)}`;
+}
+
+/** A failure line as every gate prints it: the report's two-space gutter, then the refusal line. */
+export function failLine(rule: string, detail: string): string {
+  return `  ${refusalLine(rule, detail)}`;
+}
+
+/** One heading outside a code fence: its level, its text, the line it is on (1-based) and its byte offset. */
+export interface GuideHeading {
+  level: number;
+  title: string;
+  line: number;
+  offset: number;
+}
+
+const ENCODER = new TextEncoder();
+
+/** A string's length in UTF-8 bytes — the size a reader's context pays for it. No `Buffer`: nothing here is Node's. */
+function utf8Length(text: string): number {
+  return ENCODER.encode(text).length;
+}
+
+/** A fenced block's opening, and the run of the same character that closes it. */
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/** Whether `line` closes the block `fence` opened: a run of the same character, at least as long, and nothing after it. */
+function closesFence(line: string, fence: string): boolean {
+  const run = /^ {0,3}(`+|~+)\s*$/.exec(line);
+  return run !== null && run[1][0] === fence[0] && run[1].length >= fence.length;
+}
+
+/**
+ * Every heading of a markdown text that is a heading — a `#` line inside a
+ * fenced block is a shell comment or an example, and AUTHORING carries
+ * hundreds of them.
+ */
+export function guideHeadings(text: string): GuideHeading[] {
+  const out: GuideHeading[] = [];
+  let fence: string | null = null;
+  let offset = 0;
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const opens = FENCE.exec(line);
+    if (opens !== null) {
+      if (fence === null) fence = opens[1];
+      else if (closesFence(line, fence)) fence = null;
+    } else if (fence === null) {
+      const heading = /^(#{1,6}) (.*)$/.exec(line);
+      if (heading !== null) out.push({ level: heading[1].length, title: heading[2].trim(), line: i + 1, offset });
+    }
+    offset += utf8Length(line) + 1;
+  }
+  return out;
+}
+
+/** One addressable section: its address, its heading, and the byte and line span it covers. */
+export interface GuideSection {
+  /** `5` or `5.2` — what follows `§`. */
+  address: string;
+  heading: GuideHeading;
+  /** Byte offsets into the text: the heading's line up to the next heading of its level or above. */
+  start: number;
+  end: number;
+  /** Line numbers, 1-based and inclusive. */
+  firstLine: number;
+  lastLine: number;
+}
+
+/** The number a `## ` heading carries before its first `.` — `5` for `5. Reading a failure`. */
+function chapterNumber(title: string): string | null {
+  const m = /^(\d+)\. /.exec(title);
+  return m === null ? null : m[1];
+}
+
+/**
+ * Every section `§<n>` and `§<n>.<m>` addresses, in the order the text gives
+ * them. `§<n>.<m>` is the m-th `###` under `## <n>.`, counted here.
+ */
+export function guideSections(text: string): GuideSection[] {
+  const heads = guideHeadings(text);
+  const total = utf8Length(text);
+  const lineCount = text.split('\n').length;
+  const span = (k: number): { start: number; end: number; firstLine: number; lastLine: number } => {
+    const h = heads[k];
+    const next = heads.slice(k + 1).find((x) => x.level <= h.level);
+    return {
+      start: h.offset,
+      end: next === undefined ? total : next.offset,
+      firstLine: h.line,
+      lastLine: next === undefined ? lineCount : next.line - 1,
+    };
+  };
+  const out: GuideSection[] = [];
+  let chapter: string | null = null;
+  let m = 0;
+  let sub = 0;
+  for (let k = 0; k < heads.length; k++) {
+    const h = heads[k];
+    if (h.level <= 2) {
+      chapter = h.level === 2 ? chapterNumber(h.title) : null;
+      m = 0;
+      sub = 0;
+      if (chapter !== null) out.push({ address: chapter, heading: h, ...span(k) });
+    } else if (h.level === 3 && chapter !== null) {
+      m++;
+      sub = 0;
+      out.push({ address: `${chapter}.${m}`, heading: h, ...span(k) });
+    } else if (h.level === 4 && chapter !== null && m > 0) {
+      // §<n>.<m>.<k>: the k-th #### under the m-th ### (HQ's ruling on rig-c/parts#343, S-A). A #### above the
+      // chapter's first ### belongs to no ###, so nothing addresses it.
+      sub++;
+      out.push({ address: `${chapter}.${m}.${sub}`, heading: h, ...span(k) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Every `###` and `####` whose written number is not the position it is counted
+ * at — the guide writes `### 5.2 …` and `#### 4.5.1 …`, and `§5.2` is the second
+ * `###` under `## 5.`, `§4.5.1` the first `####` under `§4.5`, so a heading
+ * inserted, moved or misnumbered would make the printed number lie about what
+ * `rigc guide` prints for it. Named by heading and line. A heading that writes
+ * no number is counted and not checked; one that writes a number its counted
+ * address is not — a lettered `10.6b`, a four-part `3.5.2.1` at `####` — is a
+ * fault, because nothing could address it by it.
+ */
+export function numberingFaults(text: string, file: string = GUIDE_FILE): string[] {
+  const faults: string[] = [];
+  for (const section of guideSections(text)) {
+    if (section.heading.level < 3) continue;
+    const written = /^(\d+(?:\.\d+)*[a-z]?(?:\.\d+)*)\s/.exec(section.heading.title);
+    if (written === null) continue;
+    if (written[1] !== section.address) {
+      const parts = section.address.split('.');
+      const level = '#'.repeat(section.heading.level);
+      const parent = section.heading.level === 3 ? `"## ${parts[0]}."` : `§${parts.slice(0, -1).join('.')}`;
+      faults.push(
+        `${file}:${section.heading.line} "${level} ${section.heading.title}" writes ${written[1]} and is the ` +
+          `${ordinal(Number(parts[parts.length - 1]))} ${level} under ${parent}, so ${GUIDE_BIN} guide §${section.address} prints it — ` +
+          `renumber it ${section.address}, or make it a ${level}# of the ${level} above it`,
+      );
+    }
+  }
+  return faults;
+}
+
+function ordinal(n: number): string {
+  const tens = n % 100;
+  const suffix = tens >= 11 && tens <= 13 ? 'th' : n % 10 === 1 ? 'st' : n % 10 === 2 ? 'nd' : n % 10 === 3 ? 'rd' : 'th';
+  return `${n}${suffix}`;
+}
+
+/** A rule row: the rule its first cell names, the row's text, where it is, and the table it sits in. */
+export interface GuideRow {
+  rule: string;
+  /** The row as written. */
+  text: string;
+  file: string;
+  line: number;
+  /** The table's header row and its separator, so the cells can be read by their column. */
+  header: string[];
+  /** The nearest heading above the row. */
+  heading: GuideHeading | null;
+  /** The anchor id the first cell opens with, or `null` when it carries none. */
+  anchor: string | null;
+}
+
+/** A rule name as a row spells it: upper-case words joined by `_`, a `<WORD>` standing for a family's member. */
+const RULE_CELL = /^\|\s*(?:<a id="([^"]*)"><\/a>)?`([A-Z][A-Z0-9]*(?:<[A-Z]+>)?(?:_(?:[A-Z0-9]+|<[A-Z]+>))*)`\s*\|/;
+
+/**
+ * Every rule row of a text. With `section` the rows are those under that
+ * heading, up to the next heading of its level or above — the one table of
+ * rules a document other than the guide holds; without it, every row of the
+ * text whose code carries an underscore (the module comment says why).
+ */
+export function guideRows(text: string, file: string, section?: string): GuideRow[] {
+  const heads = guideHeadings(text);
+  const lines = text.split('\n');
+  let from = 1;
+  let to = lines.length;
+  if (section !== undefined) {
+    const at = heads.findIndex((h) => `${'#'.repeat(h.level)} ${h.title}`.startsWith(section));
+    if (at < 0) return [];
+    const next = heads.slice(at + 1).find((h) => h.level <= heads[at].level);
+    from = heads[at].line + 1;
+    to = next === undefined ? lines.length : next.line - 1;
+  }
+  const out: GuideRow[] = [];
+  let fence: string | null = null;
+  let header: string[] = [];
+  let h = 0;
+  let heading: GuideHeading | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    while (h < heads.length && heads[h].line <= i + 1) heading = heads[h++];
+    const opens = FENCE.exec(line);
+    if (opens !== null) {
+      if (fence === null) fence = opens[1];
+      else if (closesFence(line, fence)) fence = null;
+      continue;
+    }
+    if (fence !== null) continue;
+    if (line.startsWith('|') && i + 1 < lines.length && /^\|\s*:?-{3,}/.test(lines[i + 1])) header = [line, lines[i + 1]];
+    if (i + 1 < from || i + 1 > to) continue;
+    const row = RULE_CELL.exec(line);
+    if (row === null) continue;
+    if (section === undefined && !row[2].includes('_')) continue;
+    out.push({ rule: row[2], text: line, file, line: i + 1, header, heading, anchor: row[1] ?? null });
+  }
+  return out;
+}
+
+/** Whether a family row's code (`ATTACHMENT_<TYPE>`) spells `rule`. */
+export function familySpells(family: string, rule: string): boolean {
+  if (!family.includes('<')) return false;
+  const pattern = family.split(/<[A-Z]+>/).map((part) => part.replace(/[^A-Z0-9_]/g, '')).join('[A-Z0-9]+');
+  return new RegExp(`^${pattern}$`).test(rule);
+}
+
+/** The documents `guide` reads, as their texts: the guide, and each other document a rule table lives in. */
+export interface GuideTexts {
+  guide: string;
+  /** By file, as `GUIDE_RULE_TABLES_ELSEWHERE` names them; a file that could not be read is absent. */
+  elsewhere: Readonly<Record<string, string>>;
+}
+
+/** Every rule row `guide` can print: the guide's, then each other document's table. */
+export function allRuleRows(texts: GuideTexts): GuideRow[] {
+  const rows = guideRows(texts.guide, GUIDE_FILE);
+  for (const table of GUIDE_RULE_TABLES_ELSEWHERE) {
+    const text = texts.elsewhere[table.file];
+    if (text !== undefined) rows.push(...guideRows(text, table.file, table.heading));
+  }
+  return rows;
+}
+
+/**
+ * The rows that answer for `rule`: its own rows, in the guide first; or, where
+ * it has none anywhere, the family rows that spell it. Empty when nothing does.
+ */
+export function rowsFor(rule: string, rows: readonly GuideRow[]): GuideRow[] {
+  const own = rows.filter((row) => row.rule === rule);
+  if (own.length > 0) return own;
+  return rows.filter((row) => familySpells(row.rule, rule));
+}
+
+/**
+ * The `n` known names nearest to `asked`, case aside: a name it is the start of
+ * (or, from three characters, a part of) first; then by edit distance less the
+ * prefix the two share, so `A00_MODEL_READ` is nearer `A00_MODEL_REGIONS_ON_PAGES`
+ * than a short name a few edits away; then by name.
+ */
+export function nearestNames(asked: string, known: readonly string[], n = 3): string[] {
+  const key = asked.toUpperCase();
+  const shared = (name: string): number => {
+    let k = 0;
+    while (k < key.length && k < name.length && key[k] === name[k]) k++;
+    return k;
+  };
+  const score = (name: string): number =>
+    name.toUpperCase().startsWith(key) || (key.length >= 3 && name.toUpperCase().includes(key)) ? -Infinity : editDistance(key, name.toUpperCase()) - shared(name.toUpperCase());
+  return [...new Set(known)]
+    .map((name) => ({ name, d: score(name) }))
+    .sort((a, b) => a.d - b.d || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .slice(0, n)
+    .map((x) => x.name);
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/**
+ * The two rules `guide` itself refuses by (HQ's ruling on rig-c/parts#343, the printed form): a name no row
+ * carries, and an address no section has. Each has its row in the guide, like every other rule a line can name.
+ */
+export const GUIDE_RULE_KNOWN = 'GUIDE_RULE_KNOWN';
+export const GUIDE_SECTION_KNOWN = 'GUIDE_SECTION_KNOWN';
+export const GUIDE_RULES: readonly string[] = [GUIDE_RULE_KNOWN, GUIDE_SECTION_KNOWN];
+
+/** What `guide` answers: the lines to print, or the refusal's rule and detail (stderr, exit 1). */
+export type GuideAnswer = { ok: true; lines: string[] } | { ok: false; rule: string; detail: string };
+
+function kb(bytes: number): string {
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+/** The `§` address of the section a line of the guide sits in — its deepest addressed heading; `null` outside every numbered section. */
+function addressOfLine(sections: readonly GuideSection[], line: number): string | null {
+  let best: GuideSection | null = null;
+  for (const s of sections) if (s.firstLine <= line && line <= s.lastLine && (best === null || s.heading.level > best.heading.level)) best = s;
+  return best === null ? null : best.address;
+}
+
+/** A section's children — the addresses one level below it, in the order the guide gives them; `null` is the guide itself. */
+function childrenOf(sections: readonly GuideSection[], address: string | null): GuideSection[] {
+  const depth = address === null ? 0 : address.split('.').length;
+  return sections.filter((s) => s.address.split('.').length === depth + 1 && (address === null || s.address.startsWith(`${address}.`)));
+}
+
+/**
+ * `rigc guide <RULE>` and `rigc guide §<n>[.<m>[.<k>]]`, over the texts as read, in the printed form HQ fixed for
+ * both packages on rig-c/parts#343:
+ *
+ * - a rule: per row, `docs/AUTHORING.md §<addr>, line <N> — under "<heading>"`, then the row verbatim;
+ * - a section: `docs/AUTHORING.md §<addr> "<title>", lines <a>–<b>, <X.X> KB`, then — when it has children — one
+ *   `§<addr>  <X.X KB>  <title>` line per child, then the section verbatim;
+ * - an unknown rule or section: a refusal by `GUIDE_RULE_KNOWN` / `GUIDE_SECTION_KNOWN`.
+ */
+export function guideAnswer(asked: string, texts: GuideTexts): GuideAnswer {
+  const sections = guideSections(texts.guide);
+  if (asked.startsWith('§')) {
+    const address = asked.slice(1);
+    const section = sections.find((s) => s.address === address);
+    if (section === undefined) {
+      // The deepest section the address names a prefix of, and its sections: §5.9 -> §5 and §5.1…§5.4.
+      const parts = address.split('.');
+      let deepest: GuideSection | null = null;
+      for (let n = parts.length - 1; n >= 1 && deepest === null; n--) deepest = sections.find((s) => s.address === parts.slice(0, n).join('.')) ?? null;
+      const kids = childrenOf(sections, deepest === null ? null : deepest.address).map((s) => `§${s.address}`);
+      const where = deepest === null ? `the guide itself, ${GUIDE_FILE}` : `§${deepest.address} "${deepest.heading.title}"`;
+      return {
+        ok: false,
+        rule: GUIDE_SECTION_KNOWN,
+        detail: `"${asked}" — no such section; the deepest that exists is ${where}, whose sections are: ${kids.length === 0 ? 'none' : kids.join(', ')}`,
+      };
+    }
+    const body = texts.guide.split('\n').slice(section.firstLine - 1, section.lastLine).join('\n').replace(/\n+$/, '');
+    const lines = [`${GUIDE_FILE} §${section.address} "${section.heading.title}", lines ${section.firstLine}–${section.lastLine}, ${kb(section.end - section.start)}`];
+    // A chapter lists its ###, a ### its #### — each with the address that prints it, its size and its title.
+    const subs = childrenOf(sections, section.address);
+    const wide = Math.max(0, ...subs.map((sub) => sub.address.length + 1));
+    const wideKb = Math.max(0, ...subs.map((sub) => kb(sub.end - sub.start).length));
+    for (const sub of subs) lines.push(`${`§${sub.address}`.padEnd(wide)}  ${kb(sub.end - sub.start).padStart(wideKb)}  ${sub.heading.title}`);
+    lines.push(body);
+    return { ok: true, lines };
+  }
+  const rows = allRuleRows(texts);
+  const found = rowsFor(asked, rows);
+  if (found.length === 0) {
+    return {
+      ok: false,
+      rule: GUIDE_RULE_KNOWN,
+      // The files actually searched, named (HQ on rig-c/parts#343): the guide, then each other document a rule table lives in.
+      detail: `"${asked}" — no row in ${[GUIDE_FILE, ...GUIDE_RULE_TABLES_ELSEWHERE.map((t) => t.file)].join(' or ')} names it; the nearest: ${nearestNames(asked, rows.map((r) => r.rule)).join(', ')}`,
+    };
+  }
+  const lines: string[] = [];
+  for (const row of found) {
+    const address = row.file === GUIDE_FILE ? addressOfLine(sections, row.line) : null;
+    const where = `${row.file}${address === null ? '' : ` §${address}`}, line ${row.line}`;
+    lines.push(`${where} — under "${row.heading === null ? '(no heading)' : row.heading.title}"`);
+    if (row.rule !== asked) lines.push(`${asked} has no row of its own; the row for the family ${row.rule}, which spells it, answers for it`);
+    lines.push(row.text);
+  }
+  return { ok: true, lines };
+}

package/src/ingest.ts

@@ -52,6 +52,7 @@ import {
   SPINE_VERSION,
 } from './compile.ts';
 import { CompileError } from './errors.ts';
+import { guidePointer } from './guide.ts';
 import { physicsDrives } from './core/constraints_physics.ts';
 import { CHANNELS_BY_KIND } from './timelines.ts';
 import {
@@ -149,6 +150,17 @@ export const INGEST_GUTTERS: Record<IngestFindingKind, string> = {
   lossy: 'LOSS',
 };
 
+/**
+ * One finding as `ingest` and `repack` print it: the gutter padded to one width
+ * so the codes line up, the code, where, the detail, and the pointer to the
+ * code's row (issue #1397) — the one writer of the line, so both commands print
+ * the same one.
+ */
+export function findingLine(finding: IngestFinding): string {
+  const width = Math.max(...Object.values(INGEST_GUTTERS).map((gutter) => gutter.length));
+  return `  ${INGEST_GUTTERS[finding.kind].padEnd(width)} ${finding.code}: ${finding.where} — ${finding.detail}${guidePointer(finding.code)}`;
+}
+
 export interface IngestFinding {
   /** Stable code, so a table can count them and a doc can name one. */
   code: string;

package/src/meshcompare.ts

@@ -66,7 +66,11 @@
  *   on every walk and stepped at the declared `dt` to each frame (the oracle's
  *   `stepSchedule` rule: from the last frame, steps of `dt` while before the
  *   next, then to it), the same steps for the reference and every candidate. A
- *   nonzero `warmupSteps` is refused, never run as zero.
+ *   nonzero `warmupSteps` is refused, never run as zero. The physics clock
+ *   moves by `physicsClockStep` of each step, the render's clock
+ *   (`PHYSICS_CLOCK_LEAD` in `src/core/raw.ts`, issue #1380), so a step
+ *   lasting a whole number of a constraint's steps takes them as exact
+ *   arithmetic does (`comparisonWalk`, issue #1389).
  *
  * ## What it never does
  *
@@ -106,8 +110,8 @@ import {
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
 import { uvCarriers, uvCarriersWith, type Carrier, type CarrierPlant } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
-import { poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
-import { sampleTime } from './core/animation.ts';
+import { physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
+import { sampleTime, type TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN } from './core/skins.ts';
 import { readVersion } from './package_meta.ts';
 import { hypot2 } from './numeric.ts';
@@ -187,7 +191,9 @@ export interface MotionComparisonInput {
  * Issue #1291's faults in carrying `motionAmplitude` into the setup measurement, for the `mesh-compare` suite's
  * negative controls: the amplitude not handed over; `null` handed over as the field left out; the field not validated
  * before the builds are read; `null` echoed for a field left out; and the load counted as a required row, so the
- * amplitude moves a verdict. `compareMeshesInMotion` plants none. Issue #1323 adds `CarrierPlant`
+ * amplitude moves a verdict. `compareMeshesInMotion` plants none. Issue #1389 adds `'frame-physics-clock'`: every
+ * build posed with the physics clock moved by the schedule's step itself, the walk before that issue
+ * (`comparisonWalk`). Issue #1323 adds `CarrierPlant`
  * (`src/meshcarriers.ts`): a fault in resolving a sample's several carriers, planted in every `uvCarriers` the
  * comparison reads.
  */
@@ -197,6 +203,7 @@ export type ComparePlant =
   | 'amplitude-unvalidated'
   | 'echo-when-unset'
   | 'amplitude-gates-acceptance'
+  | 'frame-physics-clock'
   | OverBoundPlant
   | CarrierPlant;
 
@@ -594,7 +601,37 @@ function drawnOf(pose: RawPose, ref: AttachmentRef): number[] | null {
   return row === undefined ? null : row.vertices;
 }
 
-function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames: readonly Planned[], walks: readonly Walk[]): Posed | { refused: string } {
+/**
+ * The walk every build of a comparison is posed on (issue #1389): `poseRawAnimationEach`, reset at the animation, the
+ * physics clock moved by `physicsClockStep` of each step — the render's clock (`src/core/raw.ts`). A walk time that
+ * ends on a whole number of a physics constraint's steps leaves zero time over in exact arithmetic and a few ulps
+ * either side of zero in doubles, so with the step itself as the clock the constraint took one step too few or one
+ * too many by rounding. Measured over the clock arithmetic on 300 durations as the core reads them (float32, as Spine
+ * does: n/12 s to 20 s and tenths to 8 s): at 12 fps and `dt` 1/12, the rate `@rig-c/parts` walks, 11,248 of 44,486
+ * grid updates sit on a tie against a 60 Hz constraint and the frame clock happens to resolve every one as exact
+ * arithmetic does, while against 30, 24 and 50 Hz it mis-steps 3,274, 3,350 and 3,160 of them; at 4 fps and `dt` 1/60
+ * it mis-steps 19,876 grid and 594 irr updates against 60 Hz. The render's clock mis-steps none of any, so no time
+ * that is not a tie came within its lead of a whole step. `clock: 'frame'` is that walk, the step itself — `ComparePlant`
+ * `'frame-physics-clock'` and `MQ178`'s planted red. With no physics constraint the clock is read by nothing, so every
+ * pose is the same either way (`MQ179`); with one, the lead moves the shown lag weight by about `2⁻³⁰` of the time
+ * walked even where no step moves: on `MQ179`'s spring at parts' rate and 60 Hz, one unit of a row's sixth decimal,
+ * which can move the worst sample to a neighbour that nearly ties it.
+ */
+export function comparisonWalk(doc: CompiledDocument, animation: string, deltas: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, clock: 'render' | 'frame' = 'render'): void {
+  poseRawAnimationEach(doc, animation, deltas, plant, 'animation', visit, clock === 'render' ? physicsClockStep : undefined);
+}
+
+/**
+ * The walks `schedule` plans over the model document `model`, in walk order, each with the steps every build is posed
+ * on — `planSchedule`'s, read for the `mesh-compare` suite's `MQ178`. Internal: merely exported, so not promised; it
+ * reads the schedule without the input checks `compareMeshesInMotion` runs first.
+ */
+export function comparisonWalks(schedule: MotionSchedule, model: string): Array<{ animation: string; phase: 'grid' | 'irr' | null; deltas: number[] }> {
+  const doc = readModel(model, 'the model document');
+  return planSchedule(schedule, doc, doc.constraints.filter((c) => c.kind === 'physics').length).walks.map((w) => ({ animation: w.animation, phase: w.phase, deltas: [...w.deltas] }));
+}
+
+function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames: readonly Planned[], walks: readonly Walk[], clock: 'render' | 'frame'): Posed | { refused: string } {
   try {
     const view = viewOf(doc, refs[0].skin);
     const setupPose = poseRawSetup(view);
@@ -612,12 +649,19 @@ function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames
         list.push(i);
         wanted.set(f.pose, list);
       });
-      poseRawAnimationEach(view, w.animation, w.deltas, {}, 'animation', (pose, index) => {
-        const at = wanted.get(index);
-        if (at === undefined) return;
-        const drawn = refs.map((r) => drawnOf(pose, r));
-        for (const i of at) out[i] = drawn;
-      });
+      comparisonWalk(
+        view,
+        w.animation,
+        w.deltas,
+        {},
+        (pose, index) => {
+          const at = wanted.get(index);
+          if (at === undefined) return;
+          const drawn = refs.map((r) => drawnOf(pose, r));
+          for (const i of at) out[i] = drawn;
+        },
+        clock,
+      );
     });
     return { setup, frames: out, setupBones };
   } catch (err) {
@@ -1003,11 +1047,12 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     const carriersOf = (uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> =>
       uvCarriersWith(uvs, triangles, samples, who, carrierPlant);
     const refCarriers = order.map((i, k) => carriersOf(reference.meshes[i].uvs, reference.meshes[i].triangles, samplesOf[k].samples, `reference "${reference.id}", attachment ${nameOf(refs[i])}`));
-    const posedRef = poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks);
+    const clock = plant === 'frame-physics-clock' ? 'frame' : 'render';
+    const posedRef = poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks, clock);
 
     motionOf = (b: Build, isReference: boolean) => {
       const carriers = isReference ? refCarriers : order.map((i, k) => carriersOf(b.meshes[i].uvs, b.meshes[i].triangles, samplesOf[k].samples, `candidate "${b.id}", attachment ${nameOf(refs[i])}`));
-      const posed = isReference ? posedRef : poseBuild(b.doc, order.map((i) => refs[i]), frames, walks);
+      const posed = isReference ? posedRef : poseBuild(b.doc, order.map((i) => refs[i]), frames, walks, clock);
       const built: Built[] = [];
       const perFrame: NonNullable<CandidateReport['perFrame']> = [];
       // Issue #1315: kept for a candidate only, and only when asked — a call without the field does none of this.

package/src/render_core.ts

@@ -30,7 +30,7 @@
  *   the same walk handing each pose over as it is posed (`CORE_RAW_WALK`), so
  *   one pose is held at a time. Since issue #1380 the physics clock — and
  *   nothing else — moves by `physicsClockStep(1/fps)` rather than by the step
- *   (`PHYSICS_CLOCK_LEAD` below), in both posers: `CR03` still holds the walk
+ *   (`PHYSICS_CLOCK_LEAD`, `./core/raw.ts`), in both posers: `CR03` still holds the walk
  *   under the step itself, and the loop-seam suite's `LS06` holds the two
  *   posers equal under the render's clock.
  * - **Vertices, triangles, bones, slot colours, draw order** are the raw
@@ -100,7 +100,7 @@ import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
@@ -369,61 +369,10 @@ export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: read
 export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep);
 
 /**
- * How much faster than the frames a render's physics clock runs: each frame
- * moves the skeleton's clock — the time a physics constraint integrates — by
- * `physicsClockStep(1 / fps)`, the frame's step and `2⁻³⁰` of it more, while
- * the animation is applied at the running sum of the frame steps as before
- * (issue #1380).
- *
- * ⭐ **Why a render's physics clock is not the frame clock.** A physics
- * constraint keeps the time it has not yet integrated (`remaining`), takes
- * whole steps of `1 / fps` (its own `fps`, 60 by default) while at least one
- * step remains, and shows `offset − lag·(1 − remaining / step)`, `lag` being
- * everything this update's steps moved (`src/core/constraints_physics.ts`,
- * *The step*). Whenever a frame lasts a whole number of physics steps — 12,
- * 20, 30 and 60 fps against 60 Hz, and every second frame at 24 — the time
- * left at the frame's end is zero in exact arithmetic, and in doubles it is
- * either a few ulps above zero or a few ulps short of one whole step. Which of
- * the two is decided by rounding, not by the motion: the shown weight is 1 or
- * 0, so the spring is drawn one frame late or on time, and it changes regime
- * on a single frame. Measured on the public trailer (`show`, 20 fps, 321
- * frames): every spring jumps at frames 5, 12, 45 and 188 — the four frames
- * that arithmetic alone predicts — and the loop's start (frame 80, on time)
- * and end (frame 320, a frame late, which is what exact arithmetic draws)
- * differ by 31.70 units of vertex and 10.37 of bone
- * while every keyed bone agrees to 1.3e-12. spine-core 4.3.13 stepped the
- * same way draws the same frames to the bit: this is the runtime under a
- * fixed offline step, not a defect of the core's port, which is why the fix
- * is the render's schedule and the physics is untouched.
- *
- * Running the clock `2⁻³⁰` fast puts the time left a little ABOVE every
- * whole number of steps instead of on it, by `2⁻³⁰ · t` after `t` seconds:
- * 1.5e-8 s at 16 s, against a rounding error of at most a few ulps of the
- * clock (3.6e-15 s at 16 s) — so every tie resolves the way exact arithmetic
- * resolves it, a step taken, and the shown weight sits at 1 − 9e-7 rather
- * than flipping. It stays below the smallest gap a step boundary can fall
- * into for 7.8e5 s even at 23 fps against 60 Hz (a gap of 1/1380 s), and a
- * physics `reset` key, which restarts the time left from zero, is resolved
- * the same way on every frame after it, because the lead is taken on every
- * frame rather than once (read off the clock arithmetic with a reset at frame
- * 100, 16 s at the five rates: no tie; no tree probe keys a reset under the
- * render's clock). A pose stays a function of its frame
- * index alone: the lead does not depend on how many frames are asked for.
- *
- * Rejected, measured over the same arithmetic (16 s at 12, 20, 24, 25, 30 and
- * 60 fps): the clock as `i / fps` rather than a running sum (90 frames still
- * flipped at 20 fps); a one-time lead of half a step (114 flipped at 24 fps,
- * where half a step lands on the other tie); a one-time lead of any size,
- * which a `reset` key cancels; and snapping `remaining` inside the physics,
- * which changes the runtime's physics rather than the render's schedule and
- * which spine-core's poser could not follow.
+ * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
+ * comparison (`./meshcompare.ts`, issue #1389) reads the same clock without this module's closure.
  */
-export const PHYSICS_CLOCK_LEAD = 2 ** -30;
-
-/** What one frame of `step` seconds moves a render's physics clock by — `PHYSICS_CLOCK_LEAD`; both posers step with it. */
-export function physicsClockStep(step: number): number {
-  return step + step * PHYSICS_CLOCK_LEAD;
-}
+export { PHYSICS_CLOCK_LEAD, physicsClockStep };
 
 /** What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`) and the raw walk (`RC44`). */
 export interface CorePoserPlants {