@protoboardai/ext-docs 0.0.0-stage → 0.2.1

package/lib/templates/flow.js

@@ -0,0 +1,131 @@
+/*
+ * Paginator for uhd-tech-docs documents (runs once in headless Chrome at
+ * build time; the saved HTML is already paginated, so this script is removed).
+ *
+ * Blocks in #flow are poured into A4 page frames cloned from #page-template:
+ *   data-page="cover|full"   the block is a whole page of its own
+ *   data-break="before"      start a new page before the block
+ *   .sec / .sub / .keep-next  kept with the following block
+ *   table.split              may split between rows (header repeated, "continued")
+ * Pages whose body still overflows are marked .overflow (the verifier fails them).
+ *
+ * It measures only once every declared font face and every image has loaded:
+ * measuring with a fallback font gives other page breaks, so the same
+ * document would paginate differently on a busy machine.
+ */
+function flowPages() {
+  const tpl = document.getElementById("page-template");
+  const pagesEl = document.getElementById("pages");
+  const flow = document.getElementById("flow");
+  const pages = [];
+  let body = null;
+
+  function newPage(kind) {
+    const page = tpl.content.firstElementChild.cloneNode(true);
+    if (kind) page.classList.add(kind);
+    pagesEl.appendChild(page);
+    pages.push(page);
+    body = page.querySelector(".pg-body");
+    return page;
+  }
+  const overflows = () => body.scrollHeight > body.clientHeight + 1;
+  const isKeepNext = (el) => el && (el.matches(".sec, .sub, .keep-next") || el.dataset.keepNext === "1");
+
+  function moveTrailingHeadings() {
+    const moved = [];
+    while (body.lastElementChild && isKeepNext(body.lastElementChild) && body.children.length > 1) {
+      moved.unshift(body.lastElementChild);
+      body.removeChild(body.lastElementChild);
+    }
+    return moved;
+  }
+
+  function splitTable(block) {
+    // block is (or wraps) table.split; move rows to a continuation until the page fits
+    const table = block.matches("table.split") ? block : block.querySelector("table.split");
+    if (!table) return null;
+    const rows = [...table.tBodies[0].rows];
+    if (rows.length < 4) return null;
+    const cont = block.cloneNode(true);
+    const ctable = cont.matches("table.split") ? cont : cont.querySelector("table.split");
+    ctable.tBodies[0].innerHTML = "";
+    cont.querySelectorAll(".cap, figcaption").forEach((c) => c.remove());
+    cont.classList.add("continued");
+    let moved = 0;
+    while (overflows() && table.tBodies[0].rows.length > 2) {
+      const last = table.tBodies[0].rows[table.tBodies[0].rows.length - 1];
+      ctable.tBodies[0].insertBefore(last, ctable.tBodies[0].firstChild);
+      moved++;
+    }
+    // avoid orphaned group headings at the bottom
+    const lastRow = table.tBodies[0].rows[table.tBodies[0].rows.length - 1];
+    if (lastRow && lastRow.classList.contains("group") && table.tBodies[0].rows.length > 1) {
+      ctable.tBodies[0].insertBefore(lastRow, ctable.tBodies[0].firstChild);
+      moved++;
+    }
+    if (overflows() || table.tBodies[0].rows.length < 2) {
+      // could not fit even two rows: give the rows back and move the whole block
+      while (ctable.tBodies[0].rows.length) table.tBodies[0].appendChild(ctable.tBodies[0].rows[0]);
+      return null;
+    }
+    return moved ? cont : null;
+  }
+
+  function place(block) {
+    if (!body) newPage();
+    if (block.dataset.page) {
+      if (body.children.length) newPage(block.dataset.page);
+      else pages[pages.length - 1].classList.add(block.dataset.page);
+      body.appendChild(block);
+      if (overflows()) pages[pages.length - 1].classList.add("overflow");
+      body = null;
+      return;
+    }
+    if (block.dataset.break === "before" && body.children.length) newPage();
+    body.appendChild(block);
+    if (!overflows()) return;
+    const cont = splitTable(block);
+    if (cont) {
+      newPage();
+      place(cont);
+      return;
+    }
+    if (body.children.length === 1) {
+      pages[pages.length - 1].classList.add("overflow");
+      return;
+    }
+    body.removeChild(block);
+    const carry = moveTrailingHeadings();
+    newPage();
+    for (const c of carry) body.appendChild(c);
+    place(block);
+  }
+
+  const blocks = [...flow.children];
+  for (const b of blocks) place(b);
+  flow.remove();
+
+  // page numbers, table of contents
+  const total = pages.length;
+  pages.forEach((p, i) => {
+    const n = p.querySelector(".pg-num");
+    if (n) n.textContent = `${String(i + 1).padStart(2, "0")} / ${String(total).padStart(2, "0")}`;
+    p.dataset.page = String(i + 1);
+    if (p.querySelector(".pg-body").scrollHeight > p.querySelector(".pg-body").clientHeight + 1) p.classList.add("overflow");
+  });
+  document.querySelectorAll("ol.toc").forEach((toc) => {
+    const items = [];
+    pages.forEach((p, i) => p.querySelectorAll("h1.sec, .step-head h2").forEach((h) => items.push({ t: h.dataset.toc || h.textContent.trim(), n: h.dataset.num || "", page: i + 1 })));
+    toc.innerHTML = items
+      .map((it) => `<li><span class="toc-n">${it.n}</span><span class="toc-t">${it.t}</span><span class="toc-dots"></span><span class="toc-p">${String(it.page).padStart(2, "0")}</span></li>`)
+      .join("");
+  });
+  document.getElementById("page-template").remove();
+  document.body.dataset.pages = String(total);
+  window.__flowDone = true;
+}
+
+Promise.all([...document.fonts].map((f) => f.load().catch(() => null)))
+  .then(() => document.fonts.ready)
+  .then(() => Promise.all([...document.images].map((i) => (i.complete ? 0 : new Promise((r) => { i.onload = i.onerror = r; })))))
+  .then(flowPages);

