partforge 0.41.0 → 0.45.0

package/src/framework/pick-request/server.js

@@ -1,26 +1,155 @@
 // src/framework/pick-request/server.js
 // The Node side of request-a-pick: an http+SSE server holding one active batch,
 // a blocking CLI client (requestPicks), and CLI output formatting. 127.0.0.1 only.
+//
+// Threat model. While this is listening, any page the developer visits can reach
+// http://127.0.0.1:<port> from their browser. Everything here exists to make that
+// harmless:
+//   * a per-process bearer token gates every route (the browser gets it through the
+//     app URL, the CLI through ~/.partforge/pick-<port>.token),
+//   * Origin is never reflected unless it is loopback, and `*` is never emitted, so
+//     a foreign page cannot read the SSE stream or any response,
+//   * Host must name loopback, so a rebound DNS name pointing at 127.0.0.1 is refused,
+//   * bodies are capped, and
+//   * /resolve payloads are shape-checked and stripped of control characters before
+//     they can reach the agent's stdout — that print is a prompt-injection channel.
 import { createServer, request as httpRequest } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createBatch, view, resolve, cancel, timeout, result } from "./batch.js";
 import { formatSelection } from "../selection/format.js";
+import {
+  PICK_SERVER_DEFAULT_PORT, PICK_SERVER_DEFAULT_TIMEOUT_MS, PICK_SERVER_DEFAULT_HOST,
+  isLoopbackOrigin, isLoopbackHost,
+} from "./endpoint.js";
 
