partforge 0.26.1 → 0.27.0

package/src/framework/lint/rules-build.js

@@ -0,0 +1,84 @@
+// Group 3 — how the build uses the kernel, discovered by executing build() against
+// the validating probe with no geometry kernel. Every error in this group already
+// throws at runtime; the value is reaching it in microseconds, before a WASM boot.
+import { err, warn } from "./finding.js";
+import { OCCT_ONLY_OPS } from "../geometry/kernel.js";
+import { MAX_PROBE_OPS } from "../geometry/probe.js";
+
+const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
+const unique = (xs) => [...new Set(xs)];
+
+export const BUILD_RULES = [
+  {
+    id: "derive-throws",
+    run: ({ deriveError }) => (deriveError ? [
+      err("derive-throws", `derive(p) threw: ${deriveError}`,
+        "derive(p) must return derived values for any parameter set the defaults allow — fix the error so it does not throw. As written, the app is left spinning with no geometry: resolveParams's catch reports the failure but no build ever runs.",
+        "derive"),
+    ] : []),
+  },
+  {
+    id: "unknown-kernel-op",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "unknown-op" && i.scope === "kernel").map((i) => i.op))
+      .map((op) => err("unknown-kernel-op", `\`k.${op}(…)\` is not a kernel operation`,
+        `Remove the call or correct the name — see the kernel op table in docs/AUTHORING-PARTS.md for the full list.`,
+        "parts")),
+  },
+  {
+    id: "unknown-solid-op",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "unknown-op" && i.scope === "solid").map((i) => i.op))
+      .map((op) => err("unknown-solid-op", `\`.${op}(…)\` is not a Solid or Shape2D method`,
+        `Remove the call or correct the name — see the Solid and Shape2D method tables in docs/AUTHORING-PARTS.md.`,
+        "parts")),
+  },
+  {
+    id: "invalid-op-options",
+    run: ({ probe }) => unique(probe().issues
+      .filter((i) => i.kind === "invalid-options").map((i) => i.message))
+      .map((message) => err("invalid-op-options", message,
+        "Correct the options object to match the op's documented keys — the message above names the offending key or the missing required one.",
+        "parts")),
+  },
+  {
+    id: "build-throws",
+    run: ({ probe }) => probe().throws.map(({ subpart, message }) =>
+      err("build-throws", `sub-part "${subpart}" threw during a geometry-free build: ${message}`,
+        "Fix the error in build(). This was raised with no kernel attached, so it is a fault in the build's own logic (bad arithmetic, a missing param, a null dereference) rather than a geometry failure.",
+        `parts.${subpart}.build`)),
+  },
+  {
+    id: "manifold-backend-uses-occt-op",
+    run: ({ part, probe }) => {
+      if (part?.meta?.backend !== "manifold") return [];
+      return [...probe().used].filter((op) => OCCT_ONLY.has(op))
+        .map((op) => err("manifold-backend-uses-occt-op",
+          `\`meta.backend\` pins Manifold, but the build calls \`${op}\`, which only OCCT implements`,
+          `Remove \`meta.backend: "manifold"\` and let the probe route this part to OCCT, or replace \`${op}\` with a mesh-friendly construction — as written the build throws KernelCapabilityError.`,
+          "meta.backend"));
+    },
+  },
+  {
+    id: "build-runaway",
+    run: ({ probe }) => (probe().runaway ? [
+      err("build-runaway", `the build exceeded ${MAX_PROBE_OPS} kernel operations`,
+        "A loop in build() is not terminating, or a count parameter is far larger than intended. Bound the loop, or reduce the governing parameter.",
+        "parts"),
+    ] : []),
+  },
+  {
+    id: "nondeterministic-build",
+    run: ({ probe, probeAgain }) => {
+      const a = probe();
+      if (a.runaway || a.throws.length > 0) return []; // an aborted build can't be compared
+      const b = probeAgain();
+      if (b.runaway || b.throws.length > 0) return [];
+      if (JSON.stringify(a.calls) === JSON.stringify(b.calls)) return [];
+      return [warn("nondeterministic-build",
+        "two builds with identical parameters produced different kernel calls",
+        "build() must be a pure function of (k, p, d). Remove Math.random(), Date/clock reads, and module-level mutable state — the preview kernel memoizes geometry by content hash, so an impure build silently returns stale geometry.",
+        "parts", "impure-build-stale-preview")];
+    },
+  },
+];

