@rig-c/parts 1.15.0 → 1.17.0

package/src/config.ts

@@ -86,7 +86,7 @@
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RIG_SKIN_CONSTRAINT_KEYS, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
@@ -227,6 +227,15 @@ export interface SingleBone {
   parent: string;
   at: Point;
   tip?: Point;
+  /**
+   * What the bone takes from its parent's transform (issue #348): one of rig-c's
+   * own mode names (`RIG_BONE_INHERIT`, rig-c's `RigBone.inherit`), passed to
+   * rig.json as written. Absent, rig.json carries no `inherit` and the bone
+   * takes the parent's whole transform (rig-c's default, `normal`). A spelling
+   * outside rig-c's table is refused by name (`CONFIG_BONE_INHERIT`): the
+   * runtime would fold the first letter, and this loader folds and maps nothing.
+   */
+  inherit?: RigBoneInherit;
 }
 
 export interface ChainBones {
@@ -627,12 +636,37 @@ export interface ConfigConstraint {
   [field: string]: unknown;
 }
 
+/**
+ * One segment of a limb (issue #349): the part it makes, the part whose
+ * pixels it takes (`from`: a plan part or a cut's piece), and the one bone it
+ * rides with weight 1. Every segment after the first sits below a joint at
+ * its bone's origin: `joint` names it, `range` is the bend the joint may take
+ * from rest, `[min, max]` degrees (metadata: read by the stress readers, not
+ * by rig-c), and `cap` an image, relative to the config's directory, of the
+ * cap that overlaps the joint (`limbCaps` in `src/assemble.ts`).
+ */
+export interface LimbSegment {
+  part: string;
+  from: string;
+  bone: string;
+  joint?: string;
+  range?: [number, number];
+  cap?: string;
+}
+
+/** A limb (issue #349): its segments, upper first; each segment's bone is the child of the one before. */
+export interface Limb {
+  segments: LimbSegment[];
+}
+
 export interface CharacterConfig {
   key: string;
   note?: string;
   generation?: Generation;
   seethrough?: SeeThrough;
   assemble: Assemble;
+  /** Limbs cut at their joints (issue #349): absent, no part is cut at a joint and no byte of any output moves. */
+  limbs?: Record<string, Limb>;
   bones: BoneEntry[];
   meshes: Record<string, MeshSpec>;
   regions: Record<string, string>;
@@ -925,9 +959,12 @@ export interface AssembleConfig {
   seethrough: SeeThrough;
   assemble: Assemble;
   scene?: SceneSpec;
+  /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
+  limbs?: Record<string, Limb>;
+  bones?: BoneEntry[];
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -976,8 +1013,14 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   }
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
-    if ('assemble' in t) checkAssemble(c, t.assemble, door);
+    const made = 'assemble' in t ? checkAssemble(c, t.assemble, door) : { parts: [], patches: [], cuts: [] };
     if ('scene' in t) checkScene(c, t.scene);
+    // Issue #349: the limbs' joints are their bones' origins, so the bones are read with them, and only then.
+    if ('limbs' in t) {
+      if (!('bones' in t)) c.fail('CONFIG_FIELD_PRESENT', 'config.bones', 'is absent; config.limbs names bones, and each joint is its bone\'s origin, so assemble reads the bones with the limbs');
+      const names = 'bones' in t ? checkBones(c, t.bones) : null;
+      checkLimbs(c, t.limbs, made, names);
+    }
   }
   const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
@@ -1124,9 +1167,10 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
   const { parts, patches, cuts } = 'assemble' in t ? checkAssemble(c, t.assemble, 'full') : { parts: [], patches: [], cuts: [] };
   const names = 'bones' in t ? checkBones(c, t.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
+  const limbs = 'limbs' in t ? checkLimbs(c, t.limbs, { parts, patches, cuts }, 'bones' in t ? names : null) : null;
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
   if ('regions' in t) checkRegions(c, t.regions, names.bones);
-  if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions);
+  if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
@@ -1651,8 +1695,16 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
       }
       return;
     }
-    const b = c.object(at, entry, ['name', 'parent', 'at'], ['tip']);
+    const b = c.object(at, entry, ['name', 'parent', 'at'], ['tip', 'inherit']);
     if (b === null) return;