package/lib/testdata.ts

@@ -0,0 +1,85 @@
+/**
+ * Test data for documents: `docs/test-data/<test-id>.json` in the project.
+ *
+ * One file per test id. `status` is "standin" (generated from the model by
+ * a stand-in recipe, drawn with a STAND-IN watermark) or "measured" (real
+ * results). The stand-in generator never overwrites a measured file, so
+ * dropping a measured file in place of a stand-in swaps it into every
+ * document on the next build. Schema: the uhd-tech-docs skill's templates/test-data.schema.json.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+
+export interface TestColumn {
+  id: string;
+  label: string;
+  unit: string;
+}
+
+export interface TestData {
+  $schema?: string;
+  id: string;
+  title: string;
+  status: "standin" | "measured";
+  subject: { system: string; modules?: string[] };
+  /** Test conditions, each with a unit ("" for none). */
+  conditions: { name: string; value: number | string; unit: string }[];
+  provenance: {
+    method: string;
+    /** Model queries the stand-in was derived from (values.ts syntax). */
+    derivedFrom?: string[];
+    assumptions?: string[];
+    generator?: string;
+    generatedAt?: string;
+    /** Measured data: who, when, with what. */
+    operator?: string;
+    date?: string;
+    instruments?: string[];
+    rawFiles?: string[];
+  };
+  columns: TestColumn[];
+  rows: (number | string)[][];
+  summary: { id: string; label: string; value: number | string; unit: string }[];
+  /** Project-relative path, set when loaded. */
+  file?: string;
+}
+
+export function validateTestData(t: any, file: string): string[] {
+  const errs: string[] = [];
+  const need = (cond: boolean, msg: string) => cond || errs.push(`${file}: ${msg}`);
+  need(typeof t.id === "string" && t.id.length > 0, "id missing");
+  need(file.endsWith(`${t.id}.json`), `id "${t.id}" does not match the file name`);
+  need(t.status === "standin" || t.status === "measured", `status must be "standin" or "measured"`);
+  need(typeof t.title === "string", "title missing");
+  need(t.subject && typeof t.subject.system === "string", "subject.system missing");
+  need(Array.isArray(t.conditions) && t.conditions.every((c: any) => c.name && "value" in c && typeof c.unit === "string"), "conditions[] need name, value, unit");
+  need(t.provenance && typeof t.provenance.method === "string", "provenance.method missing");
+  if (t.status === "measured") need(Boolean(t.provenance?.date && (t.provenance?.operator || t.provenance?.instruments?.length)), "measured data needs provenance.date and operator or instruments");
+  need(Array.isArray(t.columns) && t.columns.every((c: any) => c.id && c.label && typeof c.unit === "string"), "columns[] need id, label, unit");
+  need(Array.isArray(t.rows) && t.rows.every((r: any) => Array.isArray(r) && r.length === t.columns?.length), "every row needs one value per column");
+  need(Array.isArray(t.summary) && t.summary.every((s: any) => s.id && "value" in s && typeof s.unit === "string"), "summary[] need id, value, unit");
+  for (const r of t.rows ?? []) for (const v of r) if (typeof v === "number" && !Number.isFinite(v)) errs.push(`${file}: non-finite value in rows`);
+  return errs;
+}
+
+/** `absDocs`/`docsDir`: the documents folder, absolute and project-relative. */
+export function loadTestData(absDocs: string, docsDir: string): { tests: Map<string, TestData>; errors: string[] } {
+  const dir = join(absDocs, "test-data");
+  const tests = new Map<string, TestData>();
+  const errors: string[] = [];
+  if (!existsSync(dir)) return { tests, errors };
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort()) {
+    const t = JSON.parse(readFileSync(join(dir, f), "utf8"));
+    const errs = validateTestData(t, f);
+    errors.push(...errs);
+    if (!errs.length) tests.set(t.id, { ...t, file: `${docsDir}/test-data/${f}` });
+  }
+  return { tests, errors };
+}
+
+/** Column values by id. */
+export function column(t: TestData, id: string): number[] {
+  const i = t.columns.findIndex((c) => c.id === id);
+  if (i < 0) throw new Error(`${t.id}: no column ${id}`);
+  return t.rows.map((r) => Number(r[i]));
+}

