Raw schema
{
"type": "object",
"properties": {
"check": {
"type": "string",
"description": "Which verification to run. Omit only when passing call-time `requirements`; then the requirements ledger is the verification.",
"enum": [
"assembly",
"urdf",
"dfm",
"dfm-preflight",
"swept-collision",
"reachable",
"mounting-holes",
"load-capacity",
"static-hold",
"motion-load",
"fastener-installation",
"geometry-quality",
"assembly-path",
"edge-radius",
"physics",
"requirements"
]
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Call-time external requirements ([{ name, predicate }]) measured in the same ledger as script require(), dfmSpec and feaStudy, tagged source: 'external' and never persisted. The predicate is the serializable form of require(): { metric: clearance | distance | mass | volume | bbox | centerOfMass | count | innerLoops | angle | concentric | coplanar, a?, b?, op: gte | lte | eq | between | within, limit, tolerance?, density? }. Operands are { kind: body | faces | edges | part, ref: <feature id/name or part name>, query? }. With `check` omitted the ledger is the whole verification; check 'requirements' is the explicit form."
},
"file": {
"type": "string",
"description": "Path to a .kcad.ts script (assembly/dfm/dfm-preflight/swept-collision/reachable/mounting-holes/load-capacity/static-hold/geometry-quality/edge-radius/requirements). Hosted server: cannot read files from your machine โ pass `code`, or `project:<slug>` for a saved project."
},
"code": {
"type": "string",
"description": "Inline kernelCAD script source (same checks as `file`)."
},
"feature_id": {
"type": "string",
"description": "check:'geometry-quality' โ body feature to measure; defaults to script return. check:'edge-radius' โ lowered feature; default the returned model."
},
"tiny_face_area_mm2": {
"type": "number",
"minimum": 0,
"default": 0.01,
"description": "check:'geometry-quality' โ flag faces strictly below this absolute area; zero disables."
},
"tiny_face_relative": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0,
"description": "check:'geometry-quality' โ fraction of total BREP surface area, ORed with absolute threshold."
},
"short_edge_length_mm": {
"type": "number",
"minimum": 0,
"default": 0.1,
"description": "check:'geometry-quality' โ flag edges strictly below this length; zero disables."
},
"symmetry_tolerance_mm": {
"type": "number",
"minimum": 0.000001,
"default": 0.05,
"description": "check:'geometry-quality' โ maximum sampled mirror-to-mesh distance, mm."
},
"mesh_deflection_mm": {
"type": "number",
"minimum": 1e-7,
"description": "check:'geometry-quality' โ absolute mesh deflection, defaults to tolerance/4; must be <= tolerance/2."
},
"asserted_plane": {
"type": "object",
"additionalProperties": false,
"required": [
"origin",
"normal"
],
"description": "check:'geometry-quality' โ optional required mirror plane in model coordinates; normal is normalized and must be nonzero.",
"properties": {
"origin": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3
},
"normal": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3
}
}
},
"assembly": {
"type": "string",
"description": "Assembly name; defaults to the first captured assembly."
},
"min_radius_mm": {
"type": "number",
"minimum": 0,
"description": "check:'edge-radius' โ minimum fillet radius in mm (does not imply sharp-edge prohibition)."
},
"max_radius_mm": {
"type": "number",
"minimum": 0,
"description": "check:'edge-radius' โ maximum fillet radius in mm; must be >= min_radius_mm."
},
"require_edge_break": {
"type": "string",
"enum": [
"external",
"internal",
"all"
],
"description": "check:'edge-radius' โ prohibit sharp convex/external, concave/internal, or all edges."
},
"parts": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
},
"description": "check:'edge-radius' โ explicit assembly part names (default all)."
},
"edges": {
"type": [
"object",
"array",
"string"
],
"description": "check:'edge-radius' โ EdgeQuery or @kc[...] edge ref(s); intersected with faces. Query near sorts, it does not filter."
},
"faces": {
"type": [
"object",
"array",
"string"
],
"description": "check:'edge-radius' โ FaceQuery or @kc[...] face ref(s); includes incident edges and fillets on selected faces."
},
"fasteners": {
"type": "array",
"description": "check:'fastener-installation' โ explicit named stations; empty means no coverage.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"part": {
"type": "string",
"minLength": 1
},
"against": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
}
},
"engagementPart": {
"type": "string",
"minLength": 1
},
"minEngagementMm": {
"type": "number",
"minimum": 0,
"description": "Declared geometric axial overlap minimum; no thread-strength claim."
},
"maxProtrusionMm": {
"type": "number",
"minimum": 0
}
},
"required": [
"part",
"against"
]
}
},
"toleranceMm": {
"type": "number",
"minimum": 0,
"description": "check:'fastener-installation' โ linear tolerance, default .05 mm."
},
"angleToleranceDeg": {
"type": "number",
"minimum": 0,
"maximum": 90,
"description": "check:'fastener-installation' โ axis tilt tolerance, default 1 degree."
},
"urdf_path": {
"type": "string",
"description": "check:'urdf' โ path to the .urdf file."
},
"dxf": {
"type": "string",
"description": "check:'dfm-preflight' โ path to a DXF file."
},
"featureId": {
"type": "string",
"description": "check:'dfm-preflight' โ FeatureId to scope to."
},
"vendor": {
"type": "string",
"description": "check:'dfm-preflight' โ vendor SKU (required for that check)."
},
"material": {
"type": "string",
"description": "check:'dfm-preflight' โ material SKU (required for that check)."
},
"thicknessIn": {
"type": "number",
"description": "check:'dfm-preflight' โ material thickness in inches."
},
"thicknessMm": {
"type": "number",
"description": "check:'dfm-preflight' โ material thickness in millimeters."
},
"service": {
"type": "string",
"enum": [
"laser",
"cnc-router",
"waterjet",
"bending"
],
"description": "check:'dfm-preflight' โ service."
},
"refreshCatalog": {
"type": "boolean",
"description": "check:'dfm-preflight' โ force vendor catalog refresh."
},
"directions": {
"type": "array",
"maxItems": 64,
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3
},
"description": "check:'assembly-path' โ additional nonzero world-space removal vectors; normalized and deduplicated."
},
"disassemblyOrder": {
"type": "boolean",
"description": "check:'assembly-path' โ iteratively remove freed parts and return removalOrder or stuckParts."
},
"sequence": {
"type": "boolean",
"description": "check:'assembly-path' โ plan a build sequence { steps, model, unknown, search?, requiresForce?, toolBlocked?, needsHold? }. Fastened/fixed clusters become subassemblies planned inside and installed as one unit; steps carry the insertion direction (reverse removal), and may be motion: helical (declared fastener), requires-force (press/snap, not proven) or search. Stuck sets use a budgeted partition; non-straight paths found by sampling are labelled found-by-search and are not proven. Blocked and unknown parts are not reported as impossible."
},
"threadedFasteners": {
"type": "array",
"items": {
"type": "string"
},
"description": "check:'assembly-path' โ part names that need a helical removal. Catalog screw/bolt/nut families are detected automatically; without a fastened-mate fastener declaration (axis/pitch) they remain unknown: non-straight-path. Declare the motion on arm.mate(..., 'fastened', { fastener: { part, axis, pitchMm, tool? }, fit?: { kind, part? } })."
},
"stability": {
"type": "boolean",
"description": "check:'assembly-path' โ run the approximate P3 static-stability pass on the sequence. Each part's closed-mesh volume centroid (uniform density) must project inside the convex hull of its contacts with already-stable parts. Unsupported parts become needsHold { part, reason, supports } and ok:false; a stable step may carry heldBy. Not a physics simulation."
},
"fixtures": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
},
"description": "check:'assembly-path' with stability:true โ declared base/fixture part names, stable from step 1. Default: the lowest part(s) along gravity."
},
"contactToleranceMm": {
"type": "number",
"minimum": 0,
"description": "check:'assembly-path' with stability:true โ surface distance at or below which parts count as touching (default 0.05 mm)."
},
"joint": {
"type": "string",
"description": "check:'swept-collision' โ joint to sweep; omit to sweep every declared joint. check:'static-hold' โ joint to evaluate; omit to evaluate every joint with a declared actuator."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3,
"description": "check:'swept-collision' โ [lower, upper, step] in joint-native units."
},
"collision_tolerance_mm3": {
"type": "number",
"description": "check:'swept-collision' โ BREP intersection volume tolerance (mm^3)."
},
"tip_link": {
"type": "string",
"description": "check:'reachable' โ end-effector part name (required for that check)."
},
"target_position": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3,
"description": "check:'reachable' โ target [x, y, z] mm (world frame)."
},
"target_orientation": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3,
"description": "check:'reachable' โ target XYZ Euler angles in radians."
},
"position_tolerance_mm": {
"type": "number",
"description": "check:'reachable' โ position tolerance in mm."
},
"orientation_tolerance_rad": {
"type": "number",
"description": "check:'reachable' โ orientation tolerance in radians."
},
"prefer_solver": {
"type": "string",
"enum": [
"analytical",
"numeric",
"auto"
],
"description": "check:'reachable' โ force the IK path ('auto' default)."
},
"max_iterations": {
"type": "number",
"description": "check:'reachable' โ numeric-path iteration cap."
},
"seed": {
"type": "object",
"description": "check:'reachable' โ numeric IK seed pose (joint name -> deg/mm)."
},
"loads": {
"type": "object",
"description": "check:'load-capacity' โ partName -> { force?: [Fx,Fy,Fz] N, torque?: [Tx,Ty,Tz] N*m }."
},
"materials": {
"type": "object",
"description": "check:'load-capacity' โ partName -> material declaration."
},
"mode": {
"type": "string",
"enum": [
"stub",
"beam",
"fea"
],
"description": "check:'load-capacity' โ 'beam' (default), 'stub', or 'fea' (solve the script's feaStudy: CalculiX + gmsh when installed, else the in-process voxel estimate)."
},
"safety_factor_threshold": {
"type": "number",
"description": "check:'load-capacity' โ pass/fail safety-factor floor (default 1.5; mode 'fea': the study's minSafetyFactor when declared)."
},
"study": {
"type": "string",
"description": "check:'load-capacity' mode:'fea' โ feaStudy name (default: the last declared one)."
},
"mesh_size": {
"type": "number",
"description": "check:'load-capacity' mode:'fea' โ element size override, mm."
},
"heatmaps": {
"type": "boolean",
"description": "check:'load-capacity' mode:'fea' โ also render stress heatmap PNGs (default false)."
},
"refine": {
"type": "boolean",
"description": "check:'load-capacity' mode:'fea' โ one automatic finer pass (0.75x element size) when the stress is untrusted, inside the element budget (default true); false solves once at the study's meshSize."
},
"pose": {
"type": [
"object",
"array"
],
"description": "check:'static-hold' โ explicit pose (joint name -> deg/mm) or array of poses; omit to sample a grid across the evaluated joint's range."
},
"gravity": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3,
"description": "check:'static-hold' โ gravity vector, m/s^2, world frame (default [0, 0, -9.81]). check:'assembly-path' with stability:true โ gravity direction, world frame, magnitude ignored (default [0, 0, -1])."
},
"min_torque_margin_pct": {
"type": "number",
"description": "check:'static-hold' โ safety-margin floor as a percent of actuator capacity (default 20)."
},
"range_samples": {
"type": "number",
"description": "check:'static-hold' โ grid density per evaluated joint when `pose` is omitted (default 9). check:'motion-load' motion_mode:'range' โ grid points per joint (default 5)."
},
"motion_mode": {
"type": "string",
"enum": [
"tracks",
"range",
"poses"
],
"description": "check:'motion-load' โ 'tracks' (default): along the animationView timeline with inertia; 'range': quasi-static grid over each driven joint's limits; 'poses': exactly motion_poses (a user-named pose is one entry)."
},
"motion_poses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"description": "check:'motion-load' motion_mode:'poses' โ explicit mate poses, each an object of joint name -> value in degrees."
},
"sample_ms": {
"type": "number",
"description": "check:'motion-load' โ timeline sample step, ms (default 20). Inertia peaks depend on it at keyframe velocity steps."
},
"quasi_static": {
"type": "boolean",
"description": "check:'motion-load' โ drop velocity/acceleration terms (gravity and external loads only)."
},
"motion_loads": {
"type": "array",
"description": "check:'motion-load' โ external forces: [{ part, point: [x,y,z] mm in the part's modeled frame, force: [Fx,Fy,Fz] N world, fromMs?, toMs? }].",
"items": {
"type": "object",
"required": [
"part",
"point",
"force"
],
"properties": {
"part": {
"type": "string"
},
"point": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3
},
"force": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"maxItems": 3
},
"fromMs": {
"type": "number"
},
"toMs": {
"type": "number"
}
}
}
},
"supports": {
"type": "object",
"description": "check:'motion-load' โ mechanicalJoint name -> support part names to use instead of the declared supports (compare with / without a bushing)."
},
"series_points": {
"type": "number",
"description": "check:'motion-load' โ max torque-vs-time points per joint in the result (default 120; 0 omits the series)."
}
},
"required": [
"check"
]
}