-const json = (res, code, obj, origin) => {
-  res.writeHead(code, { "content-type": "application/json", "access-control-allow-origin": origin || "*" });
+export {
+  PICK_SERVER_DEFAULT_PORT, PICK_SERVER_DEFAULT_TIMEOUT_MS, PICK_SERVER_DEFAULT_HOST,
+  PICK_SERVER_DEFAULT_URL,
+} from "./endpoint.js";
+
+const MAX_BODY_BYTES = 256 * 1024;   // no route needs more; anything bigger is abuse
+const MAX_SELECTION_CHARS = 16 * 1024;
+const MAX_STRING_CHARS = 512;
+const MAX_PARAM_KEYS = 200;
+const MAX_PROMPTS = 32;
+const MAX_PROMPT_CHARS = 2000;
+
+// Control characters (plus the Unicode line separators) are what let injected text
+// forge extra CLI lines in the agent's stdout. Fold them to spaces rather than drop
+// them, so "a\nb" cannot silently become the single token "ab".
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+export const sanitizeText = (s, max = MAX_STRING_CHARS) =>
+  String(s).replace(CONTROL_CHARS, " ").slice(0, max);
+
+export function mintPickToken() {
+  return randomBytes(32).toString("base64url");
+}
+
+const tokenMatches = (given, expected) => {
+  const a = Buffer.from(typeof given === "string" ? given : "");
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+};
+
+// EventSource cannot set headers, so the token must also be accepted in the query
+// string; POSTs prefer a header. Both are equally secret — the URL never leaves the
+// machine.
+const tokenFrom = (req, query) => {
+  const header = req.headers["x-pick-token"];
+  if (typeof header === "string" && header) return header;
+  const auth = req.headers.authorization;
+  if (typeof auth === "string" && /^bearer\s+/i.test(auth)) return auth.replace(/^bearer\s+/i, "").trim();
+  return query.get("token") ?? "";
+};
+
+const isVec3 = (v) => Array.isArray(v) && v.length === 3
+  && v.every((n) => typeof n === "number" && Number.isFinite(n));
+
+// Whitelist the Selection shape resolveSelection() produces. Unknown keys are dropped
+// rather than passed through: whatever survives here is printed to the agent, so the
+// set of things that can reach it must be closed, not open.
+function sanitizeSelection(selection) {
+  if (!selection || typeof selection !== "object" || Array.isArray(selection)) {
+    return { error: "selection must be an object" };
+  }
+  let encoded;
+  try { encoded = JSON.stringify(selection); } catch { return { error: "selection is not serialisable" }; }
+  if (!encoded || encoded.length > MAX_SELECTION_CHARS) return { error: "selection too large" };
+  if (typeof selection.subPart !== "string") return { error: "selection.subPart must be a string" };
+
+  const out = { subPart: sanitizeText(selection.subPart) };
+  for (const key of ["point", "normal"]) {
+    if (selection[key] === undefined) continue;
+    if (!isVec3(selection[key])) return { error: `selection.${key} must be 3 finite numbers` };
+    out[key] = [...selection[key]];
+  }
+  if (selection.params !== undefined) {
+    const p = selection.params;
+    if (!p || typeof p !== "object" || Array.isArray(p)) return { error: "selection.params must be an object" };
+    const keys = Object.keys(p);
+    if (keys.length > MAX_PARAM_KEYS) return { error: "selection.params has too many keys" };
+    out.params = {};
+    for (const k of keys) {
+      const v = p[k];
+      const ok = (typeof v === "number" && Number.isFinite(v)) || typeof v === "boolean" || v === null
+        || typeof v === "string";
+      if (!ok) return { error: `selection.params.${sanitizeText(k, 40)} must be a primitive` };
+      out.params[sanitizeText(k, 80)] = typeof v === "string" ? sanitizeText(v) : v;
+    }
+  }
+  if (selection.feature !== undefined) {
+    const f = selection.feature;
+    if (!f || typeof f !== "object" || Array.isArray(f) || typeof f.label !== "string") {
+      return { error: "selection.feature must be { label }" };
+    }
+    out.feature = { label: sanitizeText(f.label) };
+  }
+  return { selection: out };
+}
+
+function sanitizePrompts(prompts) {
+  if (!Array.isArray(prompts) || prompts.length === 0) return { error: "prompts must be a non-empty array" };
+  if (prompts.length > MAX_PROMPTS) return { error: "prompts must be a non-empty array of at most 32 strings" };
+  if (!prompts.every((p) => typeof p === "string")) return { error: "prompts must be a non-empty array of strings" };
+  return { prompts: prompts.map((p) => sanitizeText(p, MAX_PROMPT_CHARS)) };
+}
+
+const corsHeaders = (allowOrigin) => (allowOrigin
+  // `vary` because the same URL answers differently per Origin — never let a cache
+  // hand a foreign page a response minted for the local app.
+  ? { "access-control-allow-origin": allowOrigin, vary: "origin" }
+  : { vary: "origin" });
+
+const json = (res, code, obj, allowOrigin) => {
+  res.writeHead(code, { "content-type": "application/json", ...corsHeaders(allowOrigin) });
   res.end(JSON.stringify(obj));
 };
+
 const readBody = (req) => new Promise((resolve_) => {
   let b = "";
-  req.on("data", (c) => (b += c));
+  let size = 0;
+  let settled = false;
+  const settle = (v) => { if (!settled) { settled = true; resolve_(v); } };
+  req.on("data", (c) => {
+    if (settled) return;
+    size += c.length;
+    if (size > MAX_BODY_BYTES) { settle({ _tooLarge: true }); return; }
+    b += c;
+  });
   req.on("end", () => {
-    if (!b) { resolve_({}); return; }
-    try { resolve_(JSON.parse(b)); } catch { resolve_({ _parseError: true }); }
+    if (!b) { settle({}); return; }
+    try { settle(JSON.parse(b)); } catch { settle({ _parseError: true }); }
   });
+  req.on("error", () => settle({ _parseError: true }));
 });
 
-export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
+export function createPickServer({
+  port = PICK_SERVER_DEFAULT_PORT,
+  timeoutMs = PICK_SERVER_DEFAULT_TIMEOUT_MS,
+  token = mintPickToken(),
+} = {}) {
   let batch = null;        // the one active batch (or null)
-  let pending = null;      // { res, timer } — the held POST /request response
+  let pending = null;      // { res, timer, allowOrigin } — the held POST /request response
   const sseClients = new Set();
   const allSockets = new Set(); // track every socket for forceful teardown
 
@@ -30,34 +159,66 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
   const finish = () => {                 // resolve the held /request with the result
     if (pending) {
       clearTimeout(pending.timer);
-      json(pending.res, 200, result(batch));
+      json(pending.res, 200, result(batch), pending.allowOrigin);
       pending = null;
     }
     sse("cleared", {});
     batch = null;
   };
 
+  // The body was over the cap. readBody already stopped buffering, so memory is
+  // bounded; drain the rest so the 413 reaches the client cleanly instead of being
+  // RST'd away by an immediate destroy, and hang up on anyone still streaming after.
+  const tooLarge = (req, res, allowOrigin) => {
+    req.resume();
+    res.writeHead(413, { "content-type": "application/json", connection: "close", ...corsHeaders(allowOrigin) });
+    res.end(JSON.stringify({ error: "body too large" }));
+    const kill = setTimeout(() => { if (!req.readableEnded) req.destroy(); }, 250);
+    kill.unref?.(); // a pending hang-up must never hold the process open
+    req.on("end", () => clearTimeout(kill));
+  };
+
   const server = createServer(async (req, res) => {
+    const bound = server.address()?.port ?? port;
+    // 1. DNS-rebinding guard. A foreign name that resolves to 127.0.0.1 still carries
+    //    its own Host, so this refuses the request before any state is touched.
+    if (!isLoopbackHost(req.headers.host, bound)) return json(res, 400, { error: "bad host" }, null);
+
+    // 2. Origin. Absent means a native client (the CLI); present must be loopback. An
+    //    arbitrary origin is never reflected, and `*` is never emitted.
     const origin = req.headers.origin;
+    if (origin !== undefined && !isLoopbackOrigin(origin)) {
+      return json(res, 403, { error: "origin not allowed" }, null);
+    }
+    const allowOrigin = origin ?? null;
+
+    // 3. Preflight is answered before the token check on purpose: browsers never put
+    //    credentials on an OPTIONS, and a 401 here would mask the real error.
     if (req.method === "OPTIONS") {
       res.writeHead(204, {
-        "access-control-allow-origin": origin || "*",
+        ...corsHeaders(allowOrigin),
         "access-control-allow-methods": "GET,POST,OPTIONS",
-        "access-control-allow-headers": "content-type",
+        "access-control-allow-headers": "content-type,authorization,x-pick-token",
+        "access-control-max-age": "600",
       });
       return res.end();
     }
-    const url = req.url.split("?")[0];
 
-    if (req.method === "POST" && url === "/request") {
-      if (batch) return json(res, 409, { status: "busy" }, origin);
+    const [path, rawQuery = ""] = req.url.split("?");
+    // 4. Token on every route.
+    if (!tokenMatches(tokenFrom(req, new URLSearchParams(rawQuery)), token)) {
+      return json(res, 401, { error: "unauthorized" }, allowOrigin);
+    }
+
+    if (req.method === "POST" && path === "/request") {
+      if (batch) return json(res, 409, { status: "busy" }, allowOrigin);
       const body = await readBody(req);
-      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
-      if (!Array.isArray(body.prompts) || body.prompts.length === 0) {
-        return json(res, 400, { error: "prompts must be a non-empty array" }, origin);
-      }
-      batch = createBatch(body.prompts);
-      pending = { res, timer: setTimeout(() => { timeout(batch); finish(); }, timeoutMs) };
+      if (body._tooLarge) return tooLarge(req, res, allowOrigin);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, allowOrigin);
+      const checked = sanitizePrompts(body.prompts);
+      if (checked.error) return json(res, 400, { error: checked.error }, allowOrigin);
+      batch = createBatch(checked.prompts);
+      pending = { res, allowOrigin, timer: setTimeout(() => { timeout(batch); finish(); }, timeoutMs) };
       // A dropped client (Ctrl-C'd CLI) must free the slot immediately, not wedge
       // every new request behind 409-busy until timeoutMs. Drop `pending` first so
       // finish() never writes to the dead socket. (This also fires after a normal
@@ -71,10 +232,10 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
       sse("prompt", view(batch));
       return; // held open until finish()
     }
-    if (req.method === "GET" && url === "/events") {
+    if (req.method === "GET" && path === "/events") {
       res.writeHead(200, {
         "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive",
-        "access-control-allow-origin": origin || "*",
+        ...corsHeaders(allowOrigin),
       });
       res.write(": connected\n\n"); // SSE comment — flushes headers, makes fetch() resolve
       sseClients.add(res);
@@ -82,25 +243,32 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
       req.on("close", () => sseClients.delete(res));
       return;
     }
-    if (req.method === "POST" && url === "/resolve") {
+    if (req.method === "POST" && path === "/resolve") {
       const body = await readBody(req);
-      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      if (body._tooLarge) return tooLarge(req, res, allowOrigin);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, allowOrigin);
       const { id, index, selection } = body;
+      if (typeof id !== "string" || !Number.isInteger(index) || index < 0) {
+        return json(res, 400, { error: "id must be a string and index a non-negative integer" }, allowOrigin);
+      }
+      const checked = sanitizeSelection(selection);
+      if (checked.error) return json(res, 400, { error: checked.error }, allowOrigin);
       if (batch && id === batch.id) {
-        resolve(batch, index, selection);
+        resolve(batch, index, checked.selection);
         if (view(batch).status === "collecting") sse("prompt", view(batch));
         else finish();
       }
-      return json(res, 200, { ok: true }, origin);
+      return json(res, 200, { ok: true }, allowOrigin);
     }
-    if (req.method === "POST" && url === "/cancel") {
+    if (req.method === "POST" && path === "/cancel") {
       const body = await readBody(req);
-      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      if (body._tooLarge) return tooLarge(req, res, allowOrigin);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, allowOrigin);
       const { id } = body;
       if (batch && id === batch.id) { cancel(batch); finish(); }
-      return json(res, 200, { ok: true }, origin);
+      return json(res, 200, { ok: true }, allowOrigin);
     }
-    return json(res, 404, { error: "not found" }, origin);
+    return json(res, 404, { error: "not found" }, allowOrigin);
   });
 
   server.on("connection", (socket) => {
@@ -109,7 +277,8 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
   });
 
   return {
-    start: () => new Promise((res_) => server.listen(port, "127.0.0.1", () => res_({ port: server.address().port }))),
+    token,
+    start: () => new Promise((res_) => server.listen(port, PICK_SERVER_DEFAULT_HOST, () => res_({ port: server.address().port }))),
     stop: () => new Promise((res_) => {
       // If a batch is active, cancel it and resolve the held /request cleanly
       // so any awaiting requestPicks() gets a result instead of a socket hang-up.
@@ -124,15 +293,31 @@ export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
 
 // CLI client: POST the prompts and await the held response (blocks until the batch
 // reaches a terminal status server-side). Fails fast with a hint if nothing answers.
-export function requestPicks({ port = 4518, host = "127.0.0.1", prompts }) {
+export function requestPicks({
+  port = PICK_SERVER_DEFAULT_PORT, host = PICK_SERVER_DEFAULT_HOST, prompts, token,
+}) {
   return new Promise((resolve_, reject) => {
     const payload = JSON.stringify({ prompts });
     const req = httpRequest(
-      { host, port, path: "/request", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) } },
+      {
+        host,
+        port,
+        path: "/request",
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(payload),
+          ...(token ? { "x-pick-token": token } : {}),
+        },
+      },
       (res) => {
         let b = "";
         res.on("data", (c) => (b += c));
         res.on("end", () => {
+          if (res.statusCode === 401) {
+            reject(new Error(`pick-server on ${host}:${port} rejected the token (start it with \`partforge pick-serve\`, or pass --token)`));
+            return;
+          }
           try {
             resolve_(JSON.parse(b));
           } catch {
@@ -147,9 +332,12 @@ export function requestPicks({ port = 4518, host = "127.0.0.1", prompts }) {
 }
 
 // Human-readable CLI output: one summary line per pick, then the raw JSON to parse.
+// Every string here originated in the browser, so it is sanitised again on the way
+// out — the server already stripped control characters, but this print is the last
+// gate before text lands in an agent's context.
 export function formatPickResult({ status, picks }) {
   const safePicks = Array.isArray(picks) ? picks : [];
-  const lines = [`status: ${status} (${safePicks.length} pick${safePicks.length === 1 ? "" : "s"})`];
+  const lines = [`status: ${sanitizeText(status, 40)} (${safePicks.length} pick${safePicks.length === 1 ? "" : "s"})`];
   for (const { prompt, selection } of safePicks) {
     let summary;
     try {
@@ -161,7 +349,7 @@ export function formatPickResult({ status, picks }) {
     } catch {
       summary = JSON.stringify(selection);
     }
-    lines.push(`• "${prompt}" → ${summary}`);
+    lines.push(`• "${sanitizeText(prompt, MAX_PROMPT_CHARS)}" → ${sanitizeText(summary, MAX_SELECTION_CHARS)}`);
   }
   lines.push("", JSON.stringify({ status, picks }, null, 2));
   return lines.join("\n");

package/src/framework/pick-request/token-store.js

@@ -0,0 +1,31 @@
+// Where `partforge pick-serve` leaves the session token so that `partforge pick`,
+// which runs in a *different* process, can authenticate without the agent copying it
+// by hand. Node-only — never imported by the browser client.
+//
+// The file is the token's only at-rest home: 0600 inside a 0700 directory under the
+// user's home, not a world-readable temp dir, and removed when the server stops.
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const dir = () => join(homedir(), ".partforge");
+export const pickTokenPath = (port) => join(dir(), `pick-${port}.token`);
+
+export function savePickToken(port, token) {
+  mkdirSync(dir(), { recursive: true, mode: 0o700 });
+  writeFileSync(pickTokenPath(port), token, { mode: 0o600 });
+  return pickTokenPath(port);
+}
+
+export function loadPickToken(port) {
+  try {
+    const t = readFileSync(pickTokenPath(port), "utf8").trim();
+    return t || null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearPickToken(port) {
+  try { rmSync(pickTokenPath(port)); } catch { /* already gone — nothing to clean */ }
+}

package/src/framework/pose-fast-path.js

@@ -4,7 +4,7 @@
 // unchanged gets its delivered mesh re-posed in the viewer (delta vs. the
 // delivered pose) and is re-stamped current — no worker job. Everything else
 // falls through to the normal regen loop.
-import { viewSubParts } from "./jobs.js";
+import { viewSubParts } from "./part-model.js";
 import { probePoses } from "./pose-probe.js";
 import { poseDelta } from "./geometry/pose.js";
 
@@ -28,6 +28,17 @@ export function createPoseFastPath(part, viewer, cache, { params, getView, getPa
       stamps[name] = probeFor().get(name);
     },
 
+    // Drop a subpart's stamp: the mesh in the viewer is no longer known to
+    // correspond to any probed pose. Used when meshes are SHOWN without being
+    // recorded — a build delivered stale because animation frames kept bumping
+    // the version is displayed best-effort, but its geometry was not built at
+    // the live params, so no stamp may describe it. Without this the next edit
+    // would re-pose that newer mesh off the PREVIOUS delivery's stamp, i.e.
+    // apply a delta measured against geometry that is no longer on screen.
+    forget(name) {
+      delete stamps[name];
+    },
+
     // Re-pose every visible stale subpart whose base geometry is unchanged.
     // Returns the NAMES repaired (empty = nothing pose-only to do). Names, not a
     // count: a slider drag repairs the same subpart on every input event, so only

package/src/framework/pose-probe-core.js

@@ -0,0 +1,129 @@
+// Geometry-free pose probe: run a subpart's build()+place() against a stub kernel
+// whose token solids carry (a) a content-hash chain built with the shared h() and
+// (b) pending rigid pose steps, mirroring the backends' pose-lazy bookkeeping.
+// The fast path compares probe results ACROSS PARAM CHANGES ONLY — probe hashes
+// are never compared to backend hashes, so they only need to be stable and to
+// fold every geometry-affecting argument.
+//
+// Trust model: any query op (boundingBox/volume/…) during a build marks that
+// subpart untrusted — a query result could feed geometry OR pose, and the probe
+// returns dummies, so neither hash stability nor pose values can be believed.
+// A FUNCTION passed as (or nested inside) an op argument is untrusted for the
+// same reason the OCCT backend refuses to hash function selectors (see `selKey`
+// in occt-backend.js): a closure like `(e) => e.inDirection([0,0,p.z])` has the
+// same source text at every value of `p.z`, so hashing it would hold baseHash
+// stable while the real geometry changed — precisely the false-positive the fast
+// path must never make. Untrusted subparts simply take the normal regen path.
+import { h } from "./geometry/solid-hash.js";
+import { addSugar } from "./geometry/solid-sugar.js";
+import { SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS, OCCT_ONLY_OPS } from "./geometry/kernel.js";
+import { MAX_PROBE_OPS, ProbeRunawayError } from "./geometry/probe.js";
+
+const NAN3 = () => [NaN, NaN, NaN];
+
+function makeProbeSession() {
+  const state = { count: 0, queried: false, unhashable: false };
+  const tick = () => { if (++state.count > MAX_PROBE_OPS) throw new ProbeRunawayError(`pose probe exceeded ${MAX_PROBE_OPS} ops`); };
+
+  // Queries return dummies AND poison trust (see module comment).
+  const QUERY_DUMMIES = {
+    boundingBox: () => ({ min: NAN3(), max: NAN3() }), // addSugar derives center/size
+    volume: () => NaN,
+    genus: () => NaN,
+    isEmpty: () => false,
+    area: () => NaN,
+    toRegions: () => [],
+    simple: () => ({ outer: [[NaN, NaN]], holes: [] }),
+    toMesh: () => ({ positions: new Float32Array(9), normals: new Float32Array(0), triangles: 1, edges: new Float32Array(0) }),
+    toSTL: () => new ArrayBuffer(0),
+    toIndexedMesh: () => ({ positions: new Float32Array(9), indices: new Uint32Array(3) }),
+  };
+
+  // Operand tokens fold into a hash key by their own (pose-folded) hash; plain
+  // data canonicalizes via h(). Functions can't be hashed at all (see the module
+  // comment), so they poison trust AND get a per-call unique key — belt and
+  // braces, so the hash can't collide even before the trust check is consulted.
+  //
+  // The walk mirrors h()'s `canon` exactly (array → elements, other object → own
+  // enumerable values), because a function nested inside an options object —
+  // `fillet({ r, edges: (e) => … })`, the normal calling convention — is reached
+  // by canon, not by the top-level argument check.
+  let unhashable = 0;
+  const argKey = (a) => {
+    if (a && a.__poseToken) return a.__folded();
+    if (typeof a === "function") { state.unhashable = true; return `fn#${unhashable++}`; }
+    if (Array.isArray(a)) return a.map(argKey);
+    if (a && typeof a === "object") return Object.fromEntries(Object.keys(a).map((k) => [k, argKey(a[k])]));
+    return a;
+  };
+
+  function token(hash, pose) {
+    const folded = () => (pose.length ? h("posed", hash, pose) : hash);
+    const foldOp = (op) => (...args) => { tick(); return token(h(op, folded(), ...args.map(argKey)), []); };
+    const t = {
+      __poseToken: true,
+      __folded: folded,
+      _hash: hash,
+      _pose: pose,
+      // The rigid vocabulary stays out of the hash: recorded as pending steps,
+      // exactly like the OCCT backend's pose-lazy wrap. All transform sugar
+      // (rotateAbout/along/at/rotateX…) composes onto these via addSugar.
+      translate: (v) => { tick(); return token(hash, [...pose, { t: "translate", v }]); },
+      rotate: (deg, center, axis) => { tick(); return token(hash, [...pose, { t: "rotate", deg, center, axis }]); },
+      clone: () => t, // tokens are immutable — sharing is safe
+      // regions() is a data-returning query in disguise: on a real backend the
+      // scission ARRAY LENGTH is param-dependent data, so a build branching on
+      // `regions().length` could hold baseHash stable while geometry changed.
+      // It therefore poisons trust like any other query; the single token is
+      // still returned so op chains on regions()[0] don't crash mid-probe.
+      regions: () => { tick(); state.queried = true; return [token(h("regions", folded()), [])]; },
+    };
+    for (const [op, dummy] of Object.entries(QUERY_DUMMIES))
+      t[op] = (...a) => { tick(); state.queried = true; return dummy(...a); };
+    // Every other contract op folds pose + args into a fresh hash. Generated from
+    // the kernel-contract lists so new ops can never silently drift out of the probe.
+    for (const op of [...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_OPS, ...OCCT_ONLY_OPS])
+      t[op] ??= foldOp(op);
+    return addSugar(t);
+  }
+
+  // Kernel: catch-all factory — any op makes a fresh token hashed from its args.
+  const kernelQueries = {
+    toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
+    cleanup: () => {}, beginSubPart: () => {}, endSubPart: () => {},
+    cacheStats: () => ({ hits: 0, misses: 0 }), resetCacheStats: () => {},
+  };
+  const ignore = (key) => typeof key !== "string" || key === "then" || key === "toJSON" || key[0] === "_";
+  const kernel = new Proxy({}, {
+    get(_t, key) {
+      if (ignore(key)) return undefined;
+      if (key in kernelQueries) return kernelQueries[key];
+      return (...args) => { tick(); return token(h(key, ...args.map(argKey)), []); };
+    },
+  });
+
+  return { kernel, state };
+}
+
+const finiteVec = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+const stepsFinite = (steps) => steps.every((st) =>
+  st.t === "translate"
+    ? finiteVec(st.v)
+    : Number.isFinite(st.deg) && finiteVec(st.center) && finiteVec(st.axis));
+
+// Probe ONE sub-part's build+place at explicit params/purpose. The shared
+// primitive under probePoses (pose-probe.js) and the lint place/animation
+// rules — kept free of jobs.js imports so the lint import closure stays pure
+// (test/lint-purity.test.js). Never throws; a failing/queried/weird sub-part
+// yields { trusted: false }.
+export function probeSubPartPose(sp, { view, purpose = "display", p, d }) {
+  try {
+    const { kernel, state } = makeProbeSession(); // fresh op budget + trust per subpart
+    let s = sp.build(kernel, p, d);
+    if (sp.place) s = sp.place(s, { view, purpose, p, d });
+    const ok = s && s.__poseToken && !state.queried && !state.unhashable && stepsFinite(s._pose);
+    return ok ? { trusted: true, baseHash: s._hash, pose: s._pose } : { trusted: false };
+  } catch {
+    return { trusted: false };
+  }
+}