partforge 0.26.0 → 0.27.0

package/bin/cli.js

@@ -15,9 +15,10 @@ import { verify } from "../src/testing/verify.js";
 import { renderViews } from "../src/testing/render.js";
 import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
 import { matchPattern } from "../src/testing/error-patterns.js";
+import { lintPart } from "../src/lint.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
-const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
@@ -59,16 +60,57 @@ async function loadPart(partPath, usage) {
 const bootKernel = (part) => (detectBackend(part) === "occt" ? bootOcctKernel() : bootManifoldKernel());
 
 const commands = {
+  async lint(args) {
+    const usage = "usage: partforge lint <part-module> [--params <json>] [--json] [--out <file>] [--strict]";
+    const { values: flags, positionals: [partPath] } = parse(args, {
+      params: { type: "string" },
+      json: { type: "boolean" },
+      out: { type: "string" },
+      strict: { type: "boolean" },
+    }, usage);
+    try {
+      const part = await loadPart(partPath, usage);
+      const params = flags.params ? JSON.parse(flags.params) : undefined;
+      const report = lintPart(part, { params });
+      if (!flags.json) printLint(report);
+      if (flags.out) {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+        console.log(`\nwrote ${flags.out}`);
+      }
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      process.exit(report.ok && (!flags.strict || report.warnings.length === 0) ? 0 : 1);
+    } catch (e) {
+      crash("lint", e, !!flags.json);
+    }
+  },
+
   async measure(args) {
-    const usage = "usage: partforge measure <part-module> [view] [--process <profile>] [--no-verify] [--json] [--out <file>]";
+    const usage = "usage: partforge measure <part-module> [view] [--process <profile>] [--no-verify] [--no-lint] [--json] [--out <file>]";
     const { values: flags, positionals: [partPath, view] } = parse(args, {
       process: { type: "string" },
       "no-verify": { type: "boolean" },
+      "no-lint": { type: "boolean" },
       json: { type: "boolean" },
       out: { type: "string" },
     }, usage);
     try {
       const part = await loadPart(partPath, usage);
+      // Error-tier lint before the kernel boots: a statically broken part fails in
+      // milliseconds with a precise message rather than after a WASM boot and a
+      // downstream error that doesn't name the cause. Warnings never gate measure.
+      if (!flags["no-lint"]) {
+        const lint = lintPart(part);
+        if (!lint.ok) {
+          if (flags.json) console.log(JSON.stringify({ ok: false, lint }, null, 2));
+          else printLint(lint);
+          if (flags.out) {
+            mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+            writeFileSync(flags.out, JSON.stringify({ ok: false, lint }, null, 2));
+          }
+          process.exit(1);
+        }
+      }
       const kernel = await bootKernel(part);
       const report = measure(kernel, part, view);
       printMeasure(report);
@@ -172,6 +214,19 @@ function printVerify(v) {
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
 
+function printLint(r) {
+  const all = [...r.errors, ...r.warnings];
+  if (all.length === 0) { console.log("lint: clean"); return; }
+  console.log("lint:");
+  for (const f of all) {
+    console.log(`  ${f.severity === "error" ? "✗" : "⚠"} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
+    console.log(`      ${f.message}`);
+    console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
+  }
+  const e = r.errors.length, w = r.warnings.length;
+  console.log(`  result: ${e ? `${e} error(s)` : "no errors"}${w ? `, ${w} warning(s)` : ""}`);
+}
+
 const [, , cmd, ...args] = process.argv;
 if (!commands[cmd]) die(USAGE);
 await commands[cmd](args);

package/docs/AUTHORING-PARTS.md

@@ -390,6 +390,28 @@ choosing a preset updates both numeric and text fields.
 Every `key` used must exist in `defaults`. `src/parts/demo.js` is the worked example for
 everything below.
 
+**Standalone toggles** (a plain on/off checkbox, no accompanying sliders): add a
+`toggles` array to a preset section — shown below the preset picker, outside the
+Advanced fold, so it stays visible:
+
+```js
+{
+  id: "shape",
+  title: "Shape ops",
+  toggles: [
+    { key: "clip", label: "Clip arms to a disc (intersect)", on: 1,
+      description: "**Intersect** the cross with a circle so the four arm tips are rounded off to a common radius." },
+  ],
+}
+```
+
+Each entry is `{ key, label, on?, hidden?, description? }`: checked sets `key` to `on`
+(default `1`); unchecked sets it to `0`. This is the correct home for a bare boolean —
+a `features` entry *requires* a `sliders` array (the panel reads `feat.sliders.filter(...)`
+unguarded and throws if it's missing), so a feature with nothing to reveal belongs in
+`toggles` instead. `src/parts/bracket.js`'s `clip` toggle (shown above) is the worked
+example.
+
 **Control metadata (optional — on any control def, feature, or section):**
 
 - `description` — a CommonMark string shown in a click-open **ⓘ** popover beside the
@@ -785,6 +807,83 @@ The `measure` function is also exported for vitest (boot a Manifold kernel as in
       expect(r.subparts[0].holes).toBe(1);   // e.g. expects one bore
     });
 
+## Linting
+
+`partforge lint` statically validates a PartDefinition without booting a geometry
+kernel. It runs in milliseconds and catches the authoring mistakes that otherwise
+surface only at runtime — or, worse, not at all.
+
+```bash
+npx partforge lint src/parts/<part>.js [--params '{"h":40}'] [--json] [--out f] [--strict]
+```
+
+Exit 0 when clean, 1 when any **error** finding is present; `--strict` also fails on
+warnings. `partforge measure` runs the error tier automatically before booting a
+kernel — pass `--no-lint` to skip it.
+
+The same check is available programmatically and in the browser:
+
+```js
+import { lintPart } from "partforge/lint";
+const { ok, errors, warnings } = lintPart(part, { params });
+```
+
+`partforge/lint` has **zero runtime dependencies** and never imports a geometry
+kernel or the DOM viewer, so it runs unchanged in Node, a Web Worker, a sandboxed
+iframe, and Deno. A worker also answers `{ type: "lint", params }` with
+`{ type: "lint-report", report }` without booting its kernel.
+
+**Findings** carry the same guarantees as verify's checks — a self-contained `hint`
+on every one, and a stable `pattern` id where an ERROR-PATTERNS.md entry applies:
+
+```js
+{ rule: "features-requires-sliders", severity: "error",
+  message: "section \"flange\" feature 0 has no `sliders` array",
+  hint: "A `features` entry must carry a `sliders` array …",
+  path: "parameters[1].features[0]", pattern: "features-missing-sliders" }
+```
+
+`path` is a JS accessor path rooted at the PartDefinition — `parameters[1].features[0]`,
+`defaults.bore`, `parts.spacer.views[0]`, `parameters[0].presets["M3"].od`. Findings
+about the definition as a whole use `""`.
+
+**Severity.** A finding is an `error` when the part is *provably broken* — it cannot
+behave as authored — whether or not that shows up as a thrown exception. Some error
+findings do correspond to a runtime throw (`build-throws`, `verify-expect-throws`),
+but others catch **silent** wrongness: `missing-meta-title`, `part-view-unknown`,
+`control-key-not-in-defaults`, `preset-key-not-in-defaults`, and
+`verify-unknown-subpart` all fire on parts that build, measure, and verify cleanly —
+a dead control that's silently unreachable, a view that renders nothing, or a
+`verify` expectation that's silently dropped so its gate never runs. That's still an
+error: the part doesn't do what its author wrote, the failure is just quiet instead
+of loud. Everything speculative or stylistic — lossy but not broken — is a `warning`
+and never blocks anything. Because `measure` runs the error tier as a gate (see
+below), a part with one of these silent defects now exits non-zero where it
+previously didn't; that's the fix working as intended, not a regression.
+
+### Rule catalog
+
+**Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`,
+`missing-views`, `part-view-unknown` (all errors); `view-unused` (warning).
+
+**Parameter schema** — `features-requires-sliders`, `control-key-not-in-defaults`,
+`preset-key-not-in-defaults` (errors); `slider-range-excludes-default`,
+`unknown-control-field`, `duplicate-control-key`, `default-not-exposed` (warnings).
+
+**Kernel API**, found by executing `build()` against a geometry-free probe —
+`unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
+`derive-throws`, `manifold-backend-uses-occt-op`, `build-runaway` (errors);
+`nondeterministic-build` (warning, from diffing two probe runs).
+
+**Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
+`verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
+`verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise
+`contacts` / `clearance` keys, which are not scalar view metrics; they are
+validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
+
+A rule that itself throws yields an `internal-rule-error` **warning** and the run
+continues: `lintPart` never throws and never blocks a part because of a linter bug.
+
 ### The diagnostics contract (for agents)
 
 `partforge measure <part> --json` / `--out <file>` emits the machine-readable
@@ -817,13 +916,20 @@ JSON to stdout and exits 1:
 ```
 
 `pattern`/`hint` appear when the message matches an ERROR-PATTERNS.md symptom
-string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. Caveat: a throw
-*after* measure output has printed (e.g. an unknown metric in `verify.expect`, or
-a per-case build crash) appends this JSON after the human lines, so stdout is no
-longer pure JSON; prefer `--out` (or parse the trailing JSON object — the crash
-JSON is pretty-printed across multiple lines) for robust machine parsing. With
-`--out` the measure report is written to the file as soon as `measure` succeeds,
-so even if a later `verify` throw crashes the run the file is there — it just
+string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. `measure`'s
+automatic lint pass (see "Linting" above) now catches most of the defects that
+used to surface this way statically, before the kernel boots, so they fail with
+pure JSON up front instead. The caveat narrows but doesn't disappear: lint
+resolves `verify.expect` once against the part's *defaults*, while `verify()`
+itself expands every `verify.cases` entry and re-resolves `expect(p, d)` per
+case — so an expectation that only names a bad metric/subpart for a non-default
+case (see `test/fixtures/unknown-metric-in-case-part.js`) still passes lint
+clean and then throws at runtime, after measure output has printed. That throw
+appends crash JSON after the human lines, so stdout is no longer pure JSON;
+prefer `--out` (or parse the trailing JSON object — the crash JSON is
+pretty-printed across multiple lines) for robust machine parsing. With `--out`
+the measure report is written to the file as soon as `measure` succeeds, so
+even if a later `verify` throw crashes the run the file is there — it just
 lacks the `verify` key.
 
 **Fresh-evidence rule.** A passing report is evidence only for the source, parameters,

package/docs/ERROR-PATTERNS.md

@@ -115,6 +115,12 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** A `key` used in the `parameters` schema (slider, feature, or preset override) doesn't exist in `defaults` — every key must, including `hidden` ones.
 - **Fix:** Add the key to `defaults` with a sensible starting value. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
 
+## features-missing-sliders
+
+- **Symptom:** `Cannot read properties of undefined (reading 'filter')` thrown from the control panel while the app boots, with no geometry ever rendering.
+- **Cause:** A `features` entry in the parameter schema has no `sliders` array — `controls.js` reads `feat.sliders.filter(...)` unguarded. A bare on/off control was put in `features` instead of `toggles`.
+- **Fix:** Move a bare boolean to the section's `toggles` array (`{ key, label, on }`), or give the `features` entry the `sliders` array it requires. `npx partforge lint <part>` catches this statically as `features-requires-sliders`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
+
 ## dimmed-control-vestigial-param
 
 - **Symptom:** A control renders dimmed (but still editable) and changing it does nothing on screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     ".": "./src/index.js",
     "./worker": "./src/framework/worker.js",
     "./geometry": "./src/framework/geometry/polygon.js",
+    "./lint": "./src/lint.js",
     "./derive": "./src/framework/derive.js",
     "./testing": "./src/testing.js",
     "./tokens.css": "./src/framework/tokens.css"

package/skills/partforge/SKILL.md

@@ -60,4 +60,10 @@ Picks come back **in request order**, each echoing its prompt, so you can map th
 ## Related: debugging failures
 
 If anything fails while you're editing a part, grep `docs/ERROR-PATTERNS.md` for the
-symptom first — its preamble states the full grep-first rule.
+symptom first — its preamble states the full grep-first rule. Before assuming a user's
+click is needed at all, run the static linter — it's instant, needs no live app, and
+catches schema/build mistakes no pick session would explain:
+
+```bash
+partforge lint src/parts/<part>.js
+```

package/src/framework/geometry/kernel-front.js

@@ -12,7 +12,16 @@
 //     capability (Manifold can't do toSTEP; both backends now define shape2d, so
 //     that stub is dead in practice — kept as a safety net for a future backend).
 // The per-Solid twin of this layer is addSugar() in solid-sugar.js.
-import * as opentype from "opentype.js";
+// opentype.js 2.x ships no `exports` map: bundlers take its `module` field (real
+// ESM, named `parse`), while Node ESM takes `main` (a UMD/CJS bundle, whose named
+// exports Node cannot statically detect — the namespace holds only `default`).
+// So `import * as opentype` gives a working `.parse` in the browser and `undefined`
+// under Node, which broke every headless text2d build (`opentype.parse is not a
+// function`) while the browser stayed green. Normalize both interop shapes here.
+import * as opentypeNamespace from "opentype.js";
+const opentype = typeof opentypeNamespace.parse === "function"
+  ? opentypeNamespace
+  : (opentypeNamespace.default ?? opentypeNamespace);
 import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { textGlyphs } from "./text2d.js";

package/src/framework/geometry/op-options.js

@@ -28,7 +28,9 @@ function editDistance(a, b) {
 // Prefix match first so long-form names hit their short key (radius→r,
 // height→h, diameter→d), then edit distance ≤ 2 for plain typos. A digit
 // suffix is peeled and re-attached so radius1 hints r1, not r.
-function suggest(key, valid) {
+// Exported so partforge/lint's `unknown-control-field` rule reuses this exact
+// suggester rather than carrying a second copy of the edit-distance logic.
+export function suggest(key, valid) {
   const lk = key.toLowerCase();
   const m = /^([a-z]+)(\d+)$/.exec(lk);
   if (m) for (const v of valid) if (m[1].startsWith(v.toLowerCase()) && valid.includes(v + m[2])) return v + m[2];

package/src/framework/geometry/probe.js

@@ -1,22 +1,44 @@
-// Geometry-free backend detection. A probe kernel records every op a part's
-// build() invokes (returning chainable no-op proxies, dummy values for queries);
-// if an OCCT-only op was used, the part needs the OCCT backend. The op list lives
-// in kernel.js — the same list generates the Manifold backend's throwing stubs.
-import { OCCT_ONLY_OPS } from "./kernel.js";
+// Geometry-free build execution. Two consumers share one Proxy implementation:
+//
+//  • createProbeKernel() — records op NAMES so detectBackend() can route a part to
+//    OCCT when it uses fillet/chamfer/shell.
+//  • createValidatingProbe() — additionally checks op names against the kernel
+//    contract's op lists and routes options-form calls through the same op-options
+//    normalizers the real backends use, so partforge/lint can catch a bad call in
+//    microseconds instead of after a WASM boot.
+//
+// Catch-all proxies (rather than a hand-listed allowlist) mean new kernel/solid
+// methods never have to be mirrored here — the probe can't drift out of sync with
+// the real backends. (That drift previously broke the panel's relevance dimming
+// when the build-step vocabulary was added but not taught to the probe.) The
+// validating probe DOES need an allowlist, so it takes one from kernel.js's op
+// lists, which test/kernel-contract.test.js pins to both backend implementations.
+import {
+  OCCT_ONLY_OPS, KERNEL_OPS, KERNEL_OPTIONAL_OPS,
+  SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS,
+} from "./kernel.js";
+import { KERNEL_OP_SPECS, SOLID_OP_SPECS, isPlainOptions } from "./op-options.js";
 import { resolveDerived } from "../derive.js";
 
 const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
 
-export function createProbeKernel() {
-  const used = new Set();
-  const note = (name) => used.add(name);
+// The probe returns ONE chainable handle for every non-query op, so it cannot tell a
+// Solid from a Shape2D — k.box() and k.shape2d() yield the same object. The solid-scope
+// allowlist is therefore the union of all three surfaces: deliberately permissive, so
+// it never false-positives on an error-severity rule.
+const KERNEL_ALLOWED = new Set([...KERNEL_OPS, ...KERNEL_OPTIONAL_OPS]);
+const SOLID_ALLOWED = new Set([...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_OPS]);
+
+export const MAX_PROBE_OPS = 100000;
+
+// Thrown to unwind a runaway build. Never escapes runValidatingProbe.
+export class ProbeRunawayError extends Error {
+  constructor(message) { super(message); this.name = "ProbeRunawayError"; }
+}
 
-  // Catch-all proxies: any method records its name and returns the chainable solid
-  // proxy, EXCEPT the queries below, which return realistic dummy values the build may
-  // read. Using a Proxy (rather than a hand-listed allowlist) means new kernel/solid
-  // methods never have to be mirrored here — the probe can't drift out of sync with the
-  // real backends. (That drift previously broke the panel's relevance dimming/hiding when
-  // the build-step vocabulary was added but not taught to the probe.)
+// Shared proxy construction. `onCall(scope, op, args)` observes every op; queries
+// return realistic dummy values the build may read.
+function makeProbe(onCall) {
   const solidQueries = {
     boundingBox: () => ({ min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }),
     volume: () => 1,
@@ -29,24 +51,101 @@ export function createProbeKernel() {
     cleanup: () => {},
   };
 
-  // `ignore` keeps the proxy from masquerading as a thenable/internal handle: symbols,
-  // `then` (so it's never await-unwrapped), and `_`-prefixed internals resolve to
-  // undefined rather than a chainable op.
-  const ignore = (key) => typeof key !== "string" || key === "then" || key[0] === "_";
+  // `ignore` keeps the proxy from masquerading as a thenable/internal/serializable
+  // handle: symbols, `then` (so it's never await-unwrapped), `_`-prefixed internals,
+  // and `toJSON` all resolve to undefined rather than a chainable op. `toJSON` matters
+  // because a handle nested inside an options object (the normal calling convention,
+  // e.g. `k.extrude({ profile: someShape, h: 5 })`) isn't caught by the `describe()`
+  // identity check below — that only sees the top-level options object, not the
+  // nested handle — so `JSON.stringify` walks into it and probes for `toJSON` per the
+  // spec. Without this, that probe would be recorded as a real op and then flagged as
+  // an unknown one.
+  const ignore = (key) => typeof key !== "string" || key === "then" || key === "toJSON" || key[0] === "_";
 
-  const opProxy = (queries) => new Proxy({}, {
+  // A query (boundingBox, volume, toMesh, …) must count against `onCall`'s ceiling
+  // exactly like any other op — returning `queries[key]` directly here used to let
+  // every query bypass the counter entirely, so a query-only loop (`for(;;)
+  // s.volume()`) never tripped MAX_PROBE_OPS and hung forever. Wrap it the same
+  // way as the chaining branch below: observe the call, then run the real query.
+  const opProxy = (queries, scope) => new Proxy({}, {
     get(_t, key) {
       if (ignore(key)) return undefined;
-      if (key in queries) return queries[key];
-      return (..._args) => { note(key); return proxy; };
+      if (key in queries) return (...args) => { onCall(scope, key, args); return queries[key](...args); };
+      return (...args) => { onCall(scope, key, args); return proxy; };
     },
   });
 
-  const proxy = opProxy(solidQueries);   // a solid handle: every op chains back to itself
-  const kernel = opProxy(kernelQueries); // factory ops (cylinder/box/prism/…) return a solid
+  const proxy = opProxy(solidQueries, "solid");   // a solid handle: every op chains back to itself
+  const kernel = opProxy(kernelQueries, "kernel"); // factory ops (cylinder/box/prism/…) return a solid
+  return { kernel, proxy };
+}
+
+export function createProbeKernel() {
+  const used = new Set();
+  const { kernel } = makeProbe((_scope, key) => used.add(key));
   return { kernel, used };
 }
 
+export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
+  const calls = [];
+  const issues = [];
+  const used = new Set();
+  let count = 0;
+  let solidProxy = null;
+
+  // Args are recorded as strings so two probe runs can be compared for determinism.
+  // The chainable handle is a single shared object, so identity is enough to spot it —
+  // and checking identity FIRST matters, because JSON.stringify would trip its traps.
+  const describe = (a) => {
+    if (a === solidProxy) return "<solid>";
+    if (typeof a === "function") return "<fn>";
+    try { return JSON.stringify(a) ?? String(a); } catch { return "<unserializable>"; }
+  };
+
+  const onCall = (scope, op, args) => {
+    if (++count > maxOps) throw new ProbeRunawayError(`build exceeded ${maxOps} kernel operations`);
+    used.add(op);
+    const allowed = scope === "kernel" ? KERNEL_ALLOWED : SOLID_ALLOWED;
+    if (!allowed.has(op)) issues.push({ kind: "unknown-op", scope, op });
+    // Validate ONLY the options form — the normative rule (KERNEL-CONTRACT.md
+    // "Calling convention") is that a call is options form when it receives exactly
+    // one plain-object argument. Legacy positional calls have no options contract to
+    // check against. We run `toArgs` (key + required validation) but never the spec's
+    // separate `check` hook: `check` inspects real geometry (revolve's calls
+    // boundingBox() on its profile), which is meaningless against a proxy.
+    const specs = scope === "kernel" ? KERNEL_OP_SPECS : SOLID_OP_SPECS;
+    if (specs[op] && args.length === 1 && isPlainOptions(args[0])) {
+      try { specs[op].toArgs(args[0]); }
+      catch (e) { issues.push({ kind: "invalid-options", scope, op, message: e?.message || String(e) }); }
+    }
+    calls.push({ scope, op, args: args.map(describe) });
+  };
+
+  const { kernel, proxy } = makeProbe(onCall);
+  solidProxy = proxy;
+  return { kernel, calls, issues, used };
+}
+
+/**
+ * Execute every sub-part's build() against a validating probe.
+ * Never throws: a build error becomes an entry in `throws`, a runaway sets `runaway`.
+ */
+export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {}) {
+  const probe = createValidatingProbe({ maxOps });
+  const throws = [];
+  let runaway = false;
+  for (const [name, sp] of Object.entries(part?.parts ?? {})) {
+    if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
+    try {
+      sp.build(probe.kernel, p, d);
+    } catch (e) {
+      if (e instanceof ProbeRunawayError) { runaway = true; break; }
+      throws.push({ subpart: name, message: e?.message || String(e) });
+    }
+  }
+  return { calls: probe.calls, issues: probe.issues, used: probe.used, throws, runaway };
+}
+
 export function detectBackend(part, params = {}) {
   if (part.meta?.backend) return part.meta.backend;
   const p = { ...part.defaults, ...params };

package/src/framework/lint/finding.js

@@ -0,0 +1,20 @@
+// Finding constructors. The shape mirrors the diagnostics contract that verify's
+// checks already satisfy (docs/AUTHORING-PARTS.md "The diagnostics contract"):
+// a self-contained `hint` on every finding, plus an optional stable ERROR-PATTERNS.md
+// `pattern` id. Verify's [x,y,z] `location` is replaced by `path`, an accessor path
+// into the PartDefinition — nothing parses it, it is for navigation only.
+const make = (severity) => (rule, message, hint, path = "", pattern) => ({
+  rule, severity, message, hint, path, ...(pattern ? { pattern } : {}),
+});
+
+// error → the part is PROVABLY broken: it cannot behave as authored, whether or
+// not that surfaces as a thrown exception. A dead control (control-key-not-in-
+// defaults), a view that renders nothing (part-view-unknown), or a verify
+// expectation that's silently dropped so its gate never runs (verify-unknown-
+// subpart) build/measure/verify cleanly today and still earn error — the defect
+// is real even though nothing throws. Because `measure` gates on this tier, a
+// part with one of these silent defects now exits non-zero where it previously
+// didn't; that's the point, not a regression.
+export const err = make("error");
+// warning → suspicious or lossy, but the part behaves as authored.
+export const warn = make("warning");

package/src/framework/lint/index.js

@@ -0,0 +1,114 @@
+// partforge/lint — static PartDefinition validation. Pure: no I/O, no async, and
+// (load-bearing) an import closure that never reaches three / manifold-3d / replicad,
+// so this runs unchanged in Node, a browser sandbox iframe, and Deno. The purity
+// guarantee is enforced by test/lint-purity.test.js — read it before adding an import.
+//
+// A rule is { id, run(ctx) → Finding[] }, one rule object per finding id, so the
+// registry doubles as the documented rule catalog. Rules are cheap and parts are
+// tiny; clarity beats sharing a walk between rules.
+import { resolveDerived } from "../derive.js";
+import { err, warn } from "./finding.js";
+import { SHAPE_RULES } from "./rules-shape.js";
+import { SCHEMA_RULES } from "./rules-schema.js";
+import { runValidatingProbe } from "../geometry/probe.js";
+import { BUILD_RULES } from "./rules-build.js";
+import { VERIFY_RULES, resolveExpect } from "./rules-verify.js";
+
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES];
+
+// Every rule runs inside a guard. lintPart is called on a user-facing hosted path
+// (partforge-cloud's sandbox), and a linter that takes down the preview it exists to
+// protect is worse than no linter — so a throwing rule becomes a WARNING, never an
+// error, and never blocks a part that would otherwise have built.
+export function runRules(rules, ctx) {
+  const out = [];
+  for (const rule of rules) {
+    try {
+      const found = rule.run(ctx);
+      if (Array.isArray(found)) out.push(...found);
+    } catch (e) {
+      out.push(warn("internal-rule-error",
+        `lint rule "${rule.id}" threw: ${e?.message || String(e)}`,
+        "This is a partforge bug rather than a problem with your part; every other rule still ran. Please report it with the part that triggered it."));
+    }
+  }
+  return out;
+}
+
+// Build the shared context. A throwing derive() must not abort the lint — the
+// throw is captured as `deriveError` (for Group 3's `derive-throws` rule) and `d`
+// falls back to {}, so Groups 1/2/4 remain useful without derived values.
+//
+// Building `p` can itself throw — `part.defaults` may be a getter that throws, or
+// `part.defaults` / `params` may be a Proxy whose `ownKeys` trap throws (the spread
+// below walks own keys) — so that construction gets the same never-escapes
+// treatment as derive(): fall back to `{}` rather than let a hostile/broken input
+// take down lintContext (and, by extension, lintPart — see its own guard below).
+// The failure is also captured as `pError`, mirroring `deriveError`, so lintPart
+// can still surface it as a real finding instead of silently linting against an
+// empty `{}` params object as if nothing were wrong.
+export function lintContext(part, params) {
+  let p;
+  let pError = null;
+  try { p = { ...(part?.defaults ?? {}), ...(params ?? {}) }; }
+  catch (e) { p = {}; pError = e?.message || String(e); }
+  let d = {};
+  let deriveError = null;
+  try { d = resolveDerived(part ?? {}, p) ?? {}; } catch (e) { d = {}; deriveError = e?.message || String(e); }
+  let cached = null;
+  const probe = () => (cached ??= runValidatingProbe(part, p, d));
+  const probeAgain = () => runValidatingProbe(part, p, d);
+  // Group 4's several rules all need `verify.expect` resolved; `expect` may be a
+  // user-supplied function, so — same reasoning as `probe` above — resolve it once
+  // per lint pass and share it, rather than letting each rule invoke it again and
+  // risk a cascading double-report from a function that only throws sometimes.
+  let cachedExpect = null;
+  const resolveExpectOnce = () => (cachedExpect ??= resolveExpect(part?.verify, p, d));
+  return { part, p, d, pError, deriveError, probe, probeAgain, resolveExpectOnce };
+}
+
+/**
+ * Lint a PartDefinition. Never throws.
+ * @param {object} part   the default-exported PartDefinition
+ * @param {{params?: object}} [opts]  params layered over part.defaults for the probe pass
+ * @returns {{ok: boolean, errors: object[], warnings: object[]}}
+ */
+export function lintPart(part, opts) {
+  // `opts` is defaulted here, not via `= {}` on the parameter, because a default
+  // parameter only fires on `undefined` — a caller passing `lintPart(part, null)`
+  // (a plausible downstream-harness call) would otherwise throw destructuring
+  // `{ params }` out of `null` before this function's body ever runs.
+  const { params } = opts ?? {};
+  // lintContext already guards its own internals (see its comment above), but it
+  // is user-authored data all the way down — wrap the call itself too, so a
+  // failure mode neither of us has thought of still degrades to a report instead
+  // of an escaping throw. `lintPart` must never throw; that guarantee is a bigger
+  // deal than any one finding.
+  let ctx;
+  try {
+    ctx = lintContext(part, params);
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [err("lint-context-error",
+        `partforge/lint could not build a lint context: ${e?.message || String(e)}`,
+        "This part is too malformed for lint to analyze safely — make sure `defaults`, `params`, and `verify`/`derive` are plain, side-effect-free data rather than throwing getters or hostile Proxies.",
+        "")],
+      warnings: [],
+    };
+  }
+  const findings = runRules(RULES, ctx);
+  // `p` (params merged from `defaults`) failed to build — every rule still ran
+  // against the `{}` fallback (each guarded individually by runRules), but the
+  // part is provably broken independent of whatever those rules happened to
+  // notice, so report it directly rather than relying on incidental fallout.
+  if (ctx.pError) {
+    findings.push(err("lint-context-error",
+      `partforge/lint could not read \`defaults\`/\`params\`: ${ctx.pError}`,
+      "Make sure `defaults` and any `params` passed to lintPart are plain, side-effect-free data rather than a throwing getter or a hostile Proxy.",
+      ""));
+  }
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warning");
+  return { ok: errors.length === 0, errors, warnings };
+}