package/lib/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Per-system documentation config: `<system>/docs/docspec.ts` default-exports
+ * a DocConfig. It says how to *present* the model (step order, cameras,
+ * which parameters are "key"), never what the values are: every value in a
+ * document is a query into the model (see values.ts).
+ */
+import type { Mat4 } from "@deltarobotics/uhd";
+
+export type Vec = [number, number, number];
+
+export interface CameraSpec {
+  /** Direction from the target toward the camera (world, Z up). */
+  dir?: number[];
+  up?: number[];
+  margin?: number;
+  shiftX?: number;
+  shiftY?: number;
+}
+
+export interface StepGroupSpec {
+  /** Stable id, used in file names. */
+  id: string;
+  /** Verb-phrase title, e.g. "Mount the motors". */
+  title: string;
+  /** Mate link ids (as in assemble().mates[].linkId) covered by this step; `*` wildcards allowed. */
+  mates?: string[];
+  /** Wiring link ids (wiringChecklist linkId, with the sub-assembly prefix, e.g. "stack/fc_esc_cable"); wildcards allowed. */
+  wiring?: string[];
+  /** Instance paths placed in this step without a mate (placement hints, strapped parts). */
+  place?: string[];
+  /**
+   * Hand-written actions done first in the step, for work the model does not
+   * carry as an instance or a mate (a printed part of an enclosure fitted
+   * before what covers it, such as a button plunger). Value queries in
+   * {{…}} as in notes. The generated actions follow.
+   */
+  before?: string[];
+  /**
+   * Actions the model cannot generate, appended after the step's generated ones (the guide's list and the
+   * release's work order): a fold, a part laid in place last.
+   */
+  actions?: string[];
+  /** Presentation notes shown under the step (tips / cautions). Model-derived notes are added automatically. */
+  notes?: { kind: "tip" | "caution" | "warning"; text: string }[];
+  camera?: CameraSpec;
+  /** Explode distance for this step (mm). */
+  explode?: number;
+  /** Instances drawn as context from this step on even when not yet assembled (e.g. hidden until later). */
+  hideContext?: string[];
+  /** Figure style: exploded assembly (default) or a wiring figure. */
+  figure?: "assembly" | "wiring" | "none";
+  /**
+   * "test": done only after the unit's bench test and configuration (a
+   * battery strapped on for use). The Manufacturing Package's work order runs
+   * the test before such steps and a final check after them. Steps that fit
+   * propellers are treated this way without the flag.
+   */
+  after?: "test";
+}
+
+export interface KeySpec {
+  label: string;
+  /** Value query (values.ts). */
+  q: string;
+  /** Format options (format.ts). */
+  f?: string;
+  sub?: string;
+}
+
+export interface DocConfig {
+  title?: string;
+  subtitle?: string;
+  docId?: string;
+  revision?: string;
+  /** Root instance path for assemble() (default []). */
+  root?: string[];
+  /** Placements for modules no mate reaches (strapped/free), from model constants. */
+  placementHints?: { path: string[]; matrix: Mat4; note: string }[];
+  /** Default iso camera for the system. */
+  camera?: CameraSpec;
+  datasheet?: {
+    keyFigures?: KeySpec[];
+    specGroups?: { title: string; rows: KeySpec[] }[];
+    /** Interfaces to call out on the mechanical figure: "<instance path>.<interface id>". */
+    mechanicalCallouts?: string[];
+    /** Module whose pinout / interface allocation is tabulated (instance path). */
+    hub?: string;
+    /**
+     * Draw the bodies placed by placement hints on the cover (default false: a
+     * strapped battery is left off). True for parts held inside an enclosure.
+     */
+    heroHints?: boolean;
+    /**
+     * The Mechanical section's envelope table and figure captions. Omitted: the
+     * multirotor recipe (wheelbase, arm spacing, plates, props, motors),
+     * dimensioned on the drawings.
+     */
+    envelope?: { rows: KeySpec[]; note?: string; topCaption?: string; sideCaption?: string };
+    /**
+     * Performance figures as model queries, for a system whose parts state no performance table (not a
+     * multirotor): a summary table and bar charts (each item a query; `refs` draw target lines).
+     */
+    performance?: {
+      title?: string;
+      rows?: KeySpec[];
+      note?: string;
+      charts?: { title: string; y: string; unit: string; items: { label: string; q: string }[]; refs?: { label: string; q: string }[]; caption?: string; decimals?: number }[];
+    };
+  };
+  assembly?: {
+    steps: StepGroupSpec[];
+    explode?: number;
+    /** Instance path prefixes never drawn in step figures (e.g. props until their step). */
+    lateParts?: string[];
+  };
+  testData?: {
+    /** Stand-in recipe: a module name under lib/standins/ of @protoboardai/ext-docs ("multirotor"). */
+    standins?: string;
+  };
+}