package/src/framework/lint/rules-schema.js

@@ -0,0 +1,209 @@
+// Group 2 — the parameter schema that src/framework/controls.js turns into the panel.
+// Two failure modes drive this group: a shape controls.js reads without guarding
+// (features[].sliders at controls.js:313, an unguarded .filter), and keys that don't
+// resolve against `defaults`, which produce a control that silently does nothing.
+import { err, warn } from "./finding.js";
+import { suggest } from "../geometry/op-options.js";
+
+// Fields controls.js reads on a slider/number descriptor.
+const CONTROL_FIELDS = ["key", "label", "unit", "min", "max", "step", "control", "hidden", "description"];
+const FEATURE_FIELDS = ["key", "label", "on", "sliders", "hidden", "description"];
+const TOGGLE_FIELDS = ["key", "label", "on", "hidden", "description"];
+
+const sections = (part) => (Array.isArray(part?.parameters) ? part.parameters : []);
+const arr = (x) => (Array.isArray(x) ? x : []);
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+// Every (descriptor, path, allowed-fields) triple that owns a parameter key, across
+// all four section kinds. A feature's own `sliders` are collected too, since each
+// slider is a full control descriptor in its own right.
+function collectDescriptors(part) {
+  const out = [];
+  sections(part).forEach((sec, si) => {
+    arr(sec?.advanced).forEach((d, i) => {
+      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: CONTROL_FIELDS });
+    });
+    arr(sec?.features).forEach((f, i) => {
+      if (!f) return;
+      out.push({ d: f, path: `parameters[${si}].features[${i}]`, fields: FEATURE_FIELDS });
+      arr(f.sliders).forEach((s, j) => {
+        // Tag with the owning feature's key so slider-range-excludes-default can
+        // recognise the demo.js flange_d pattern below: a slider sharing its key
+        // with the feature is not an independent parameter, it's the feature's own
+        // magnitude, and `defaults[key] === 0` there means "off", not "out of range".
+        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: CONTROL_FIELDS, featureKey: f.key });
+      });
+    });
+    arr(sec?.toggles).forEach((t, i) => {
+      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: TOGGLE_FIELDS });
+    });
+  });
+  return out;
+}
+
+const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
+
+// Mirrors src/framework/controls.js's own visibility predicates (visibleFeatures /
+// sectionRenders, controls.js:32,36-41) — NOT imported, because controls.js pulls in
+// `marked`/`dompurify` (via markdown.js) for its description popovers, which would
+// break partforge/lint's zero-bare-dependency purity guarantee (test/lint-purity.test.js).
+// `features-requires-sliders` must not flag a `feat.sliders.filter(...)` the panel
+// will never reach: controls.js only iterates `visibleFeatures(sec)` (skipping any
+// feature marked `hidden: true`), and only builds a section at all when
+// `sectionRenders(sec)` is true.
+const visibleFeatures = (sec) => arr(sec?.features).filter((f) => f && !f.hidden);
+function sectionRenders(sec) {
+  if (sec?.hidden) return false;
+  if (sec?.features) return visibleFeatures(sec).length > 0;
+  const hasPresets = sec?.presets && Object.keys(sec.presets).length > 0;
+  return !!hasPresets || arr(sec?.advanced).some((d) => d && !d.hidden) || arr(sec?.toggles).some((t) => t && !t.hidden);
+}
+
+export const SCHEMA_RULES = [
+  {
+    id: "features-requires-sliders",
+    run: ({ part }) => {
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        // A feature the panel will never reach can't crash it: skip the whole
+        // section when it never renders at all (sectionRenders), and skip any
+        // individual feature the panel skips via `hidden: true` (visibleFeatures'
+        // own filter condition, restated inline rather than built into a Set).
+        if (!sectionRenders(sec)) return;
+        arr(sec?.features).forEach((f, i) => {
+          if (f && !f.hidden && !Array.isArray(f.sliders)) {
+            out.push(err("features-requires-sliders",
+              `section "${sec.id ?? si}" feature ${i} has no \`sliders\` array`,
+              "A `features` entry must carry a `sliders` array — the control panel reads it unguarded, so a missing one throws \"Cannot read properties of undefined (reading 'filter')\". A bare on/off control belongs in `toggles` instead.",
+              `parameters[${si}].features[${i}]`,
+              "features-missing-sliders"));
+          }
+        });
+      });
+      return out;
+    },
+  },
+  {
+    id: "control-key-not-in-defaults",
+    run: ({ part }) => {
+      // Only skip when `defaults` isn't a plain object at all (missing-defaults
+      // already reports that) — an explicit `defaults: {}` must still be checked,
+      // otherwise every control key in the part is silently unreachable and dead.
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      return collectDescriptors(part)
+        .filter(({ d }) => typeof d.key === "string" && !known.has(d.key))
+        .map(({ d, path }) => err("control-key-not-in-defaults",
+          `control key "${d.key}" is not in \`defaults\``,
+          `Add "${d.key}" to \`defaults\`${suggest(d.key, [...known]) ? `, or correct it to "${suggest(d.key, [...known])}"` : ""} — a control whose key is absent from defaults is silently dead and never reaches the build.`,
+          `${path}.key`));
+    },
+  },
+  {
+    id: "preset-key-not-in-defaults",
+    run: ({ part }) => {
+      // Same guard as control-key-not-in-defaults: only bail when `defaults` is
+      // entirely absent (or not an object), not merely empty.
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        const presets = sec?.presets;
+        if (!presets || typeof presets !== "object") return;
+        for (const [name, bundle] of Object.entries(presets)) {
+          if (!bundle || typeof bundle !== "object") continue;
+          for (const key of Object.keys(bundle)) {
+            if (known.has(key)) continue;
+            const hint = suggest(key, [...known]);
+            out.push(err("preset-key-not-in-defaults",
+              `preset "${name}" sets "${key}", which is not in \`defaults\``,
+              `Add "${key}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a preset field absent from defaults is dropped, so selecting the preset silently does nothing for it.`,
+              `parameters[${si}].presets[${JSON.stringify(name)}].${key}`));
+          }
+        }
+      });
+      return out;
+    },
+  },
+  {
+    id: "slider-range-excludes-default",
+    run: ({ part }) => {
+      const defaults = part?.defaults ?? {};
+      return collectDescriptors(part)
+        // A slider that shares its key with the feature that owns it (demo.js's
+        // flange_d) is exempt ONLY when the default is actually the feature's
+        // off-sentinel: controls.js sets `params[feat.key] = 0` on uncheck (and
+        // reads `params[feat.key] > 0` to decide checked state), so `0` there means
+        // "off", not "out of range". Matching keys alone isn't enough — a mistyped
+        // non-zero "on" default (e.g. 999 against an 8..50 slider) is exactly the
+        // authoring mistake this rule exists to catch, and must still warn.
+        .filter(({ d, featureKey }) => !(featureKey !== undefined && featureKey === d.key && defaults[d.key] === 0))
+        .filter(({ d }) => typeof d.key === "string"
+          && typeof defaults[d.key] === "number"
+          && (typeof d.min === "number" || typeof d.max === "number")
+          && ((typeof d.min === "number" && defaults[d.key] < d.min)
+            || (typeof d.max === "number" && defaults[d.key] > d.max)))
+        .map(({ d, path }) => warn("slider-range-excludes-default",
+          `\`defaults.${d.key}\` is ${defaults[d.key]}, outside this control's range ${d.min ?? "-∞"}..${d.max ?? "∞"}`,
+          `Widen the control's min/max or move \`defaults.${d.key}\` inside the range — as it stands the panel clamps the value on first render, so the geometry the user sees is not the geometry the defaults describe.`,
+          path));
+    },
+  },
+  {
+    id: "unknown-control-field",
+    run: ({ part }) => {
+      const out = [];
+      for (const { d, path, fields } of collectDescriptors(part)) {
+        for (const key of Object.keys(d)) {
+          if (fields.includes(key)) continue;
+          const hint = suggest(key, fields);
+          out.push(warn("unknown-control-field",
+            `unrecognised control field "${key}"`,
+            `The control panel ignores "${key}"${hint ? ` — did you mean "${hint}"?` : ` (recognised: ${fields.join(", ")}).`}`,
+            `${path}.${key}`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "duplicate-control-key",
+    run: ({ part }) => {
+      const seen = new Map();
+      const out = [];
+      for (const { d, path } of collectDescriptors(part)) {
+        if (typeof d.key !== "string") continue;
+        // A feature and its own slider legitimately share a key (see demo.js's
+        // flange_d), so only flag a repeat that crosses to a different owner path.
+        const root = path.replace(/\.sliders\[\d+\]$/, "");
+        if (seen.has(d.key) && seen.get(d.key) !== root) {
+          out.push(warn("duplicate-control-key",
+            `parameter key "${d.key}" is owned by more than one control`,
+            `Two controls writing "${d.key}" fight over the same value — rename one, or remove the duplicate.`,
+            path));
+        } else if (!seen.has(d.key)) {
+          seen.set(d.key, root);
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "default-not-exposed",
+    run: ({ part }) => {
+      if (sections(part).length === 0) return []; // no panel declared at all — nothing to expose
+      const exposed = new Set(collectDescriptors(part).map(({ d }) => d.key).filter(Boolean));
+      for (const sec of sections(part)) {
+        for (const bundle of Object.values(sec?.presets ?? {})) {
+          for (const key of Object.keys(bundle ?? {})) exposed.add(key);
+        }
+      }
+      return Object.keys(part?.defaults ?? {})
+        .filter((key) => !exposed.has(key))
+        .map((key) => warn("default-not-exposed",
+          `\`defaults.${key}\` is not referenced by any control`,
+          `Either add a control for "${key}" or leave it as an intentional internal constant — a hidden control (\`hidden: true\`) counts as exposing it, and is the documented way to keep a build-only value out of the panel.`,
+          `defaults.${key}`));
+    },
+  },
+];

package/src/framework/lint/rules-shape.js

@@ -0,0 +1,86 @@
+// Group 1 — definition shape and view wiring. This group is the shared replacement
+// for partforge-cloud's hand-rolled sandbox validate(), which checks meta.title,
+// defaults and build but not `views`, and had already drifted from the eval runner's
+// separate views check. One source of truth ends that split.
+import { err, warn } from "./finding.js";
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const partEntries = (part) => (isPlainObject(part?.parts) ? Object.entries(part.parts) : []);
+
+export const SHAPE_RULES = [
+  {
+    id: "missing-meta-title",
+    run: ({ part }) => (typeof part?.meta?.title === "string" && part.meta.title.length > 0 ? [] : [
+      err("missing-meta-title", "the part has no `meta.title`",
+        "Add a `meta` object with a `title` string — it names the part in the viewer and in export filenames.",
+        "meta.title"),
+    ]),
+  },
+  {
+    id: "missing-defaults",
+    run: ({ part }) => (isPlainObject(part?.defaults) ? [] : [
+      err("missing-defaults", "the part has no `defaults` object",
+        "Add a `defaults` object giving every parameter its starting value; the control panel and every build read from it.",
+        "defaults"),
+    ]),
+  },
+  {
+    id: "no-buildable-parts",
+    run: ({ part }) => {
+      const entries = partEntries(part);
+      if (entries.length === 0) {
+        return [err("no-buildable-parts", "the part declares no sub-parts in `parts`",
+          "Add at least one entry to `parts`, each with a `build(k, p, d)` function returning a solid.",
+          "parts")];
+      }
+      return entries
+        .filter(([, sp]) => typeof sp?.build !== "function")
+        .map(([name]) => err("no-buildable-parts", `sub-part "${name}" has no \`build\` function`,
+          "Every entry in `parts` needs a `build(k, p, d)` function that returns a solid.",
+          `parts.${name}.build`));
+    },
+  },
+  {
+    id: "missing-views",
+    run: ({ part }) => (isPlainObject(part?.views) && Object.keys(part.views).length > 0 ? [] : [
+      err("missing-views", "the part has no `views` map",
+        "Add a top-level `views` object — e.g. `views: { main: { label: \"Main\" } }` — and list each view name in the owning sub-part's `views` array.",
+        "views"),
+    ]),
+  },
+  {
+    id: "part-view-unknown",
+    run: ({ part }) => {
+      const known = isPlainObject(part?.views) ? new Set(Object.keys(part.views)) : new Set();
+      if (known.size === 0) return []; // missing-views already reported it; don't pile on
+      const out = [];
+      for (const [name, sp] of partEntries(part)) {
+        if (!Array.isArray(sp?.views)) continue;
+        sp.views.forEach((v, i) => {
+          if (!known.has(v)) {
+            out.push(err("part-view-unknown",
+              `sub-part "${name}" lists view "${v}", which is not in the \`views\` map`,
+              `Add "${v}" to the top-level \`views\` map, or correct the name to one of: ${[...known].join(", ")}.`,
+              `parts.${name}.views[${i}]`));
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "view-unused",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.views)) return [];
+      const used = new Set();
+      for (const [, sp] of partEntries(part)) {
+        if (Array.isArray(sp?.views)) for (const v of sp.views) used.add(v);
+      }
+      return Object.keys(part.views)
+        .filter((v) => !used.has(v))
+        .map((v) => warn("view-unused", `view "${v}" is not listed by any sub-part`,
+          `Either add "${v}" to a sub-part's \`views\` array or remove it from the \`views\` map — as it stands the view renders empty.`,
+          `views.${v}`));
+    },
+  },
+];

package/src/framework/lint/rules-verify.js

@@ -0,0 +1,288 @@
+// Group 4 — the verify block's own well-formedness. Each condition here currently
+// throws from verify() mid-run, AFTER measure has printed and the kernel has booted,
+// which is also the documented reason CLI stdout isn't pure JSON in that case.
+// Catching them statically removes both the wasted boot and the stdout caveat.
+import { err } from "./finding.js";
+import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
+import { PROFILES } from "../../testing/dfm-profiles.js";
+import { parseAssertion } from "../../testing/assert-dsl.js";
+import { suggest } from "../geometry/op-options.js";
+
+// Resolve `expect` to a plain object. The function form (p, d) => ({…}) is invoked
+// once with the probe's params so per-preset topology can be linted like any other.
+// Returns { expect, threw }.
+//
+// Exported so `lintContext` (index.js) can memoize a single call per lint pass and
+// share it across every Group 4 rule below — `expect` is user-supplied code, and
+// without memoization a function-form `expect` that throws only on its first call
+// would fire both `verify-expect-throws` (first call) and whatever rule calls it
+// next (second call succeeds), a cascading double-report.
+export function resolveExpect(verify, p, d) {
+  if (typeof verify?.expect !== "function") return { expect: verify?.expect, threw: null };
+  try { return { expect: verify.expect(p, d), threw: null }; }
+  catch (e) { return { expect: null, threw: e?.message || String(e) }; }
+}
+
+const isExpectation = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "expr" in v;
+const exprOf = (v) => (isExpectation(v) ? v.expr : v);
+
+// `contacts` (must-touch pairs) and `clearance` (free-fit gaps) live under
+// `verify.expect._view` but are pair-wise checks, not scalar VIEW_METRICS — mirror
+// verify.js's own peel (verify.js:143) so they never hit the scalar-metric /
+// assertion-expression checks below. Validated for real by `verify-bad-pair-check`.
+const peelPairKeys = (metrics) => {
+  const { contacts, clearance, ...rest } = metrics;
+  return rest;
+};
+
+// `JSON.stringify` can itself throw (BigInt, circular refs) — lintPart must never
+// throw, so fall back to `String` for anything that won't serialize.
+const describe = (v) => { try { return JSON.stringify(v); } catch { return String(v); } };
+
+// `suggest` calls `.toLowerCase()` on the key; guard against non-string pair names
+// (a runtime `contacts`/`clearance` entry can contain anything).
+const safeSuggest = (key, valid) => (typeof key === "string" ? suggest(key, valid) : null);
+
+// `requirePair` (verify.js:41) throws before it even looks at `part.parts` when a
+// pair names the same sub-part twice — a pair describes a relationship between two
+// distinct sub-parts, so self-pairs are never legal.
+function checkSameName(a, b, path) {
+  return a === b
+    ? [err("verify-bad-pair-check",
+        `\`${path}\` names the same sub-part twice ("${a}")`,
+        "A pair must name two different sub-parts. Change one side to the other sub-part it should be checked against, or remove the entry if it doesn't describe a real relationship.",
+        path)]
+    : [];
+}
+
+// Both `contacts` pairs and `clearance` keys ultimately name two sub-parts; a name
+// absent from `part.parts` is what the runtime `requirePair` throws for.
+function checkPairNames(a, b, names, path) {
+  const out = [];
+  for (const n of [a, b]) {
+    if (names.includes(n)) continue;
+    const hint = safeSuggest(n, names);
+    out.push(err("verify-unknown-subpart",
+      `\`${path}\` references "${n}", which is not a sub-part`,
+      `Use one of the sub-part names (${names.join(", ")})${hint ? ` — did you mean "${hint}"?` : "."}`,
+      path));
+  }
+  return out;
+}
+
+// Static analogue of verify.js's `pairGapChecks` contacts handling (verify.js:61-66).
+function checkContacts(contacts, names, path) {
+  if (contacts === undefined || contacts === null) return [];
+  if (!Array.isArray(contacts)) {
+    return [err("verify-bad-pair-check",
+      `\`${path}\` must be an array of ["a", "b"] pairs, got ${describe(contacts)}`,
+      `Set \`contacts\` to an array of two-element sub-part name pairs, e.g. \`contacts: [["lid", "body"]]\`.`,
+      path)];
+  }
+  const out = [];
+  contacts.forEach((pair, i) => {
+    const pairPath = `${path}[${i}]`;
+    if (!Array.isArray(pair) || pair.length !== 2) {
+      out.push(err("verify-bad-pair-check",
+        `\`${pairPath}\` must be an ["a", "b"] pair, got ${describe(pair)}`,
+        `Each \`contacts\` entry must be a two-element array naming the two sub-parts that should touch, e.g. \`["lid", "body"]\`.`,
+        pairPath));
+      return;
+    }
+    out.push(...checkSameName(pair[0], pair[1], pairPath));
+    // `requirePair` (verify.js:41) checks the same-name case first and throws
+    // before ever looking at `part.parts` — so a same-name pair never reaches the
+    // unknown-name check at runtime either. Skip it here too, or an unknown
+    // self-paired name would double-report (once per identical position).
+    if (pair[0] !== pair[1]) out.push(...checkPairNames(pair[0], pair[1], names, pairPath));
+  });
+  return out;
+}
+
+// Static analogue of verify.js's `pairGapChecks` clearance handling (verify.js:85-87).
+// Note the separator is the multiplication sign "×" (U+00D7), not the letter x.
+function checkClearance(clearance, names, path) {
+  if (clearance === undefined || clearance === null || typeof clearance !== "object") return [];
+  const out = [];
+  for (const key of Object.keys(clearance)) {
+    const pairPath = `${path}[${JSON.stringify(key)}]`;
+    const pair = key.split("×").map((s) => s.trim());
+    if (pair.length !== 2 || !pair[0] || !pair[1]) {
+      out.push(err("verify-bad-pair-check",
+        `\`${pairPath}\` key must be "a×b" (sub-part names joined by the multiplication sign ×), got ${JSON.stringify(key)}`,
+        `Rename the key to \`"a×b"\` using the two sub-part names that should have a declared clearance, e.g. \`"lid×body"\`. The separator is U+00D7 (×), not the letter x.`,
+        pairPath));
+      continue;
+    }
+    out.push(...checkSameName(pair[0], pair[1], pairPath));
+    // Same short-circuit as `checkContacts` above: a same-name pair never reaches
+    // the unknown-name check at runtime (or here), so it can't double-report.
+    if (pair[0] !== pair[1]) out.push(...checkPairNames(pair[0], pair[1], names, pairPath));
+  }
+  return out;
+}
+
+// `clearance`'s values genuinely are assertion expressions run through the DSL
+// (verify.js:96), unlike `contacts` (pair arrays with nothing to parse). Mirror
+// verify.js's own normalization — a bare value or an `{ expr, hint }` wrapper,
+// via `normalizeExpectation` (verify.js:91) — using the same `isExpectation` /
+// `exprOf` helpers the scalar-metric loop below uses. Reported under
+// `verify-bad-expr`, not `verify-bad-pair-check`: a malformed key is a pair-naming
+// problem, but a malformed value is an assertion-DSL problem, same as any other
+// metric's expectation.
+function checkClearanceExprs(clearance, path) {
+  if (clearance === undefined || clearance === null || typeof clearance !== "object") return [];
+  const out = [];
+  for (const [key, spec] of Object.entries(clearance)) {
+    try { parseAssertion(exprOf(spec)); }
+    catch (e) {
+      out.push(err("verify-bad-expr",
+        `the expectation for _view.clearance["${key}"] is not a valid assertion: ${e?.message || String(e)}`,
+        "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
+        `${path}[${JSON.stringify(key)}]`));
+    }
+  }
+  return out;
+}
+
+// Static walk of `resolveProfile`'s (dfm-profiles.js) `base` chain, mirroring its
+// exact throw conditions at every level: a string not in `PROFILES` ("unknown
+// process profile"), or — recursively — a bad `base` nested inside a `base`
+// object. A falsy `base` resolves to `{}` at runtime (`spec.base ? … : {}`) and
+// is never reached, so it's left alone here too. `seen` records every `base`
+// value already visited so a self-referential or cyclic chain (`base.base ===
+// base`) cannot recurse forever — `lintPart` must always terminate. `depth` is a
+// second, cheap belt-and-suspenders cap for the same reason.
+function checkProcessSpec(spec, path, valid, seen, depth = 0) {
+  if (depth > 50) return []; // pathological chain — bail rather than hang
+  if (typeof spec === "string") {
+    if (valid.includes(spec)) return [];
+    const hint = suggest(spec, valid);
+    return [err("verify-unknown-process",
+      `\`${path}\` names "${spec}", which is not a known DFM profile`,
+      `Use one of: ${valid.join(", ")}${hint ? ` — did you mean "${hint}"?` : ""}, or pass an inline profile object such as \`{ bed: [220, 220, 250], minWall: 1.2 }\`.`,
+      path)];
+  }
+  if (spec && typeof spec === "object") {
+    if (!spec.base) return []; // no base (or a falsy one) — nothing further to resolve
+    if (seen.has(spec.base)) return []; // already visited — self-referential/cyclic, stop
+    seen.add(spec.base);
+    return checkProcessSpec(spec.base, `${path}.base`, valid, seen, depth + 1);
+  }
+  // Anything else truthy (number, boolean, …) is what resolveProfile's final
+  // branch throws "invalid process profile" for.
+  return [err("verify-unknown-process",
+    `\`${path}\` is not a valid DFM profile: ${describe(spec)}`,
+    `Use one of: ${valid.join(", ")}, or an inline profile object such as \`{ bed: [220, 220, 250], minWall: 1.2 }\`.`,
+    path)];
+}
+
+export const VERIFY_RULES = [
+  {
+    id: "verify-expect-throws",
+    run: ({ resolveExpectOnce }) => {
+      const { threw } = resolveExpectOnce();
+      return threw ? [err("verify-expect-throws",
+        `\`verify.expect(p, d)\` threw: ${threw}`,
+        "The function form of `expect` must return an expectation object for any parameter set. Guard whatever it reads, or switch to the static object form.",
+        "verify.expect")] : [];
+    },
+  },
+  {
+    id: "verify-unknown-subpart",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      return Object.keys(expect)
+        .filter((key) => key !== "_view" && !names.includes(key))
+        .map((key) => {
+          const hint = suggest(key, names);
+          return err("verify-unknown-subpart",
+            `\`verify.expect\` targets "${key}", which is not a sub-part`,
+            `Use one of the sub-part names (${names.join(", ")}) or the literal \`_view\` for whole-assembly metrics${hint ? ` — did you mean "${hint}"?` : "."}`,
+            `verify.expect.${key}`);
+        });
+    },
+  },
+  {
+    id: "verify-unknown-metric",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      const out = [];
+      for (const [target, metricsRaw] of Object.entries(expect)) {
+        if (target !== "_view" && !names.includes(target)) continue; // reported by verify-unknown-subpart
+        if (!metricsRaw || typeof metricsRaw !== "object") continue;
+        // contacts/clearance are pair checks, not scalar view metrics — validated
+        // separately by verify-bad-pair-check, and excluded here.
+        const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
+        const registry = target === "_view" ? VIEW_METRICS : SUBPART_METRICS;
+        const valid = Object.keys(registry);
+        for (const metric of Object.keys(metrics)) {
+          if (valid.includes(metric)) continue;
+          const hint = suggest(metric, valid);
+          out.push(err("verify-unknown-metric",
+            `"${metric}" is not a ${target === "_view" ? "view" : "sub-part"} metric`,
+            `Valid ${target === "_view" ? "view" : "sub-part"} metrics are: ${valid.join(", ")}${hint ? ` — did you mean "${hint}"?` : "."}`,
+            `verify.expect.${target}.${metric}`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "verify-bad-expr",
+    run: ({ resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const out = [];
+      for (const [target, metricsRaw] of Object.entries(expect)) {
+        if (!metricsRaw || typeof metricsRaw !== "object") continue;
+        // `contacts` is pair arrays with no expression to parse, and `clearance`'s
+        // values are keyed by pair name rather than metric name — both are peeled
+        // from this scalar-metric loop. `clearance`'s values are still assertions
+        // though, so they get their own pass (with a pair-shaped path) below.
+        const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
+        for (const [metric, spec] of Object.entries(metrics)) {
+          try { parseAssertion(exprOf(spec)); }
+          catch (e) {
+            out.push(err("verify-bad-expr",
+              `the expectation for ${target}.${metric} is not a valid assertion: ${e?.message || String(e)}`,
+              "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
+              `verify.expect.${target}.${metric}`));
+          }
+        }
+      }
+      out.push(...checkClearanceExprs(expect?._view?.clearance, "verify.expect._view.clearance"));
+      return out;
+    },
+  },
+  {
+    id: "verify-bad-pair-check",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      const view = expect?._view;
+      if (!view || typeof view !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      return [
+        ...checkContacts(view.contacts, names, "verify.expect._view.contacts"),
+        ...checkClearance(view.clearance, names, "verify.expect._view.clearance"),
+      ];
+    },
+  },
+  {
+    id: "verify-unknown-process",
+    run: ({ part }) => {
+      const process = part?.verify?.process;
+      // verify.js:163-164 — `profileSpec ?? part.verify?.process` then
+      // `profileSpec ? resolveProfile(profileSpec) : null` — that second check is
+      // truthiness, not a null/undefined check, so ANY falsy `process` (undefined,
+      // null, "", 0, false) never reaches `resolveProfile` and can't throw.
+      if (!process) return [];
+      const valid = Object.keys(PROFILES);
+      return checkProcessSpec(process, "verify.process", valid, new Set());
+    },
+  },
+];