partforge 0.76.0 → 0.78.0

package/bin/cli.js

@@ -6,8 +6,8 @@
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
-import { resolve, dirname } from "node:path";
-import { writeFileSync, mkdirSync } from "node:fs";
+import { resolve, dirname, basename } from "node:path";
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { detectBackend } from "../src/framework/backend-select.js";
 import { fontsFor } from "../src/framework/fonts.js";
 import { viewAnimations, evaluate, cueAt } from "../src/framework/animation.js";
@@ -15,6 +15,8 @@ import { bootOcctKernel } from "../src/testing/occt.js";
 import { bootManifoldKernel } from "../src/testing/manifold.js";
 import { measure } from "../src/framework/oracle/measure.js";
 import { verify } from "../src/framework/oracle/verify.js";
+import { describe as describeMesh } from "../src/framework/oracle/describe.js";
+import { compactDescribe } from "../src/framework/oracle/describe/report.js";
 import { renderViews } from "../src/testing/render.js";
 import {
   createPickServer, requestPicks, formatPickResult,
@@ -25,7 +27,7 @@ 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 <lint|measure|render|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|describe|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
@@ -77,6 +79,21 @@ async function loadPart(partPath, usage) {
   return part;
 }
 
+// The source rules (group 9) read the part's TEXT, which `loadPart` never sees —
+// it imports the module, and evaluation is exactly what erases the defects those
+// rules exist for (`13 / 3` is just a number by then). The entry module's own file
+// is all we hand over: following relative imports is a deliberate non-goal, and a
+// missing/unreadable file simply leaves `sources` off, which turns the group into
+// a no-op rather than failing the command.
+const readSources = (partPath) => {
+  try {
+    const path = basename(partPath);
+    return { files: { [path]: readFileSync(resolve(process.cwd(), partPath), "utf8") }, entrypoint: path };
+  } catch {
+    return undefined;
+  }
+};
+
 // Pass the part's declared fonts through, mirroring the worker path (jobs.js) —
 // otherwise a part using a named font builds in the browser but dies headlessly
 // with `text2d: unknown font …`. A function-form `fonts` is resolved against
@@ -102,7 +119,8 @@ const commands = {
     try {
       const part = await loadPart(partPath, usage);
       const params = flags.params ? JSON.parse(flags.params) : undefined;
-      const report = lintPart(part, { params });
+      const sources = readSources(partPath);
+      const report = lintPart(part, { params, sources });
       if (!flags.json) printLint(report);
       if (flags.out) {
         mkdirSync(dirname(resolve(flags.out)), { recursive: true });
@@ -131,7 +149,7 @@ const commands = {
       // 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);
+        const lint = lintPart(part, { sources: readSources(partPath) });
         if (!lint.ok) {
           if (flags.json) console.log(JSON.stringify({ ok: false, lint }, null, 2));
           else printLint(lint);
@@ -170,6 +188,51 @@ const commands = {
     }
   },
 
+  async describe(args) {
+    const usage = "usage: partforge describe <part-module#importName> [--surfaces] [--json] [--budget N] [--out <file>]";
+    const { values: flags, positionals: [target] } = parse(args, {
+      surfaces: { type: "boolean" },
+      json: { type: "boolean" },
+      budget: { type: "string" },
+      out: { type: "string" },
+    }, usage);
+    if (!target) die(usage);
+    // `part.js#importName` — describe reads a FILE, and a file only reaches the kernel
+    // through a part's `imports` declaration, so the part is how we find it. A bare mesh
+    // path is deliberately not accepted in v1: it would need its own resolver, its own
+    // format sniffing, and its own unit assumptions, all of which the import pipeline
+    // already owns.
+    const [partPath, importName] = target.split("#");
+    if (!importName) die(`describe needs an import name: <part-module>#<importName>\n${usage}`);
+    try {
+      const part = await loadPart(partPath, usage);
+      if (!part.imports?.[importName]) {
+        die(`describe: "${importName}" is not a declared import of ${partPath} ` +
+            `(have: ${Object.keys(part.imports ?? {}).join(", ") || "none"})`);
+      }
+      const kernel = await bootKernel(part);
+      const solid = kernel.import(importName);
+      const report = describeMesh(kernel, solid, {
+        name: importName,
+        digest: kernel._importDigest?.(importName) ?? null,
+        budget: flags.budget ? Number(flags.budget) : undefined,
+      });
+      if (flags.out) {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+      }
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      else printDescribe(report, { surfaces: !!flags.surfaces });
+      if (flags.out) console.log(`\nwrote ${flags.out}`);
+      // A closed-set error exits non-zero; LOW COVERAGE does not. Coverage is a finding
+      // the caller must be able to read, and an exit code that conflated the two would
+      // train an agent to discard exactly the reports it most needs to look at.
+      process.exit(report.error ? 1 : 0);
+    } catch (e) {
+      crash("describe", e, !!flags.json);
+    }
+  },
+
   async render(args) {
     const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>] " +
       "[--params <json>] [--animation <name>] [--at <t[,t…]>] [--step <index|label>]";
@@ -379,13 +442,94 @@ function printVerify(v) {
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
 
+// Human/agent-readable summary. Features, patterns, symmetry, score, residual — the
+// compact shape (spec §3.4), because a 24k-triangle part yields hundreds of surfaces and
+// dumping them buries the reader in the noise the oracle exists to remove. `--surfaces`
+// opts back in; `--json` always has everything. Reads the SAME compactDescribe() output
+// a model reads (not a hand-rolled subset), so what a human sees here and what an agent
+// sees over `--json` cannot drift apart.
+function printDescribe(report, { surfaces }) {
+  if (report.error) {
+    console.error(`describe: ${report.error}${report.detail ? ` — ${report.detail}` : ""}`);
+    return;
+  }
+  const c = compactDescribe(report);
+  if (c.warning) console.log(`\n!! ${c.warning}\n`);
+  console.log(`${c.source.name ?? "mesh"} — ${c.source.triangles} triangles, ` +
+              `${c.bounds.size.map((v) => v.toFixed(2)).join(" x ")} mm, ${c.frame.up} up`);
+  // The `share` hint lives HERE, at the point of use, not several lines below beside
+  // Score (fix round 2, IMPORTANT 1 — a prior version printed the full `score.note`
+  // paragraph under Score and it dominated the report: measured at 36-43% of a typical
+  // run's line count, the single largest visual element, bigger than the feature list,
+  // banners, and score line combined — burying findings instead of clarifying them). One
+  // line, next to the column it explains; the full note is still in `--json` unabridged
+  // (`buildScore` in report.js attaches it unconditionally — nothing lost there).
+  console.log(`\nFeatures (${c.features.length}):` +
+              (c.features.length ? `   share = fraction of part volume this feature ` +
+                `accounts for — a size measure, not certainty` : ""));
+  // `volumeShareReason` (fix round 2, IMPORTANT 2): `volumeShare: null` alone doesn't
+  // say whether this feature type is never proposed at all, was proposed but never
+  // reached before the search ran out of budget, or was reached and built but simply
+  // didn't win — three different signals to a rebuilder deciding what to do next. See
+  // describe.js's own comment on the field for the exact three-way split.
+  const REASON_LABEL = { "not-proposed": "not proposed", budget: "budget", rejected: "rejected" };
+  for (const f of c.features) {
+    const dim = f.diameter ?? f.radius ?? f.width ?? f.thickness ?? f.depth;
+    const snap = f.snapped?.diameter?.note ? `  [${f.snapped.diameter.note}]` : "";
+    const share = f.volumeShare != null
+      ? `${(100 * f.volumeShare).toFixed(1)}%`
+      : `n/a (${REASON_LABEL[f.volumeShareReason] ?? f.volumeShareReason ?? "unknown"})`;
+    console.log(`  ${f.id.padEnd(5)} ${f.type.padEnd(14)} ` +
+                `${dim != null ? dim.toFixed(3) : ""}`.padEnd(10) +
+                `share ${share}${snap}`);
+  }
+  if (c.patterns.length) {
+    console.log(`\nPatterns (${c.patterns.length}):`);
+    for (const p of c.patterns) {
+      console.log(`  ${p.id.padEnd(5)} ${p.type.padEnd(9)} x${p.counts.join("x")} ` +
+                  `pitch ${p.pitch.map((v) => v.toFixed(2)).join(", ")}  [${p.members.length} members]`);
+    }
+  }
+  if (c.symmetry.length) {
+    console.log(`\nSymmetry:`);
+    for (const s of c.symmetry) console.log(`  ${s.type} coverage ${s.coverage}`);
+  }
+  if (surfaces) {
+    console.log(`\nSurfaces (${report.surfaces.length}):`);
+    for (const s of report.surfaces) {
+      console.log(`  ${s.id.padEnd(5)} ${s.type.padEnd(9)} area ${s.area.toFixed(2)}`.padEnd(40) +
+                  `rms ${s.rms.toExponential(2)}`);
+    }
+  }
+  // TWO DIFFERENT NUMBERS, printed as two: explainedArea is how much of the mesh's
+  // SURFACE segmentation fitted to some primitive; explainedVolumeFraction is how much
+  // of the part's actual SHAPE the accepted features reconstruct. They can diverge
+  // totally — a dome segments to ~100% area and 0% volume, since a sphere is not a
+  // candidate-eligible feature type — so printing only one (or a blended "xor%") would
+  // hide exactly the gap the LOW COVERAGE banner above exists to catch. The wording here
+  // ("surface area explained" vs. "volume reconstructed") already carries that
+  // distinction; `score.note`'s full prose (this point, plus the volumeShare aside now
+  // covered at the Features header instead) stays JSON-only — fix round 2, IMPORTANT 1.
+  console.log(`\nScore: ${(100 * c.score.explainedArea).toFixed(1)}% surface area explained, ` +
+              `${(100 * c.score.explainedVolumeFraction).toFixed(1)}% volume reconstructed ` +
+              `(residual xor ${(100 * c.score.xorFraction).toFixed(2)}% of volume)`);
+  console.log(`Residual: ${(100 * c.residual.areaFraction).toFixed(2)}% of area in ` +
+              `${c.residual.regions.length} region(s)`);
+  const truncated = Object.entries(report.truncated ?? {}).filter(([, v]) => v).map(([k]) => k);
+  if (truncated.length) console.log(`Truncated (caps hit): ${truncated.join(", ")}`);
+}
+
 function printLint(r) {
   const all = [...r.errors, ...r.warnings, ...(r.notes ?? [])];
   if (all.length === 0) { console.log("lint: clean"); return; }
   console.log("lint:");
   for (const f of all) {
     const icon = f.severity === "error" ? "✗" : f.severity === "warning" ? "⚠" : "·";
-    console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
+    // A source-rule finding carries file+line — the only location a reader can
+    // open. Print it alongside the accessor path (which is `""` for a finding
+    // about a token anywhere in the file) rather than instead of it.
+    const at = f.file ? `  ${f.file}:${f.line ?? "?"}` : "";
+    console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}${at}`);
     console.log(`      ${f.message}`);
     console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
   }

package/docs/AUTHORING-PARTS.md

@@ -1494,6 +1494,166 @@ build: (k, p, d) => {
 
 **CLI:** `partforge measure|render|lint` work on an importing part exactly as on any other — the `imports` field resolves in the CLI's Node boot the same way `fonts` does, no extra flags.
 
+## Describing an imported mesh
+
+Before you write the parametric rebuild, ask the mesh itself what's in it: `partforge
+describe <part-module>#<importName>` reads an already-declared import (`k.import`'s own
+name, not a bare file path — the `imports` field is how the file gets to a kernel at
+all, so it's how `describe` finds it too) and emits a semantic feature report — holes,
+bosses, pockets, extrusions, patterns, symmetry — rather than a triangle soup. On
+`import-demo.js`, whose `scan` import is a plain 20×14×8mm block:
+
+```
+$ npx partforge describe src/parts/import-demo.js#scan
+
+scan — 12 triangles, 20.00 x 14.00 x 8.00 mm, +Z up
+
+Features (1):   share = fraction of part volume this feature accounts for — a size measure, not certainty
+  f0    extrusion      8.000     share 100.0%
+
+Score: 100.0% surface area explained, 100.0% volume reconstructed (residual xor 0.00% of volume)
+Residual: 0.00% of area in 0 region(s)
+```
+
+**Two report shapes, and which one is authoritative.** `describe()` (`src/framework/
+oracle/describe.js`) returns the FULL report — every surface, every fitted edge, every
+feature at full precision — and that is the archive: `--json` prints it whole, and
+`--out <file>` writes it whole. `compactDescribe()` (`src/framework/oracle/describe/
+report.js`) derives a second, smaller shape from it — features, patterns, symmetry,
+score, residual, and the suggested rebuild, with `surfaces`/`edges` reduced to counts —
+and that is what a model reads, and what the terminal printer above reads too: **the
+same `compactDescribe()` output**, not a hand-rolled subset, so what a human sees in the
+default summary and what an agent gets from a cloud turn cannot drift apart. The full
+report is authoritative for the facts (a fitted surface's rms, an edge's exact radius);
+the compact report is authoritative for what's worth paying attention to.
+
+**Computed once, reused for the session.** `describe` depends on nothing but the mesh's
+own bytes — no part params, no derived state — so unlike `measure`/`verify` it never
+needs to re-run on every parameter edit. The worker keys its memo on the import's
+content digest (`kernel._importDigest(name)`), so re-describing the same file, or asking
+again mid-session while you iterate on the parametric rebuild, is free after the first
+call. The CLI doesn't carry a memo across process invocations — each `partforge
+describe` run is its own process — but within one browser session or one long-running
+tool loop, the mesh is segmented once.
+
+**`--surfaces` and `--json`, and why the default elides.** A hand-modelled block
+segments to six surfaces; a real 24k-triangle CAD export segments to hundreds. Printing
+every one of them by default would bury the two or three that actually matter under
+exactly the noise this oracle exists to remove — so the plain-text summary shows
+features, patterns, symmetry, score, and residual only. Pass `--surfaces` to add the
+surface table back (`s0 plane area … rms …`, one line per fitted patch); pass `--json`
+to get everything, always, structured — the mode an agent should default to over
+scraping the text summary. `--out <file>` writes the full report to disk independently
+of either flag, so you can capture it once and read it multiple ways.
+
+**Low coverage exits zero — it's a finding, not a failure.** A poor segmentation (a
+dome, a free-form scan, anything the four feature detectors can't reconstruct) is
+exactly the situation an agent most needs to see, not one that should make itself
+harder to see. `describe` treats "the shape isn't well explained" and "the command
+failed" as different questions: a `LOW COVERAGE` banner at the top of the summary (and
+`compactDescribe()`'s own `warning` field in `--json` output) is how a poor result
+announces itself, and the process still exits 0. Only a genuine closed-set error — the
+mesh couldn't be read or segmented at all — exits 1. Coverage is gated on the WORSE of
+two numbers, both always printed rather than blended into one: `explainedArea` (how much
+of the mesh's *surface* a fitted primitive accounts for) and `explainedVolumeFraction`
+(how much of the part's actual *shape* the accepted features reconstruct). They can
+diverge totally — a dome segments to ~100% surface area (it fits a sphere cleanly) and
+0% volume (a sphere isn't a candidate-eligible feature type for any detector) — so
+printing only one of them, or an average, would hide precisely the gap the banner exists
+to catch. Each feature's own score is named `volumeShare`, never "confidence": it is the
+fraction of the part's volume that feature accounts for — a measure of *size* — so a
+small-but-certain feature (a precisely-fitted 3mm hole in a large plate) legitimately
+reports a small share. Read a feature's fitted surface `rms`/`maxDev` (under `--surfaces`
+or `--json`) for an actual certainty signal. The one-line hint at the `Features (N):`
+header states the size-not-certainty point at its point of use; the longer explanation
+(`score.note` — both this and the `explainedArea`/`explainedVolumeFraction` distinction
+above, spelled out for a reader who never gets this far) stays `--json`-only, since
+printing it in full under `Score:` used to be the single largest visual element in every
+plain-text run — measured at 36-43% of a typical report's line count, bigger than the
+feature list, the banners, and the score line combined.
+
+**Why a null `volumeShare` isn't always the same story.** A feature can carry
+`volumeShare: null` for three different reasons, distinguished by its sibling field
+`volumeShareReason` (`--surfaces`/`--json`; the text view renders it as `share n/a
+(<reason>)`):
+
+- `"not-proposed"` — this feature TYPE is never turned into an acceptance candidate at
+  all. Fillets, chamfers, revolves and shells fall here today; they're still reported as
+  features, just not yet reconstructable through this pipeline.
+- `"budget"` — a candidate WAS proposed, but the search ran out of `--budget` before
+  reaching it. Raise `--budget` and re-describe; the feature may resolve to a real share
+  once given the chance.
+- `"rejected"` — a candidate was proposed, built, and evaluated, but never won a round
+  (`accept.js`'s `MIN_GAIN_FRACTION` gate, or simply never the best candidate available).
+  Raising `--budget` will not change this outcome — the feature genuinely doesn't fit
+  well enough to explain a meaningful share of the part.
+
+`"budget"` and `"rejected"` are the two that matter most to get right, and the
+distinction is real, not cosmetic: "try a bigger budget" and "this doesn't fit" are
+different next actions for whoever is rebuilding the part.
+
+**What `describe` reconstructs today, and what it doesn't.** The FACTS layer — surfaces,
+arcs, holes, dress-ups, sweeps, patterns, symmetry — covers the tool's full detection
+vocabulary; a feature can be *reported* there regardless of shape. The RECONSTRUCTION
+score (`explainedVolumeFraction`, and every accepted feature's own `volumeShare`) is
+narrower: `toCandidate` only proposes box and cylinder footprints as acceptance
+candidates today, so it currently reconstructs prismatic parts built from roughly fewer
+than eight box/cylinder features well, and does not yet reconstruct round bosses,
+revolves, fillets, chamfers, or shells — those are detected and reported (with
+`volumeShareReason: "not-proposed"`) but never turned into a candidate that could win
+volume back. Measured directly on this repo's own reference parts: `demo.js`
+reconstructs 65.7% of its volume, `filleted-box.js` 36.2%, `bracket.js` 23.6%, a plain
+tube 0.0%, and a hollow box 1.9%. The low-coverage banner fires on every one of these, so
+nothing here is misreported — but a low `explainedVolumeFraction` on a turned or
+feature-dense part means **"not yet reconstructable by this tool"**, not "not
+understood" or "broken." Read the FACTS (features, surfaces, patterns) as the ground
+truth regardless of the volume score; read the volume score as a measure of how much of
+that ground truth also comes with a working, boolean-verified rebuild recipe.
+
+**Closed error set.** Anything short of a programming mistake comes back as
+`{error: "<code>", detail, diagnostic}` rather than a thrown exception — a CLI or an
+agent can act on a code far better than on a stack trace — and every code has an
+ERROR-PATTERNS.md entry:
+
+- `not-manifold` — the mesh still has open edges after repair; see
+  [ERROR-PATTERNS.md#describe-not-manifold](ERROR-PATTERNS.md#describe-not-manifold).
+- `too-large` — over the 400,000-triangle segmentation ceiling; see
+  [ERROR-PATTERNS.md#describe-too-large](ERROR-PATTERNS.md#describe-too-large).
+- `empty` — the mesh has zero triangles; see
+  [ERROR-PATTERNS.md#describe-empty](ERROR-PATTERNS.md#describe-empty).
+- `unreadable` — `solid.toMesh()` itself threw; see
+  [ERROR-PATTERNS.md#describe-unreadable](ERROR-PATTERNS.md#describe-unreadable).
+
+`not-manifold` and `empty` describe real states `describe()` itself checks for and can
+return through any caller that hands it a `Solid` directly, but through the CLI they are
+largely theoretical: `kernel.import()`'s own registration validation rejects an empty or
+a wide-open (non-manifold) mesh *before* a `Solid` ever exists to describe, so
+`partforge describe` on such a file fails earlier, as a generic import error (the
+`crash()` path every other verb shares — `describe: import "x": mesh is not a solid
+after repair…`) rather than as a structured `{error: "not-manifold"}` / `{error:
+"empty"}` report. See
+[ERROR-PATTERNS.md#import-mesh-not-solid](ERROR-PATTERNS.md#import-mesh-not-solid) for
+that failure. `describe-unreadable`'s own ERROR-PATTERNS entry already draws this same
+line for its own code (a `k.import` parse failure is a *different*, separately-thrown
+error, not `describe-unreadable`); this is the general version of that point.
+
+A `budget-exceeded` report (the acceptance loop ran out of boolean attempts before the
+residual converged) is not one of these — it's a `warning` on an otherwise-valid report,
+same tier as low coverage, not a reason to exit non-zero; raise `--budget` and re-run.
+`compactDescribe()` surfaces it exactly where the low-coverage banner lives, and shows
+both together if a report happens to earn both — an exhausted budget is exactly the kind
+of run that also leaves coverage low, and neither warning is allowed to mask the other.
+See [ERROR-PATTERNS.md#describe-budget-exceeded](ERROR-PATTERNS.md#describe-budget-exceeded).
+
+**The loop this completes.** `describe` exists to feed a specific workflow, the one
+"Importing geometry" above sets up and this closes: `describe` the import to get its
+feature list and a proposed reconstruction (`suggestion` in the full report); write a
+parametric part from that proposal; bind the rebuild's sub-part to the import with
+`reference: "scan"`; and let `verify`'s `ref*` gates (`refXorVolume`, `refVolumeDeltaPct`,
+`refBboxDelta` — "The `reference` field and the deviation gate", above) hold the rebuild
+to the scan on every future `measure`/`verify` run, long after the one-time `describe`
+call that suggested it. `describe` proposes; `verify` keeps you honest.
+
 ---
 
 ## Wiring a part into a runnable app
@@ -1878,6 +2038,16 @@ import { lintPart } from "partforge/lint";
 const { ok, errors, warnings } = lintPart(part, { params });
 ```
 
+`lintPart(part, { sources })` optionally takes the part's own source files
+(`{ files: { path: text }, entrypoint }` — `entrypoint` names the file holding the
+`PartDefinition`, defaulting to the first key) and unlocks a ninth rule group that
+reads the source itself, catching the defects evaluation erases. The CLI passes the
+module's own file automatically, so `partforge lint`/`measure` always run it; a
+programmatic caller that omits `sources` (or hands over a malformed one) just gets
+no findings from that group. Source findings carry `file` and `line` on top of the
+standard shape, and `SOURCE_RULE_IDS` names them — a host that gates rendering on
+lint errors uses it to keep them reported but non-blocking.
+
 `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
@@ -2056,6 +2226,32 @@ control that the control's own `allow` list would refuse — at build time it's
 swapped for `defaults[key]`, i.e. itself, so the part boots with no usable
 font; use a source `allow` accepts, or widen `allow`) (warning).
 
+**Source rules** — the ninth group, which runs only when the caller hands over
+`sources` (above) — `control-default-not-literal` (a control's `defaults` entry is
+written as something other than a plain literal: an expression like `13 / 3`, an
+array or object, a template literal, a `0x10`/`1_000` spelling. Hosts persist a
+panel edit by rewriting that value's span in the source, so a spelling the
+rewriter cannot read means the user's edit is silently lost on reload — write a
+plain decimal/string/boolean literal, or move the computation into `derive()`)
+(error); `impure-source-token` (the source contains `Math.random`, `Date.now`,
+`performance.now`, or an argless `new Date()` — replace it with a parameter or a
+`derive()` output) (warning). Only a default a **visible** control is actually
+**bound** to is checked: an unbound non-primitive default (a lookup table, an
+array of hole positions) is never rewritten by a panel save and stays legal and
+unflagged, and so is the default of a statically hidden control (`hidden: true`
+on the control, or on an enclosing group or section) — it renders no widget, so
+there is no panel edit to lose, and `hidden: true` is the documented idiom for an
+internal constant. A `when`-conditioned control is *not* hidden — it can appear,
+so its default is checked.
+`impure-source-token` is warning-tier because the behavioral
+`nondeterministic-build` probe stays the error authority on impurity — the source
+scan is the wider net that also catches an impure value stable within one probe
+pass. It scans `.js`/`.mjs` files only (prose in a `README.md` is not a build),
+and code only within them (comments and string/template *interiors* are blanked
+first), so an impurity token inside a `${…}` interpolation is not seen. It emits
+one finding per (file, token) pair, carrying the occurrence count and the first
+occurrence's line, rather than one per occurrence.
+
 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.
 

package/docs/ERROR-PATTERNS.md

@@ -601,6 +601,48 @@ between the Manifold preview and the OCCT STEP export.
 
   The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
 
+## describe-not-manifold
+
+- **Symptom:** `describe` returns `{"error": "not-manifold"}`.
+- **Cause:** The mesh still has open edges after vertex-merge and winding repair, so it does not bound a solid and acceptance cannot diff against it.
+- **Fix:** Repair the mesh before describing it — Meshmixer, `meshlabserver`, or the slicer's own repair. `describe` will not repair geometry it was asked to report on; silently sealing a hole would make the report a description of a mesh the user does not have.
+
+## describe-too-large
+
+- **Symptom:** `{"error": "too-large"}` naming a triangle count.
+- **Cause:** Above 400,000 triangles the segmentation pass stops being usable in an interactive loop.
+- **Fix:** Decimate first. A CAD-exported STL re-exported at a coarser chord tolerance loses nothing the describer uses; the feature vocabulary reads surfaces, not facets.
+
+## describe-empty
+
+- **Symptom:** `{"error": "empty"}`.
+- **Cause:** The mesh has zero triangles — usually an import that resolved to an empty file, or a `k.import` name that registered as an error entry.
+- **Fix:** Check the `imports` source actually resolves. See [import-unknown-name](#import-unknown-name).
+
+## describe-budget-exceeded
+
+- **Symptom:** The report carries `warning: "budget-exceeded"` and `score.xorFraction` is higher than expected.
+- **Cause:** The acceptance loop hit its boolean budget before the residual converged. The report is partial but honestly scored — not wrong, just incomplete.
+- **Fix:** Raise `--budget`, or accept the partial description. A part needing far more than the default is usually one where a residual region is being attacked by many near-identical candidates; check `residual.regions` first.
+
+## describe-unreadable
+
+- **Symptom:** `{"error": "unreadable"}`.
+- **Cause:** `solid.toMesh()` threw rather than returning geometry — a corrupt or otherwise unrepresentable solid.
+- **Fix:** Confirm the source file parses cleanly upstream (`k.import` itself throws separately for an unparseable STL/3MF/STEP — see [import-unknown-name](#import-unknown-name)); re-export the file if the kernel cannot read back what it just built. STL is assumed to be in millimetres (the format carries no unit metadata) — see the import section of AUTHORING-PARTS.md.
+
+## control-default-not-literal
+
+- **Symptom:** A control works live — the slider moves, the geometry updates — but the user's panel edits are gone when the part is reopened. Nothing throws anywhere.
+- **Cause:** The control's `defaults` entry is written as something other than a plain literal — an expression (`13 / 3`), an array or object, a template literal, a hex/`1_000` spelling. Hosts persist a panel edit by rewriting that value's span in the source, so a value the rewriter cannot read is skipped and the edit is silently lost. The evaluated-object lint cannot see this (`13 / 3` evaluates to an ordinary number); only the source says.
+- **Fix:** Write the computed value as a plain decimal/string/boolean literal, or move the computation into `derive()`. `lintPart(part, { sources })` and the CLI report this as the error `control-default-not-literal` with file and line. Only a **visible** control's default is checked — a statically hidden one (`hidden: true` on the control, group or section) renders no widget, so there is no panel edit to lose, and an expression there is legitimate. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Linting" (Rule catalog → Source rules).
+
+## impure-source-token
+
+- **Symptom:** The preview shows stale geometry after a parameter edit, or a part behaves differently across rebuilds with identical params — often intermittent.
+- **Cause:** The source contains `Math.random`, `Date.now`, `performance.now`, or an argless `new Date()`. A build must be a pure function of `(k, p, d)`; the memoizing kernel hashes inputs, so an impure value silently serves stale geometry (see impure-build-stale-preview, above). The behavioral lint probe catches impurity only when it changes the recorded call sequence between two probe runs; a value stable within one pass escapes it, which is why the source scan warns on the token itself.
+- **Fix:** Replace the impure value with a parameter or a `derive()` output. `new Date(0)` and other argument-carrying forms are deterministic and not flagged; only `.js`/`.mjs` files are scanned, so the same words in a `README.md` are prose. One finding is emitted per (file, token) pair, carrying the occurrence count and the first occurrence's line. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Caching & determinism".
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.76.0",
+  "version": "0.78.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",

package/src/framework/jobs.js

@@ -15,6 +15,15 @@ import { verify } from "./oracle/verify.js";
 import { buildView } from "./oracle/build.js";
 import { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./oracle/silhouette.js";
 import { matchViews } from "./oracle/match.js";
+import { describe as describeMesh, describeMemo } from "./oracle/describe.js";
+import { compactDescribe } from "./oracle/describe/report.js";
+
+// One describe memo for the life of this worker. Deliberately NOT swept on setPart the
+// way solid-cache is: describe is pure in the mesh bytes (spec §4.1), so an edit can
+// never invalidate it, and dropping it on rebind would throw away the single most
+// expensive thing this worker computes for no reason at all. Keyed by content digest, so
+// a genuinely changed file misses correctly.
+const DESCRIBE_MEMO = describeMemo();
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -375,6 +384,28 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
       if (match) report.match = match;
       post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
+    } else if (msg.type === "describe") {
+      // Semantic description of an IMPORTED mesh — not of the built part. The two are
+      // different questions: `inspect` asks "what did this source build?", `describe`
+      // asks "what is this file?". describe never touches the part's own geometry, which
+      // is why it takes an import name rather than a view.
+      //
+      // Manifold only, and not by choice on this path: mesh imports on OCCT are never
+      // attempted, so a describe job posted to an OCCT worker is a routing bug, not a
+      // fallback opportunity. It surfaces as an ordinary error rather than a reroute.
+      const solid = kernel.import(msg.importName);      // throws on an unknown name
+      // `_importDigest` is the backend's existing underscore side-channel (KERNEL-CONTRACT
+      // "Conformance classes") — the same digest already folded into every import cache key.
+      const digest = kernel._importDigest?.(msg.importName) ?? null;
+      const full = describeMesh(kernel, solid, {
+        name: msg.importName,
+        digest,
+        budget: msg.budget,
+        memo: DESCRIBE_MEMO,
+      });
+      // The compact shape is derived, never memoised separately: one memo entry per
+      // mesh, two views of it, no way for the two to drift.
+      post({ type: "describe-report", report: msg.compact ? compactDescribe(full) : full });
     }
   } catch (err) {
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the

package/src/framework/lint/index.js

@@ -17,8 +17,32 @@ import { ANIMATION_RULES } from "./rules-animations.js";
 import { PLACE_RULES } from "./rules-place.js";
 import { IMPORT_RULES } from "./rules-imports.js";
 import { FONT_RULES } from "./rules-fonts.js";
+import { SOURCE_RULES } from "./rules-source.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...SOURCE_RULES];
+
+// A usable sources input, or null. Deliberately forgiving: lintPart's callers
+// include hosted paths handing over user/LLM-authored trees, so a malformed
+// shape means "no source rules", never a throw. Non-string file values are
+// dropped per entry rather than voiding the whole map.
+function normalizeSources(sources) {
+  if (!sources || typeof sources !== "object") return null;
+  const rawFiles = sources.files;
+  if (!rawFiles || typeof rawFiles !== "object") return null;
+  // Null-prototype so a file literally keyed `__proto__` is KEPT as an own
+  // property: `{}["__proto__"] = text` would set the prototype instead, quietly
+  // dropping that file from the scan while still counting toward `any`.
+  const files = Object.create(null);
+  let any = false;
+  for (const [path, text] of Object.entries(rawFiles)) {
+    if (typeof text !== "string") continue;
+    files[path] = text;
+    any = true;
+  }
+  if (!any) return null;
+  const entrypoint = typeof sources.entrypoint === "string" ? sources.entrypoint : Object.keys(files)[0];
+  return { files, entrypoint };
+}
 
 // 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
@@ -74,7 +98,9 @@ export function lintContext(part, params) {
 /**
  * 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
+ * @param {{params?: object, sources?: {files?: Record<string, string>, entrypoint?: string}}} [opts]
+ *   `params` are layered over part.defaults for the probe pass; `sources` is the part's own
+ *   source text, which unlocks the source rules (Group 9) — omit it and lint behaves as before.
  * @returns {{ok: boolean, errors: object[], warnings: object[], notes: object[]}}
  */
 export function lintPart(part, opts) {
@@ -82,7 +108,7 @@ export function lintPart(part, opts) {
   // 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 ?? {};
+  const { params, sources } = 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
@@ -102,6 +128,14 @@ export function lintPart(part, opts) {
       notes: [],
     };
   }
+  // Deliberately its OWN guard, outside the lintContext try above: a malformed
+  // `sources` input means "no source rules", never a broken part. `sources` is
+  // caller-supplied data (a throwing `files`/`entrypoint` getter, a Proxy whose
+  // `ownKeys` trap throws), and folding it into the block above would turn that
+  // into a `lint-context-error` — an id that is NOT in SOURCE_RULE_IDS, so a
+  // host filtering source findings out to keep them non-blocking would instead
+  // refuse to render a part that builds fine.
+  try { ctx.sources = normalizeSources(sources); } catch { ctx.sources = null; }
   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