package/lib/values.ts

@@ -0,0 +1,309 @@
+/**
+ * Value queries: every number or fact a document shows is a query string,
+ * resolved against the live UHD model at build time and again at verify
+ * time. Nothing is typed into a document by hand.
+ *
+ *   def:<moduleId>:<path>     a field of a module definition
+ *       def:dolphinrc-f405-v3-flight-controller:interfaces[id=bec_5v].parameters[id=voltage].value
+ *       def:cnhl-black-series-1100mah-6s-100c:domains[domain=mechanical].weight_g
+ *   inst:<instance path>:<path>   the same, addressed by instance (stack/fc, arm_fl/motor)
+ *   sys:<path>                system-level results: checks, bom, assembly, wiring, scenarios
+ *       sys:checks.diagnostics[rule=propulsion_current].details.totalPeak
+ *   derived:<name>            a named derivation (derived.ts) with its inputs listed
+ *   derived:<name>(a,b)       a parameterised derivation, e.g. derived:frameDistance(frame.motor_mount_fl,frame.motor_mount_fr)
+ *   ver:<partId>:<path>       the part's committed verification record (verification.json)
+ *   test:<test-id>:<path>     a test-data file (docs/test-data/<test-id>.json); rows[i][j] takes columns[j].unit
+ *
+ * Paths: `.key`, `[n]`, `[key=value]` (first match), `.length`.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join, relative } from "path";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { bodyKey } from "@deltarobotics/uhd";
+import type { SystemCheckResult } from "@deltarobotics/uhd";
+import type { WiringStep } from "@deltarobotics/uhd";
+import type { LoadedSystem, SceneModel } from "./model.ts";
+import { unitFromKey, unitFromKeys } from "./format.ts";
+import type { TestData } from "./testdata.ts";
+
+export type ValueStatus = "source" | "model" | "assumption" | "derived" | "standin" | "measured" | "gap";
+
+export interface ResolvedValue {
+  q: string;
+  value: unknown;
+  unit?: string;
+  status: ValueStatus;
+  /** URL or repo path the value is cited from. */
+  source?: string;
+  note?: string;
+  /** For derived values: the input queries. */
+  inputs?: string[];
+  formula?: string;
+}
+
+export interface DerivedDef {
+  label: string;
+  unit?: string;
+  formula: string;
+  compute: (ctx: DocContext, args?: string[]) => { value: unknown; inputs: string[]; note?: string; unit?: string };
+}
+
+export interface DocContext {
+  sys: LoadedSystem;
+  scene: SceneModel;
+  bom: any[];
+  checks: SystemCheckResult;
+  wiring: WiringStep[];
+  scenarioChecks: { id: string; label: string; description: string; diagnostics: SystemCheckResult["diagnostics"] }[];
+  /** Each circuit board below the system (a module with nets), checked on its own as protoboard check does. */
+  boards: { path: string; id: string; diagnostics: SystemCheckResult["diagnostics"] }[];
+  tests: Map<string, TestData>;
+  derived: Record<string, DerivedDef>;
+  /** Instance path -> module definition (leaf and assembly instances). */
+  instances: Map<string, ModuleDef>;
+  /** A value lookup (resolve). */
+  resolve: (q: string) => ResolvedValue;
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+type Seg = { key: string } | { index: number } | { match: [string, string] };
+
+export function parsePath(path: string): Seg[] {
+  const segs: Seg[] = [];
+  let i = 0;
+  while (i < path.length) {
+    const c = path[i];
+    if (c === ".") {
+      i++;
+      continue;
+    }
+    if (c === "[") {
+      const end = path.indexOf("]", i);
+      if (end < 0) throw new Error(`unclosed [ in ${path}`);
+      const body = path.slice(i + 1, end);
+      const eq = body.indexOf("=");
+      if (eq >= 0) segs.push({ match: [body.slice(0, eq), body.slice(eq + 1)] });
+      else segs.push({ index: Number(body) });
+      i = end + 1;
+      continue;
+    }
+    let j = i;
+    while (j < path.length && path[j] !== "." && path[j] !== "[") j++;
+    segs.push({ key: path.slice(i, j) });
+    i = j;
+  }
+  return segs;
+}
+
+interface Walk {
+  value: unknown;
+  parent?: any;
+  lastKey?: string;
+  /** The keys along the path, in order (not the values of [k=v] matches, which name items). */
+  keys: string[];
+  sources: string[];
+  trail: any[];
+}
+
+export function walk(root: unknown, path: string): Walk {
+  let cur: any = root;
+  let parent: any;
+  let lastKey: string | undefined;
+  const keys: string[] = [];
+  const sources: string[] = [];
+  const trail: any[] = [root];
+  const noteSource = (o: any) => {
+    if (o && typeof o === "object" && !Array.isArray(o)) {
+      const s = o.source ?? o.params?.source ?? o.metadata?.source;
+      if (typeof s === "string") sources.push(s);
+      else if (Array.isArray(s) && typeof s[0] === "string") sources.push(s[0]);
+    }
+  };
+  noteSource(cur);
+  for (const seg of parsePath(path)) {
+    if (cur === undefined || cur === null) return { value: undefined, parent, lastKey, keys, sources, trail };
+    parent = cur;
+    if ("key" in seg) {
+      if (seg.key === "length" && Array.isArray(cur)) cur = cur.length;
+      else cur = cur[seg.key];
+      lastKey = seg.key;
+      keys.push(seg.key);
+    } else if ("index" in seg) cur = cur[seg.index];
+    else {
+      const [k, v] = seg.match;
+      cur = Array.isArray(cur) ? cur.find((x) => String(x?.[k]) === v) : undefined;
+      lastKey = v;
+    }
+    trail.push(cur);
+    noteSource(cur);
+  }
+  return { value: cur, parent, lastKey, keys, sources, trail };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence per module
+// ---------------------------------------------------------------------------
+
+/** The first of the definition's evidence folders (project parts/evidence, or its package) that has `name`. */
+export function evidenceFile(sys: LoadedSystem, id: string, name: string): string | undefined {
+  return sys.evidenceDirs(id).map((d) => join(d, name)).find((f) => existsSync(f));
+}
+
+export function moduleSources(sys: LoadedSystem, id: string): { id: string; title: string; url: string; authority?: string }[] {
+  const p = evidenceFile(sys, id, "sources.json");
+  if (!p) return [];
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8"));
+    return Array.isArray(j) ? j : j.sources ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function moduleVerification(sys: LoadedSystem, id: string): any | undefined {
+  const p = evidenceFile(sys, id, "verification.json");
+  return p ? JSON.parse(readFileSync(p, "utf8")) : undefined;
+}
+
+function assumptionFor(def: ModuleDef, keys: string[]): string | undefined {
+  const lower = keys.filter(Boolean).map((k) => k.toLowerCase());
+  for (const t of def.traits ?? []) {
+    if (t.type !== "assumption") continue;
+    const field = String(t.params?.field ?? "").toLowerCase();
+    if (field && lower.some((k) => k === field || field.split(/[ ,/]+/).includes(k))) return String(t.params?.reason ?? t.params?.note ?? field);
+  }
+  return undefined;
+}
+
+function resolveDef(sys: LoadedSystem, q: string, def: ModuleDef | undefined, path: string): ResolvedValue {
+  if (!def) return { q, value: undefined, status: "gap", note: "module not found" };
+  const w = walk(def, path);
+  // a parameter stated as a range has no `value`: use the range
+  if ((w.value === undefined || w.value === null) && w.lastKey === "value" && Array.isArray(w.parent?.range)) w.value = w.parent.range;
+  let unit: string | undefined;
+  if (w.lastKey === "value" || w.lastKey === "range") unit = w.parent?.unit;
+  else if (w.lastKey === "weight_g") unit = "g";
+  // the last key's unit, else the nearest along the path (lowest_latency_ms.goggles_3 is in ms)
+  else if (w.lastKey) unit = unitFromKeys(w.keys);
+  const keys = w.trail.filter((x) => x && typeof x === "object" && !Array.isArray(x) && typeof x.id === "string").map((x) => x.id);
+  // an assumption trait, or any trait/spec object carrying its own `assumption` note (supplied_from, torque, material)
+  const inAssumptionTrait = w.trail.some((x) => x && typeof x === "object" && (x.type === "assumption" || (typeof x.assumption === "string" && x.assumption) || (typeof x.params?.assumption === "string" && x.params.assumption)));
+  const assumption = inAssumptionTrait ? "assumption trait" : assumptionFor(def, [...keys, w.lastKey ?? ""]);
+  const srcs = moduleSources(sys, def.id);
+  const verified = Boolean(moduleVerification(sys, def.id));
+  const source = w.sources.at(-1) ?? srcs[0]?.url ?? (def.artifacts ?? []).find((a) => a.url)?.url;
+  let status: ValueStatus = verified || srcs.length ? "source" : "model";
+  if (assumption) status = "assumption";
+  if (w.value === undefined || w.value === null) status = "gap";
+  return { q, value: w.value, unit, status, source: status === "model" ? `model: ${def.id}` : source, note: assumption };
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+export function makeResolver(ctx: Omit<DocContext, "resolve">): (q: string) => ResolvedValue {
+  const memo = new Map<string, ResolvedValue>();
+  const resolve = (q: string): ResolvedValue => {
+    if (memo.has(q)) return memo.get(q)!;
+    const r = resolveUncached(q);
+    memo.set(q, r);
+    return r;
+  };
+  const full = ctx as DocContext;
+  full.resolve = resolve;
+
+  const resolveUncached = (q: string): ResolvedValue => {
+    const colon = q.indexOf(":");
+    const scheme = q.slice(0, colon);
+    const rest = q.slice(colon + 1);
+    if (scheme === "def" || scheme === "inst") {
+      const c = rest.indexOf(":");
+      const target = c < 0 ? rest : rest.slice(0, c);
+      const path = c < 0 ? "" : rest.slice(c + 1);
+      const def = scheme === "def" ? ctx.sys.lookup(target) : ctx.instances.get(target);
+      return resolveDef(ctx.sys, q, def, path);
+    }
+    if (scheme === "sys") {
+      const root = {
+        system: ctx.sys.system,
+        checks: ctx.checks,
+        bom: ctx.bom,
+        wiring: ctx.wiring,
+        scenarios: ctx.scenarioChecks,
+        boards: ctx.boards,
+        assembly: {
+          mates: ctx.scene.assembly.mates.length,
+          placements: ctx.scene.assembly.placements.length,
+          hardware: ctx.scene.assembly.hardware.length,
+          issues: ctx.scene.assembly.issues,
+        },
+      };
+      const w = walk(root, rest);
+      return { q, value: w.value, unit: unitFromKeys(w.keys), status: w.value === undefined ? "gap" : "model", source: `UHD ${rest.split(/[.[]/)[0]}` };
+    }
+    if (scheme === "derived") {
+      const call = rest.match(/^([\w.]+)\((.*)\)$/);
+      const d = call ? ctx.derived[call[1]] : ctx.derived[rest];
+      if (d && call) {
+        const r = d.compute(full, call[2].split(",").map((x) => x.trim()));
+        const inputs = r.inputs.map(resolve);
+        const status: ValueStatus = inputs.some((i) => i.status === "standin") ? "standin" : r.value === undefined ? "gap" : inputs.some((i) => i.status === "assumption") ? "assumption" : "derived";
+        return { q, value: r.value, unit: r.unit ?? d.unit, status, inputs: r.inputs, formula: d.formula, note: r.note };
+      }
+      if (!d) return { q, value: undefined, status: "gap", note: `no derivation "${rest}"` };
+      const r = d.compute(full);
+      const inputs = r.inputs.map(resolve);
+      const status: ValueStatus = inputs.some((i) => i.status === "standin")
+        ? "standin"
+        : inputs.some((i) => i.status === "gap") && r.value === undefined
+          ? "gap"
+          : inputs.some((i) => i.status === "assumption")
+            ? "assumption"
+            : "derived";
+      return { q, value: r.value, unit: r.unit ?? d.unit, status, inputs: r.inputs, formula: d.formula, note: r.note };
+    }
+    if (scheme === "ver") {
+      const c = rest.indexOf(":");
+      const id = c < 0 ? rest : rest.slice(0, c);
+      const file = evidenceFile(ctx.sys, id, "verification.json");
+      const v = moduleVerification(ctx.sys, id);
+      if (!v || !file) return { q, value: undefined, status: "gap", note: `no verification record for ${id}` };
+      const w = walk(v, c < 0 ? "" : rest.slice(c + 1));
+      const shown = file.startsWith(ctx.sys.root) ? relative(ctx.sys.root, file).split("\\").join("/") : `${id}/verification.json (catalog evidence)`;
+      return { q, value: w.value, status: w.value === undefined ? "gap" : "model", source: shown };
+    }
+    if (scheme === "test") {
+      const c = rest.indexOf(":");
+      const id = c < 0 ? rest : rest.slice(0, c);
+      const t = ctx.tests.get(id);
+      if (!t) return { q, value: undefined, status: "gap", note: `no test data "${id}"` };
+      const path = c < 0 ? "" : rest.slice(c + 1);
+      const w = walk(t, path);
+      const cell = path.match(/^rows\[(\d+)\]\[(\d+)\]$/);
+      const unit = cell ? t.columns[Number(cell[2])]?.unit || undefined : w.parent?.unit || unitFromKeys(w.keys);
+      return { q, value: w.value, unit, status: t.status === "measured" ? "measured" : "standin", source: t.file };
+    }
+    throw new Error(`unknown value query scheme in "${q}"`);
+  };
+  return resolve;
+}
+
+/** Instance path -> def for every child at every level (assemblies included). */
+export function instanceMap(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined): Map<string, ModuleDef> {
+  const out = new Map<string, ModuleDef>();
+  const visit = (d: ModuleDef, prefix: string[]) => {
+    for (const c of d.children ?? []) {
+      const def = lookup(c.moduleDefId);
+      if (!def) continue;
+      const path = [...prefix, c.id];
+      out.set(bodyKey(path), def);
+      visit(def, path);
+    }
+  };
+  visit(system, []);
+  return out;
+}