+    // Issue #348: rig-c's own mode names, as its table spells them; nothing is folded, mapped or defaulted.
+    if ('inherit' in b && c.string(`${at}.inherit`, b.inherit) && !(RIG_BONE_INHERIT as readonly string[]).includes(b.inherit)) {
+      c.fail(
+        'CONFIG_BONE_INHERIT',
+        `${at}.inherit`,
+        `is ${show(b.inherit)}; one of rig-c's inherit modes, spelled as its table spells them, is required — ${RIG_BONE_INHERIT.join(', ')} (rig-c's RigBone.inherit; nothing here folds a case or maps a name)`,
+      );
+    }
     if ('parent' in b && c.string(`${at}.parent`, b.parent) && !bones.has(b.parent)) {
       c.fail('CONFIG_NAME_RESOLVES', `${at}.parent`, `names "${b.parent}", which is not "${ROOT_BONE}" or a bone declared above it; parents come first`);
     }
@@ -2087,14 +2139,139 @@ function checkRegions(c: Check, v: Json, bones: Set<string>): void {
   }
 }
 
+/** What the loader read off `config.limbs` (issue #349): each limb part with its bone, and each part a limb takes, with the first limb taking it. */
+interface LimbNames {
+  parts: Map<string, { bone: string; at: string }>;
+  consumed: Map<string, string>;
+}
+
+/**
+ * `config.limbs` (issue #349): `{<limb>: {segments: [{part, from, bone}, {part,
+ * from, bone, joint, range?, cap?}, …]}}`, upper segment first. Refused field
+ * by field: `part` a new part name (`CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE`
+ * against the plan, the patches, the cuts and every other limb part); `from`
+ * a plan part or a cut's piece (`CONFIG_NAME_RESOLVES`), the segments of one
+ * limb that take one part consecutive (`CONFIG_LIMB_FROM_RUN`: the cut
+ * between them is a joint line, and a joint line has two sides); `bone` a
+ * declared bone, each segment's bone the child of the one before
+ * (`CONFIG_LIMB_BONES_CHAIN`: a bend is a rotation of the lower bone about
+ * the joint, its origin); the first segment has no joint, every other names
+ * one (`CONFIG_KEY_KNOWN`, `CONFIG_FIELD_PRESENT`); `range` two finite
+ * degrees `[min, max]` with `min <= 0 <= max` (`CONFIG_LIMB_RANGE`: the range
+ * is measured from rest, so rest is in it); `cap` a non-empty path. A limb
+ * has two segments or more. With `names` null (no `bones`), bones are not
+ * resolved. Returns the limb parts and the parts the limbs take.
+ */
+function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[]; cuts: string[] }, names: { bones: Set<string>; parents: Map<string, string> } | null): LimbNames {
+  const out: LimbNames = { parts: new Map(), consumed: new Map() };
+  if (!isPlainObject(v)) {
+    c.fail('CONFIG_FIELD_TYPE', 'config.limbs', `is ${show(v)}; an object of limb name -> {"segments": [...]} is required`);
+    return out;
+  }
+  const sources = new Set([...made.parts, ...made.cuts]);
+  const firstAt = new Map<string, string>();
+  for (const [limb, spec] of Object.entries(v)) {
+    const at = `config.limbs.${limb}`;
+    const o = c.object(at, spec, ['segments'], []);
+    if (o === null || !('segments' in o)) continue;
+    if (!Array.isArray(o.segments) || o.segments.length < 2) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.segments`, `is ${show(o.segments)}; an array of two segments or more, upper first, is required — a limb is cut at a joint, and a joint has a segment on each side`);
+      continue;
+    }
+    const segs = o.segments as Json[];
+    const froms: Array<string | null> = [];
+    const bones: Array<string | null> = [];
+    segs.forEach((entry, i) => {
+      const sat = `${at}.segments[${i}]`;
+      const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap']);
+      froms.push(null);
+      bones.push(null);
+      if (e === null) return;
+      // The upper segment sits below no joint; every other sits below one, which it names.
+      if (i === 0) {
+        for (const k of ['joint', 'range', 'cap'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
+      } else if (!('joint' in e)) c.fail('CONFIG_FIELD_PRESENT', `${sat}.joint`, 'is absent and required; a segment after the first sits below a joint, at its bone\'s origin, and names it');
+      if ('part' in e && c.string(`${sat}.part`, e.part)) {
+        const name = e.part;
+        if (!partNameOk(name)) c.fail('CONFIG_PART_NAME', `${sat}.part`, `names the part ${show(name)}; a part name is a file name, so it may not be empty, start with "." or hold a slash`);
+        else if (made.parts.includes(name) || made.patches.includes(name) || made.cuts.includes(name)) {
+          c.fail('CONFIG_PART_UNIQUE', `${sat}.part`, `names the part "${name}", which ${made.parts.includes(name) ? 'assemble.plan' : made.patches.includes(name) ? 'assemble.patches' : 'assemble.cuts'} already makes; a limb segment makes a part of its own`);
+        } else if (firstAt.has(name)) c.fail('CONFIG_PART_UNIQUE', `${sat}.part`, `names the part "${name}" again (first at ${firstAt.get(name)})`);
+        else {
+          firstAt.set(name, sat);
+          if ('bone' in e && typeof e.bone === 'string') out.parts.set(name, { bone: e.bone, at: `config.limbs.${limb} segment ${i}` });
+        }
+      }
+      if ('from' in e) {
+        if (typeof e.from !== 'string' || !sources.has(e.from)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${sat}.from`, `is ${show(e.from)}; a part named in assemble.plan or made by an assemble.cuts entry is required — the layer the segment's pixels are cut from`);
+        } else {
+          froms[i] = e.from;
+          if (!out.consumed.has(e.from)) out.consumed.set(e.from, limb);
+        }
+      }
+      if ('bone' in e && c.string(`${sat}.bone`, e.bone)) {
+        if (names !== null && !names.bones.has(e.bone)) c.fail('CONFIG_NAME_RESOLVES', `${sat}.bone`, `is "${e.bone}"; a bone config.bones declares is required (a chain's links are <chain>0, <chain>1, …)`);
+        else bones[i] = e.bone;
+      }
+      if ('joint' in e) c.string(`${sat}.joint`, e.joint);
+      if ('range' in e) {
+        const r = e.range;
+        const ok = Array.isArray(r) && r.length === 2 && r.every((n) => typeof n === 'number' && Number.isFinite(n));
+        if (!ok) c.fail('CONFIG_FIELD_TYPE', `${sat}.range`, `is ${show(r)}; [min, max], two finite numbers of degrees from rest, is required`);
+        else {
+          const [lo, hi] = r as [number, number];
+          if (!(lo <= 0 && 0 <= hi)) c.fail('CONFIG_LIMB_RANGE', `${sat}.range`, `is [${lo}, ${hi}]; min <= 0 <= max is required — the range is the bend from rest, and rest (0) is a pose the joint takes`);
+        }
+      }
+      if ('cap' in e && !(typeof e.cap === 'string' && e.cap !== '')) {
+        c.fail('CONFIG_FIELD_TYPE', `${sat}.cap`, `is ${show(e.cap)}; a non-empty path to a PNG is required, relative to the config's directory — the cap's image over the box assemble's limb line prints`);
+      }
+    });
+    froms.forEach((f, i) => {
+      if (f === null || i === 0 || froms[i - 1] === f) return;
+      const back = froms.slice(0, i - 1).lastIndexOf(f);
+      if (back >= 0) {
+        c.fail('CONFIG_LIMB_FROM_RUN', `${at}.segments[${i}].from`, `is "${f}", which segments[${back}] takes too with another part between them; the segments that take one part must be consecutive — the cut between two of them is the joint line, and it has two sides`);
+      }
+    });
+    if (names !== null) {
+      bones.forEach((b, i) => {
+        if (i === 0 || b === null || bones[i - 1] === null) return;
+        const parent = names.parents.get(b);
+        if (parent !== bones[i - 1]) {
+          c.fail('CONFIG_LIMB_BONES_CHAIN', `${at}.segments[${i}].bone`, `is "${b}", whose parent is ${parent === undefined ? 'not declared' : `"${parent}"`}; "${bones[i - 1]}", the bone of segments[${i - 1}], is required — the lower segment turns about the joint on a bone that hangs from the upper's`);
+        }
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Every plan part — and every cut's piece, which the caller lists with them —
  * is exactly one of a mesh or a region, every patch is a region, and every
  * mesh or region is one of those parts or a patch.
  */
-function checkCoverage(c: Check, parts: string[], patches: string[], meshes: Json, regions: Json): void {
+function checkCoverage(c: Check, made: string[], patches: string[], meshes: Json, regions: Json, limbs: LimbNames | null = null): void {
   const m = typeof meshes === 'object' && meshes !== null ? Object.keys(meshes) : [];
   const r = typeof regions === 'object' && regions !== null ? Object.keys(regions) : [];
+  // Issue #349: a part a limb takes is cut into the limb's parts and is not made itself; the limb's parts are.
+  const parts = limbs === null ? made : [...made.filter((n) => !limbs.consumed.has(n)), ...limbs.parts.keys()];
+  if (limbs !== null) {
+    for (const name of [...m, ...r]) {
+      const by = limbs.consumed.get(name);
+      if (by !== undefined) {
+        c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, `names "${name}", which config.limbs.${by} cuts into its parts at the joints, so no part of that name is made — attach the limb's parts instead`);
+      }
+    }
+    for (const [part, seg] of limbs.parts) {
+      const bone = isPlainObject(regions) ? regions[part] : undefined;
+      if (typeof bone === 'string' && bone !== seg.bone) {
+        c.fail('CONFIG_LIMB_BONE', `config.regions.${part}`, `is "${bone}"; "${part}" is ${seg.at}, which rides "${seg.bone}" with weight 1, so config.regions.${part} "${seg.bone}" is required`);
+      }
+    }
+  }
   for (const patch of patches) {
     if (m.includes(patch)) c.fail('CONFIG_PART_ATTACHED', `part "${patch}"`, `is an assemble.patches entry and has a meshes entry; a patch is a region — drop config.meshes.${patch} and name its bone in config.regions.${patch}`);
     else if (!r.includes(patch)) c.fail('CONFIG_PART_ATTACHED', `part "${patch}"`, `is an assemble.patches entry with no regions entry; a patch is a region, so config.regions.${patch} naming its bone is required`);
@@ -2106,8 +2283,8 @@ function checkCoverage(c: Check, parts: string[], patches: string[], meshes: Jso
     if (inM && inR) c.fail('CONFIG_PART_ATTACHED', `part "${part}"`, 'has both a meshes entry and a regions entry; exactly one is required');
   }
   for (const name of [...m, ...r]) {
-    if (!parts.includes(name) && !patches.includes(name)) {
-      c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, 'names a part that neither assemble.plan nor assemble.patches makes (nor an assemble.cuts entry)');
+    if (!parts.includes(name) && !patches.includes(name) && !(limbs?.consumed.has(name) ?? false)) {
+      c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, 'names a part that neither assemble.plan nor assemble.patches makes (nor an assemble.cuts entry, nor config.limbs)');
     }
   }
 }

package/src/errors.ts

@@ -23,6 +23,22 @@ export function problemLine(p: Problem): string {
   return `${p.code}: ${p.object} — ${p.detail}`;
 }
 
+/**
+ * The end of every FAIL line: the command that prints the guide's row for its
+ * rule (issue #343). This is the one place that writes it, so every line has the
+ * same form, and rig-c's lines have the same form with its own command. A line
+ * that quotes a rigc failure keeps rigc's pointer inside the quote, and this one
+ * goes after it.
+ */
+export function guidePointer(code: string): string {
+  return ` (see rig-parts guide ${code})`;
+}
+
+/** A refusal as it is printed: `  FAIL  RULE: object — detail (see rig-parts guide RULE)`. */
+export function failLine(p: Problem): string {
+  return `  FAIL  ${problemLine(p)}${guidePointer(p.code)}`;
+}
+
 export class PartsError extends Error {
   readonly problems: readonly Problem[];
 

package/src/guide.ts

@@ -0,0 +1,255 @@
+/**
+ * `rig-parts guide`: a slice of `docs/AUTHORING.md`, read at the moment of the
+ * call (issue #343).
+ *
+ * The guide is one file, and it is the only copy. An agent building a rig
+ * reads a failure line, `FAIL  RULE: object — detail (see rig-parts guide
+ * RULE)`, and needs the row that maps RULE to what has to change. It should
+ * not need the other 330 KB around that row. Every function here takes the
+ * guide's text and returns lines cut from it. Nothing is generated or kept
+ * apart from the file, so there is nothing to drift.
+ *
+ * Four readings, each defined on the text alone:
+ *
+ * - **A ledger table** is a Markdown table, outside a code fence, whose header's
+ *   first cell is exactly `rule` (a refusal or a warning) or `line` (a line
+ *   `check` prints). Other tables are not read.
+ * - **A row's names** are the backticked tokens in its first cell that are
+ *   rule names ({@link RULE_NAME}). A wildcard such as `PARTS_*` names
+ *   nothing. Each name sits on exactly one row in the whole guide; the
+ *   selftest's `TY16` holds that against every name the source can print.
+ * - **A row's anchors** are the `<a id="NAME"></a>` tags at the start of its
+ *   first cell, one per name. github.com keeps them as `user-content-<name>`,
+ *   and its script lowercases a link's fragment before it looks one up, so
+ *   `AUTHORING.md#NAME` lands on the row.
+ * - **`§n`** is the `## n.` heading and everything up to the next `##`.
+ *   **`§n.m`** is the m-th `###` under it, and **`§n.m.k`** the k-th `####`
+ *   under that, each counted at read time, up to the next heading of its level
+ *   or above. The guide's headings carry no number. `guide §n` and `guide
+ *   §n.m` print the numbers they counted beside each child's size.
+ *
+ * A refusal and the bar it enforces are two names, each with its own row:
+ * `CHECK_<LINE>` in a `rule` table, `<LINE>` in a `line` table. `guide` prints
+ * the asked name's row first, then `paired with <OTHER>:` and the other one's.
+ *
+ * The printed form is the one HQ settled for both packages on issue #343:
+ * `docs/AUTHORING.md §<addr>, line <N> — under "<heading>"` over each row;
+ * `docs/AUTHORING.md §<addr> "<title>", lines <a>–<b>, <X.X> KB` over a
+ * section, its children listed beneath in rig-c's columns; an unknown name or
+ * section one coded FAIL line on stderr, with rig-c's three-name ranking.
+ */
+import type { Problem } from './errors.ts';
+
+/** The guide's path inside the package, beside `cli.ts`. */
+export const GUIDE_DOC = 'docs/AUTHORING.md';
+
+/** A rule name: upper-case words joined by underscores (`USAGE` and `CHECK_LOOP_CLOSES` alike). */
+export const RULE_NAME = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
+
+/** How many of the nearest names an unknown name's refusal lists (the form shared with rig-c). */
+export const NEAREST_LISTED = 3;
+
+/** The two header words that make a table a ledger table, and what its rows are. */
+export const LEDGER_HEADS = ['rule', 'line'] as const;
+export type LedgerKind = (typeof LEDGER_HEADS)[number];
+
+/** A `##` section, a `###` or a `####`: its number, its title, its lines (1-based, end exclusive) and its size. */
+export interface GuideSection {
+  /** `"6"` for `## 6.`, `"6.3"` for the third `###` under it, `"3.6.1"` for the first `####` under §3.6. */
+  number: string;
+  /** The heading's text as written (a `##` keeps its `n. `). */
+  title: string;
+  start: number;
+  end: number;
+  /** UTF-8 bytes from the heading's line to the next heading of its level or above, each line with its newline. */
+  bytes: number;
+}
+
+/** One ledger row. */
+export interface LedgerRow {
+  kind: LedgerKind;
+  /** The row's line, 1-based. */
+  line: number;
+  /** The table's header line and its separator line, as written. */
+  header: [string, string];
+  /** The row as written. */
+  text: string;
+  /** The rule names in the first cell, in the order written. */
+  names: string[];
+  /** The ids of the `<a id="…"></a>` tags at the start of the first cell, in order. */
+  anchors: string[];
+  /** The deepest numbered section the row sits in (`§n`, `§n.m` or `§n.m.k`). */
+  section: GuideSection | null;
+  /** The nearest heading above the row, its text as written. */
+  heading: string;
+}
+
+function utf8Bytes(s: string): number {
+  return new TextEncoder().encode(s).length;
+}
+
+/** Each line, with whether it sits inside a code fence (a fence's own lines count as inside). */
+function fenced(lines: readonly string[]): boolean[] {
+  let inside = false;
+  return lines.map((l) => {
+    if (l.startsWith('```')) {
+      inside = !inside;
+      return true;
+    }
+    return inside;
+  });
+}
+
+/** Every `## n.` section, every `###` under one, and every `####` under those, numbered as {@link GuideSection} says. */
+export function guideSections(text: string): GuideSection[] {
+  const lines = text.split('\n');
+  const inFence = fenced(lines);
+  const heads: Array<{ level: number; title: string; line: number }> = [];
+  lines.forEach((l, i) => {
+    const h = inFence[i] ? null : /^(#{1,6}) (.*)$/.exec(l);
+    if (h !== null) heads.push({ level: h[1].length, title: h[2], line: i + 1 });
+  });
+  const out: GuideSection[] = [];
+  const counts = [0, 0, 0];
+  let chapter: string | null = null;
+  heads.forEach((h, k) => {
+    if (h.level <= 2) {
+      chapter = h.level === 2 ? (/^(\d+)\. /.exec(h.title)?.[1] ?? null) : null;
+      counts.fill(0);
+    } else if (h.level === 3) {
+      counts[1]++;
+      counts[2] = 0;
+    } else if (h.level === 4) counts[2]++;
+    if (chapter === null || h.level > 4 || (h.level === 4 && counts[1] === 0)) return;
+    const number = h.level === 2 ? chapter : h.level === 3 ? `${chapter}.${counts[1]}` : `${chapter}.${counts[1]}.${counts[2]}`;
+    const next = heads.slice(k + 1).find((x) => x.level <= h.level);
+    const end = next === undefined ? lines.length + 1 : next.line;
+    const title = h.title;
+    const body = lines.slice(h.line - 1, end - 1).join('\n');
+    out.push({ number, title, start: h.line, end, bytes: utf8Bytes(body) + (next === undefined ? 0 : 1) });
+  });
+  return out;
+}
+
+/** The ledger rows, in the order written. */
+export function ledgerRows(text: string): LedgerRow[] {
+  const lines = text.split('\n');
+  const inFence = fenced(lines);
+  const sections = guideSections(text);
+  const rows: LedgerRow[] = [];
+  let heading = '';
+  let header: [string, string] | null = null;
+  let kind: LedgerKind | null = null;
+  let inTable = false;
+  lines.forEach((l, i) => {
+    if (!inFence[i] && /^#{1,6} /.test(l)) heading = l.replace(/^#{1,6} /, '');
+    if (inFence[i] || !l.startsWith('|')) {
+      inTable = false;
+      return;
+    }
+    const first = (l.split('|')[1] ?? '').trim();
+    if (!inTable) {
+      inTable = true;
+      kind = (LEDGER_HEADS as readonly string[]).includes(first) ? (first as LedgerKind) : null;
+      header = [l, lines[i + 1] ?? ''];
+      return;
+    }
+    if (kind === null || header === null || /^:?-+:?$/.test(first)) return;
+    const names = [...first.matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter((t) => RULE_NAME.test(t));
+    if (names.length === 0) return;
+    const lead = /^((?:<a id="[^"]*"><\/a>)*)/.exec(first)?.[1] ?? '';
+    const anchors = [...lead.matchAll(/<a id="([^"]*)"><\/a>/g)].map((x) => x[1]);
+    const line = i + 1;
+    const holding = sections.filter((s) => s.start <= line && line < s.end).sort((a, b) => b.number.split('.').length - a.number.split('.').length);
+    rows.push({ kind, line, header, text: l, names, anchors, section: holding[0] ?? null, heading });
+  });
+  return rows;
+}
+
+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 {@link NEAREST_LISTED} names of `known` nearest `asked`, case aside — rig-c's ranking, the one the shared form
+ * fixes: a name `asked` is the start of (or, from three characters, a part of) first; then by edit distance less the
+ * prefix the two share; then by name. A list, never a substitute.
+ */
+export function nearestNames(known: readonly string[], asked: string): 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 => {
+    const up = name.toUpperCase();
+    return up.startsWith(key) || (key.length >= 3 && up.includes(key)) ? -Infinity : editDistance(key, up) - shared(up);
+  };
+  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, NEAREST_LISTED)
+    .map((x) => x.name);
+}
+
+/** A size as the shared form prints it: KB to one decimal. */
+export function kb(bytes: number): string {
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+/** One row's block: where it is, then the row as written. */
+function rowBlock(row: LedgerRow): string[] {
+  return [`${GUIDE_DOC}${row.section === null ? '' : ` §${row.section.number}`}, line ${row.line} — under "${row.heading}"`, row.text];
+}
+
+/** The other half of a refusal–bar pair: `CHECK_<LINE>` and `<LINE>`, each when the guide has its row. */
+function pairOf(name: string, rows: readonly LedgerRow[]): { row: LedgerRow; name: string } | null {
+  const other = name.startsWith('CHECK_') ? name.slice('CHECK_'.length) : `CHECK_${name}`;
+  const want: LedgerKind = name.startsWith('CHECK_') ? 'line' : 'rule';
+  const row = rows.find((r) => r.kind === want && r.names.includes(other));
+  return row === undefined ? null : { row, name: other };
+}
+
+/** What `guide` answers: the lines to print, or the refusal. */
+export type GuideAnswer = { lines: string[] } | { problem: Problem };
+
+/** `guide <RULE>`: the row naming it, then `paired with <OTHER>:` and its pair's; or `GUIDE_RULE_KNOWN` with the nearest names. */
+export function guideRule(text: string, name: string): GuideAnswer {
+  const rows = ledgerRows(text);
+  const own = rows.find((r) => r.names.includes(name));
+  if (own === undefined) {
+    return { problem: { code: 'GUIDE_RULE_KNOWN', object: `"${name}"`, detail: `no row in ${GUIDE_DOC} names it; the nearest: ${nearestNames(rows.flatMap((r) => r.names), name).join(', ')}` } };
+  }
+  const pair = pairOf(name, rows);
+  return { lines: [...rowBlock(own), ...(pair === null ? [] : [`paired with ${pair.name}:`, ...rowBlock(pair.row)])] };
+}
+
+/** `guide §n`, `§n.m` or `§n.m.k`: a line naming the slice, its children's listing when it has children, then the slice. */
+export function guideSection(text: string, ask: string): GuideAnswer {
+  const sections = guideSections(text);
+  const depth = (s: GuideSection): number => s.number.split('.').length;
+  const childrenOf = (n: string | null): GuideSection[] => sections.filter((s) => (n === null ? depth(s) === 1 : s.number.startsWith(`${n}.`) && depth(s) === n.split('.').length + 1));
+  const m = /^§(\d+(?:\.\d+){0,2})$/.exec(ask);
+  const hit = m === null ? undefined : sections.find((s) => s.number === m[1]);
+  if (hit === undefined) {
+    // The deepest address the asked one shares, and what it holds: never a section put in its place.
+    const asked = m === null ? [] : m[1].split('.');
+    let parent: GuideSection | undefined;
+    for (let d = asked.length - 1; d >= 1 && parent === undefined; d--) parent = sections.find((s) => s.number === asked.slice(0, d).join('.'));
+    const kids = childrenOf(parent?.number ?? null);
+    const list = kids.length === 0 ? 'none' : kids.map((s) => `§${s.number}`).join(', ');
+    const deepest = parent === undefined ? `the guide itself, ${GUIDE_DOC}` : `§${parent.number} "${parent.title}"`;
+    return { problem: { code: 'GUIDE_SECTION_KNOWN', object: `"${ask}"`, detail: `no such section; the deepest that exists is ${deepest}, whose sections are: ${list}` } };
+  }
+  const lines = text.split('\n');
+  const head = [`${GUIDE_DOC} §${hit.number} "${hit.title}", lines ${hit.start}–${hit.end - 1}, ${kb(hit.bytes)}`];
+  for (const s of childrenOf(hit.number)) head.push(`§${s.number.padEnd(6)} ${kb(s.bytes).padStart(9)}  ${s.title}`);
+  return { lines: [...head, '', lines.slice(hit.start - 1, hit.end - 1).join('\n').replace(/\n+$/, '')] };
+}