Contract for TypedContract {
}
/// The most keys of one call that are looked at, and the longest key given a suggestion.
-const MAX_KEYS: usize = 64;
+pub(crate) const MAX_KEYS: usize = 64;
const MAX_KEY_LEN: usize = 64;
const MAX_MESSAGE_LEN: usize = 300;
const MAX_WHOLE_LEN: usize = 4096;
@@ -260,6 +260,20 @@ pub(crate) fn parse_issue(e: &serde_path_to_error::Error) ->
Issue { path, message: truncate(&message, MAX_MESSAGE_LEN), suggestion: None }
}
+/// Run `handler` as the command `id`, checking the call against the contract `id` publishes
+/// (its [`CommandSpec::contract`](crate::cmd::CommandSpec::contract)), so the contract enforced is
+/// always the one described. With the level off and no audit recorder, this is exactly
+/// `handler(s, p)`, without looking anything up; a command without a contract just runs.
+pub fn run_checked_as(s: &mut Session, p: &Value, id: &str, handler: Run) -> Result {
+ if s.param_check == ParamCheck::Off && !record::enabled() {
+ return handler(s, p);
+ }
+ match crate::cmd::find_command(id).and_then(|c| c.contract) {
+ Some(contract) => run_checked(s, p, id, contract, handler),
+ None => handler(s, p),
+ }
+}
+
/// Run `handler` as the command `id`, checking the call against `contract` as the session's
/// [`ParamCheck`] level asks (see the module docs). With the level off and no audit recorder,
/// this is exactly `handler(s, p)`.
diff --git a/crates/engine/src/schema/coverage_tests.rs b/crates/engine/src/schema/coverage_tests.rs
new file mode 100644
index 000000000..a8db64570
--- /dev/null
+++ b/crates/engine/src/schema/coverage_tests.rs
@@ -0,0 +1,106 @@
+//! New commands come with schemas: every command has a contract (its input schema) and an
+//! output schema, apart from `planned!` placeholders and the commands listed in
+//! `unconverted.txt`. That list holds the commands that predate the rule; it only shrinks.
+
+use std::collections::BTreeSet;
+
+use serde_json::json;
+
+use crate::Session;
+use crate::cmd::command_specs;
+use crate::schema::ParamCheck;
+use crate::schema::check::MAX_KEYS;
+
+/// Whether a command without schemas fails the test. Off for now: the test warns instead. The
+/// owner will flip this to `true` when the PR backlog is down. `SOLIDCRAFT_SCHEMA_RULE_STRICT=1`
+/// turns it on for one run.
+const SCHEMA_RULE_STRICT: bool = false;
+
+const UNCONVERTED: &str = include_str!("unconverted.txt");
+
+/// The ids in `unconverted.txt`, in file order (`#` lines are comments).
+fn unconverted() -> Vec<&'static str> {
+ UNCONVERTED.lines().map(str::trim).filter(|l| !l.is_empty() && !l.starts_with('#')).collect()
+}
+
+#[test]
+fn every_command_has_input_and_output_schemas() {
+ let listed: BTreeSet<&str> = unconverted().into_iter().collect();
+ let mut problems = Vec::new();
+ let mut missing = Vec::new();
+ for c in command_specs() {
+ let has = (c.contract.is_some(), c.output.is_some());
+ let listed = listed.contains(c.id);
+ if c.planned.is_some() {
+ if listed {
+ problems.push(format!("`{}` is a planned! placeholder, which needs no line in unconverted.txt", c.id));
+ }
+ continue;
+ }
+ match (has, listed) {
+ ((true, true), true) => problems.push(format!("`{}` has its schemas now: remove its line from unconverted.txt", c.id)),
+ ((true, true), false) | (_, true) => {}
+ ((input, output), false) => missing.push(format!(
+ "`{}` has no {} schema. Every new command needs a contract (`.contract(…)`, run through `checked!`) \
+ and an output type (`.output(…)`): see docs/book/src/dev/schemas.md",
+ c.id,
+ match (input, output) {
+ (true, _) => "output",
+ (false, true) => "input",
+ (false, false) => "input or output",
+ }
+ )),
+ }
+ }
+ assert!(problems.is_empty(), "{}", problems.join("\n"));
+ if !missing.is_empty() {
+ let strict = SCHEMA_RULE_STRICT || std::env::var_os("SOLIDCRAFT_SCHEMA_RULE_STRICT").is_some_and(|v| v != "0");
+ let report = format!(
+ "{} command(s) lack an input or output schema. This is a warning for now; it will become required:\n{}",
+ missing.len(),
+ missing.join("\n")
+ );
+ assert!(!strict, "{report}");
+ eprintln!("warning: {report}");
+ // A GitHub Actions annotation, so the warning shows on the CI run page too.
+ println!("::warning title=Commands without schemas::{}", missing.len());
+ }
+}
+
+/// A contract that is published but not checked would describe calls nobody refuses: every
+/// command with a contract runs through `checked!` with its own id, which checks the contract
+/// that id publishes. Calls `run` itself (not `Session::execute`, which first asks `enabled`)
+/// in strict with an unknown key, which must be refused under the command's own id before the
+/// handler sees it.
+#[test]
+fn every_contract_is_checked_in_front_of_its_handler() {
+ const PROBE: &str = "not_a_key_of_any_command";
+ for c in command_specs() {
+ let Some(contract) = c.contract else { continue };
+ // The check reads at most `MAX_KEYS` keys of a call, so a contract can't take more.
+ let keys = contract.allowed_keys().len();
+ assert!(keys <= MAX_KEYS, "`{}` takes {keys} keys; a call may have at most {MAX_KEYS}, so no call could use them all", c.id);
+ let mut s = Session { param_check: ParamCheck::Strict, ..Session::default() };
+ let run = c.run;
+ let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(&mut s, &json!({PROBE: 1}))));
+ let fix = format!("give its CommandSpec `crate::checked!(\"{}\", )`", c.id);
+ let error = match result {
+ Ok(Err(e)) => e.to_string(),
+ Ok(Ok(v)) => panic!("`{}` ran with an unknown key in strict ({v}): {fix}", c.id),
+ Err(_) => panic!("`{}` panicked on an unknown key in strict: {fix}", c.id),
+ };
+ let expected = format!("invalid parameters for `{}`: unknown key `{PROBE}`", c.id);
+ assert!(error.starts_with(&expected), "`{}` should refuse with \"{expected}\", not \"{error}\": {fix}", c.id);
+ }
+}
+
+#[test]
+fn the_unconverted_list_is_sorted_and_names_real_commands() {
+ let ids = unconverted();
+ for pair in ids.windows(2) {
+ assert!(pair[0] < pair[1], "unconverted.txt must be sorted, each id once: `{}` comes before `{}`", pair[0], pair[1]);
+ }
+ let registered: BTreeSet<&str> = command_specs().iter().map(|c| c.id).collect();
+ let stale: Vec<&str> = ids.into_iter().filter(|id| !registered.contains(id)).collect();
+ assert!(stale.is_empty(), "unconverted.txt names commands that don't exist (remove their lines): {stale:?}");
+}
diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rs
index 266d5fa87..f74283644 100644
--- a/crates/engine/src/schema/mod.rs
+++ b/crates/engine/src/schema/mod.rs
@@ -36,12 +36,20 @@
//! `strict_keeps_todays_errors`. Then run the whole test suite with the audit recorder (see
//! `record.rs`): a call that succeeds today but breaks the contract is either a form the
//! contract is missing or a caller's mistake.
+//!
+//! New commands come with both schemas: `coverage_tests.rs` warns about a command without a
+//! contract or an output type (it will fail once `SCHEMA_RULE_STRICT` flips), unless it is a `planned!` placeholder or listed in
+//! `unconverted.txt`, which holds the commands that predate the rule. That list only shrinks:
+//! converting a command removes its line, and nothing is added to it. How to write a contract,
+//! with the shared types and a checklist: docs/book/src/dev/schemas.md.
mod check;
#[cfg_attr(target_arch = "wasm32", path = "record_wasm.rs")]
mod record;
mod types;
+#[cfg(test)]
+mod coverage_tests;
#[cfg(test)]
mod tests;
@@ -49,16 +57,17 @@ mod tests;
pub mod features;
pub mod inspect;
-pub use check::{Contract, Issue, ParamCheck, TypedContract, input_schema_for, output_schema_for, run_checked};
+pub use check::{Contract, Issue, ParamCheck, TypedContract, input_schema_for, output_schema_for, run_checked, run_checked_as};
pub use types::*;
-/// A command's `run` that checks the call against `$contract` before running `$handler`
-/// (see [`run_checked`]). Expands to a non-capturing closure, which coerces to the registry's
-/// `Run` function pointer.
+/// A command's `run` that checks the call against the contract command `$id` publishes
+/// (`.contract(…)` on its `CommandSpec`) before running `$handler` (see [`run_checked_as`]), so
+/// the contract enforced is always the one described. Expands to a non-capturing closure, which
+/// coerces to the registry's `Run` function pointer.
#[macro_export]
#[doc(hidden)]
macro_rules! checked {
- ($id:literal, $contract:path, $handler:path) => {
- |s: &mut $crate::Session, p: &serde_json::Value| $crate::schema::run_checked(s, p, $id, &$contract, $handler)
+ ($id:literal, $handler:path) => {
+ |s: &mut $crate::Session, p: &serde_json::Value| $crate::schema::run_checked_as(s, p, $id, $handler)
};
}
diff --git a/crates/engine/src/schema/unconverted.txt b/crates/engine/src/schema/unconverted.txt
new file mode 100644
index 000000000..a909e6d48
--- /dev/null
+++ b/crates/engine/src/schema/unconverted.txt
@@ -0,0 +1,461 @@
+# Commands that predate the rule that every command has input and output schemas
+# (coverage_tests.rs). This list only shrinks: when you give a command its contract and output
+# type, remove its line. Never add one: a new command comes with both schemas. Sorted, one id
+# per line.
+appearance.assign
+appearance.library
+appearance.list
+assembly.bom
+body.rename
+browser.collapse_all
+browser.expand_all
+browser.group
+browser.move
+browser.order
+browser.rename_group
+browser.ungroup
+browser.visibility
+canvas.calibrate
+canvas.decal
+canvas.delete
+canvas.edit
+canvas.insert
+component.activate
+component.break_link
+component.capture_position
+component.copies
+component.create
+component.delete
+component.extract
+component.from_bodies
+component.insert_design
+component.links
+component.list
+component.metadata
+component.metadata.set
+component.move_bodies
+component.move_sketches
+component.paste_new
+component.properties
+component.relink
+component.rename
+component.replace_with_link
+component.revert_position
+component.unlock
+component.update_links
+config.activate
+config.column
+config.configure
+config.preview
+config.row
+config.rule
+config.rules
+config.table
+construct.axis.edge
+construct.axis.normal_to_face
+construct.axis.through_cylinder
+construct.axis.two_planes
+construct.axis.two_points
+construct.plane.along_path
+construct.plane.at_angle
+construct.plane.midplane
+construct.plane.offset
+construct.plane.perpendicular
+construct.plane.tangent
+construct.plane.three_points
+construct.plane.two_edges
+construct.point.along_path
+construct.point.center
+construct.point.edge_plane
+construct.point.three_planes
+construct.point.two_edges
+construct.point.vertex
+contact.check
+contact.create
+contact.disable_all
+contact.edit
+contact.enable_all
+contact.enable_sets
+contact.list
+diagnostics.crash_report
+diagnostics.crash_reports
+diagnostics.crash_reports.clear
+diagnostics.crash_test
+doc.open
+doc.recover
+doc.recovery_discard
+doc.recovery_list
+document.inspect
+document.metadata
+document.metadata.remove
+document.metadata.set
+document.units
+edit.checkpoint
+edit.redo
+edit.restore_checkpoint
+edit.undo
+engine.commands
+explode.create
+explode.delete
+explode.list
+explode.show
+expr.evaluate
+face.delete
+file.export
+file.export_view_dxf
+file.insert_mesh
+file.insert_step
+file.new
+file.save
+file.save_as
+file.save_mesh
+file.slicers
+frame.member
+frame.profile.insert
+frame.profile.list
+frame.profile.properties
+inspect.accessibility
+inspect.center_of_mass
+inspect.clearance
+inspect.compare
+inspect.continuity
+inspect.curvature_comb
+inspect.curvature_map
+inspect.draft
+inspect.environment_map
+inspect.interference
+inspect.isocurve
+inspect.measure
+inspect.minimum_radius
+inspect.parameter_sweep
+inspect.section
+inspect.silhouette
+inspect.zebra
+joint.as_built
+joint.cam
+joint.create
+joint.delete
+joint.drive
+joint.edit
+joint.gear
+joint.inspect
+joint.limits
+joint.list
+joint.motion_link
+joint.origin
+joint.rack_pinion
+joint.reach
+joint.rigid_group
+joint.screw
+joint.solve
+joint.sweep
+library.apply
+library.export
+library.inspect
+material.assign
+material.create
+material.delete
+material.edit
+material.inspect
+material.list
+material.properties.directional
+material.properties.validate
+mesh.convert
+model.edges
+model.faces
+model.threads
+motion.delete
+motion.export
+motion.export_animation
+motion.interference
+motion.list
+motion.play
+motion.plot
+motion.study
+motion.trace
+motion.trace.edit
+motion.trace.keep
+occurrence.copy
+occurrence.drag
+occurrence.ground
+occurrence.move
+occurrence.properties
+parameters.add
+parameters.change
+parameters.comment
+parameters.complete
+parameters.delete
+parameters.export
+parameters.favorite
+parameters.graph
+parameters.import
+parameters.list
+parameters.move
+parameters.rename
+parameters.users
+parts.fastener
+parts.insert
+parts.library
+parts.resize
+plastic.assign_rule
+plastic.boss
+plastic.lip
+plastic.manage_rules
+plastic.rest
+plastic.rules
+plastic.snap_fit
+render.aging.describe
+render.backends
+render.camera.fit
+render.camera.get
+render.camera.set
+render.cancel
+render.effects.describe
+render.export
+render.hdr.inspect
+render.library.appearance.apply
+render.library.describe
+render.library.environment.apply
+render.library.list
+render.library.physical.prepare
+render.library.preview
+render.library.studio.apply
+render.library.studio.prepare
+render.library.surface.bind
+render.library.surface.prepare
+render.library.surface.unbind
+render.library.targets
+render.optics.bind
+render.optics.unbind
+render.preflight
+render.preset.apply
+render.preset.resolve
+render.quality.prepare
+render.result.pin
+render.result.regrade
+render.scene
+render.settings.apply
+render.settings.capture_hdr
+render.settings.get
+render.settings.set
+render.shot.duplicate
+render.shot.remove
+render.shot.rename
+render.stage.backdrop
+render.stage.clear
+render.stage.ground
+render.start
+render.status
+select.clear
+select.set
+selection.delete
+sheet.convert
+sheet.export_bend_table
+sheet.export_dxf
+sheet.flange
+sheet.flat_pattern
+sheet.fold
+sheet.hem
+sheet.manage_rules
+sheet.path_flange
+sheet.perforate
+sheet.refold
+sheet.rules
+sheet.unfold
+sketch.arc.center_point
+sketch.arc.tangent
+sketch.arc.three_point
+sketch.auto_constrain
+sketch.auto_constrain_from_datum
+sketch.auto_project
+sketch.blend_curve
+sketch.break
+sketch.break_link
+sketch.cancel
+sketch.centerline
+sketch.chain
+sketch.chamfer.distance_angle
+sketch.chamfer.equal_distance
+sketch.chamfer.two_distance
+sketch.circle.center
+sketch.circle.three_point
+sketch.circle.three_tangent
+sketch.circle.two_point
+sketch.circle.two_tangent
+sketch.conic
+sketch.constrainer
+sketch.constraint.coincident
+sketch.constraint.collinear
+sketch.constraint.concentric
+sketch.constraint.curvature
+sketch.constraint.equal
+sketch.constraint.fix
+sketch.constraint.horizontal_vertical
+sketch.constraint.midpoint
+sketch.constraint.parallel
+sketch.constraint.perpendicular
+sketch.constraint.polygon
+sketch.constraint.symmetry
+sketch.constraint.tangent
+sketch.construction
+sketch.copy
+sketch.create
+sketch.cut
+sketch.delete
+sketch.dimension
+sketch.dimension_text
+sketch.drag
+sketch.drag_end
+sketch.draw.dimensioned
+sketch.edit
+sketch.edit_text
+sketch.ellipse
+sketch.export_dxf
+sketch.extend
+sketch.fillet
+sketch.finish
+sketch.finish_auto_constrain
+sketch.fit_curves_to_section
+sketch.glyphs
+sketch.include_3d
+sketch.infinite
+sketch.insert_dxf
+sketch.insert_svg
+sketch.inspect
+sketch.intersect
+sketch.intersection_curve
+sketch.isoparametric_curve
+sketch.line
+sketch.line.midpoint
+sketch.line3d
+sketch.loose_ends
+sketch.loose_ends.tie
+sketch.mirror
+sketch.move
+sketch.move3d
+sketch.move_point
+sketch.offset
+sketch.offset.break
+sketch.options
+sketch.paste
+sketch.pattern.circular
+sketch.pattern.rectangular
+sketch.point
+sketch.point3d
+sketch.polygon.circumscribed
+sketch.polygon.edge
+sketch.polygon.inscribed
+sketch.project
+sketch.project_to_surface
+sketch.rectangle.center
+sketch.rectangle.rounded
+sketch.rectangle.three_point
+sketch.rectangle.two_point
+sketch.redefine
+sketch.scale
+sketch.slot.arc_center
+sketch.slot.arc_three_point
+sketch.slot.center_point
+sketch.slot.center_to_center
+sketch.slot.overall
+sketch.snap
+sketch.solve
+sketch.spline.control_point
+sketch.spline.control_point_5
+sketch.spline.fit_point
+sketch.spline3d
+sketch.spun_profile
+sketch.text
+sketch.toggle_driven
+sketch.trim
+sketch.trim.path
+solid.align
+solid.boundary_fill
+solid.bounding_solid
+solid.chamfer
+solid.coil
+solid.combine
+solid.cylinder
+solid.draft
+solid.emboss
+solid.fillet
+solid.hole
+solid.loft
+solid.mirror
+solid.move
+solid.offset_face
+solid.pattern.circular
+solid.pattern.path
+solid.pattern.rectangular
+solid.pipe
+solid.press_pull
+solid.remove
+solid.replace_face
+solid.revolve
+solid.rib
+solid.scale
+solid.shell
+solid.sphere
+solid.split_body
+solid.split_face
+solid.sweep
+solid.thread
+solid.torus
+solid.web
+surface.blend
+surface.boundary
+surface.extend
+surface.extrude
+surface.fair
+surface.loft
+surface.match
+surface.offset
+surface.patch
+surface.reverse_normal
+surface.revolve
+surface.ruled
+surface.stitch
+surface.sweep
+surface.thicken
+surface.trim
+surface.unstitch
+surface.untrim
+timeline.add
+timeline.compute_all
+timeline.copy
+timeline.delete
+timeline.dependents
+timeline.edit
+timeline.export_script
+timeline.group
+timeline.inspect
+timeline.move_many
+timeline.move_to_group
+timeline.paste
+timeline.redefine
+timeline.rename
+timeline.rename_group
+timeline.reorder
+timeline.reorder_many
+timeline.roll_to
+timeline.rollback
+timeline.suppress
+timeline.ungroup
+view.ambient_occlusion
+view.apply
+view.back
+view.bottom
+view.delete
+view.front
+view.graphics_preset
+view.history_layout
+view.isometric
+view.layout
+view.left
+view.list
+view.navigate
+view.normal_to
+view.rename
+view.right
+view.save
+view.top
diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs
index 6157ccded..6f0660a48 100644
--- a/crates/mcp/src/tools.rs
+++ b/crates/mcp/src/tools.rs
@@ -75,7 +75,7 @@ pub fn tool_definitions() -> Vec {
tool(
"describe_command",
"Describe a command",
- "One command's parameter docs and, for commands with a typed contract (solid.box, solid.extrude and engine.describe so far), the \
+ "One command's parameter docs and, for commands with a typed contract (every new command, and more of the older ones as they are converted), the \
JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); null for the others.",
obj(json!({"id": string("Command id, e.g. \"solid.extrude\"")}), &["id"]),
Effect::ReadOnly,
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index e01676019..ab2bbf80d 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -27,6 +27,7 @@
- [Extensible library proposal](dev/libraries.md)
- [Local scalar libraries](dev/local-libraries.md)
- [The command engine](dev/commands.md)
+ - [Command schemas](dev/schemas.md)
- [The kernel boundary and truck](dev/kernel.md)
- [Persistent naming](dev/naming.md)
- [Test harnesses](dev/testing.md)
diff --git a/docs/book/src/dev/commands.md b/docs/book/src/dev/commands.md
index 45172a8f4..82addea7d 100644
--- a/docs/book/src/dev/commands.md
+++ b/docs/book/src/dev/commands.md
@@ -31,9 +31,21 @@ ending in the same word (`file.open`: did you mean `doc.open`?).
## Adding a command
1. Add a `CommandSpec` to the right file in `crates/engine/src/cmd/` and implement `run`.
-2. Write engine tests that measure the result: volume, area, and face/edge/vertex counts
+2. Give it input and output schemas: a parameters type (its contract) and a reply type in the
+ module for its command file under `crates/engine/src/schema/` (`schema/features.rs` for
+ `cmd/features.rs`, and so on; create it for the file's first contract), built from the shared
+ field types in `schema/types.rs`. Register them with `checked!(…)`, `.contract(…)` and
+ `.output(…)`, as `solid.extrude` does, and add the command to that module's
+ `schemas_and_the_key_check_agree` test, with error-message cases and a reply test. The
+ parameters type documents each parameter (keep the `.params(…)` prose too, for now), and
+ `describe_command` serves both schemas to agents and scripts. A test
+ (`every_command_has_input_and_output_schemas`) warns for a command without them, and will
+ fail it once the rule becomes required; the commands
+ that predate the rule are listed in `schema/unconverted.txt`, which only shrinks.
+ [Command schemas](schemas.md) walks through it, with the shared types and a checklist.
+3. Write engine tests that measure the result: volume, area, and face/edge/vertex counts
against values you can derive by hand.
-3. The hostile-input test (`hostile_params_never_panic` in `crates/engine/src/tests.rs`) runs
+4. The hostile-input test (`hostile_params_never_panic` in `crates/engine/src/tests.rs`) runs
your command automatically with every documented parameter set to junk. It must return
errors, never panic.
-4. For UI work, add a scenario (see [Test harnesses](testing.md)).
+5. For UI work, add a scenario (see [Test harnesses](testing.md)).
diff --git a/docs/book/src/dev/schemas.md b/docs/book/src/dev/schemas.md
new file mode 100644
index 000000000..f22c6d149
--- /dev/null
+++ b/docs/book/src/dev/schemas.md
@@ -0,0 +1,286 @@
+# Command schemas
+
+Every command has an input schema and an output schema (JSON Schema 2020-12), generated by
+`schemars` from two Rust types:
+
+- a **contract**: the parameters type, checked in front of the handler (see
+ `crates/engine/src/schema/mod.rs`); with the session's check level at warn or strict, a
+ misspelt key or a wrong-typed value is reported or refused instead of silently ignored;
+- a **reply type**: what a successful call returns.
+
+`engine.describe` and the MCP tool `describe_command` serve both, so agents and scripts read a
+command's exact parameters instead of guessing from prose.
+
+## When the check fails
+
+The tests in `crates/engine/src/schema/coverage_tests.rs` say what to do. A command without
+schemas is only a warning for now (the test prints the list); it will become required once the
+PR backlog is down, so give new commands both schemas now. Set `SOLIDCRAFT_SCHEMA_RULE_STRICT=1`
+to make the missing-schema check fail today.
+
+- **"`x.y` has no input or output schema"** (or "no input schema", "no output schema"): a new
+ command. Give it what it lacks, as below. Don't add it to `schema/unconverted.txt`: that list
+ holds only the commands that predate the rule.
+- **"`x.y` has its schemas now: remove its line from unconverted.txt"**: you converted an old
+ command. Delete its line.
+- **"`x.y` is a planned! placeholder, which needs no line in unconverted.txt"**: delete its line.
+- **"unconverted.txt names commands that don't exist"**: a command was removed or renamed.
+ Delete its line.
+- **"unconverted.txt must be sorted, each id once"**: keep the list in byte order
+ (`LC_ALL=C sort`).
+- **"`x.y` ran with an unknown key in strict"** or **"`x.y` should refuse with …"**: it has a
+ contract, but its `run` isn't `crate::checked!("x.y", )` (step 5): the wrapper is
+ missing or names another command's id.
+
+## Writing a contract
+
+### 1. List the keys the handler reads
+
+The contract's keys are exactly the keys the handler reads, no more and no fewer. Read the
+handler and everything it passes `p` to:
+
+- direct reads: `p.get("k")`, `params::expr(p, "k")`, `req_expr`, `str_`, `num`, `bool_`, `vec3`,
+ `string_list` and the like;
+- `features::add_feature` (every feature command) reads `name`, `body_name`, `body_names` and
+ `participants`: take them with [`FeatureCommon`](#shared-types). What `participants` changes
+ depends on the feature, and for some it changes nothing in the result: check where the
+ feature is evaluated (`crates/doc/src/eval.rs`). `participants` takes its description from
+ `FeatureCommon`, shared by every feature, so say what it does for this one elsewhere: where it
+ and another key override each other (a primitive's `targets` gives way to it; an extrude's
+ `targets` overrides it), in that key's description; where it has no effect, in the summary.
+ For the primitives (box, cylinder, sphere, torus) `add_feature` also reads `targets`; a new
+ primitive must join the `primitive` match in `add_feature_in`, and its contract declares
+ `targets`. The commands that combine bodies read `operation` (and usually `targets`) in their
+ own handlers;
+- keys read around the command: `frames::to_local` reads `body` (and `face_body`) for commands
+ that take picks;
+- `live`, for a command with `.live(…)` (today `sketch.drag` and `sketch.edit_text`): a call
+ with `live: true` goes to the live runner, which `checked!` doesn't wrap, so live calls aren't
+ checked yet. Leave those two on the list until the engine checks the live path too. A new
+ command that needs a live runner still gets its contract (declare `live` as an optional
+ `bool`); say in its pull request that its live calls aren't checked.
+
+A key the handler reads only in some situations (thin-wall keys with `thin: true`) is still a
+field; its description says when it applies. Contracts don't check combinations of keys
+(`sketch` with `face`); the handler does.
+
+### 2. Put it in the module for its command file
+
+Contracts for `cmd/features.rs` live in `schema/features.rs`, for `cmd/inspect.rs` in
+`schema/inspect.rs`, and so on, each with its tests in a file next to it
+(`schema/features_tests.rs`). For a command file's first contract, create the module and add its
+`pub mod` line, sorted, under "The contracts, by command file" in `schema/mod.rs`. A new module
+starts like this (keep the imports it uses):
+
+```rust
+//! Contracts and result types for the commands in `cmd/wedge.rs`.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use super::types::{FeatureCommon, LengthExpr, OperationParam, PointExpr3, StringList, feature_common, present};
+
+// …the parameters and reply types…
+
+#[cfg(test)]
+#[path = "wedge_tests.rs"]
+mod tests;
+```
+
+### 3. Write the parameters type
+
+```rust
+/// Add a wedge primitive.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct WedgeParams {
+ /// Size along X.
+ pub length: LengthExpr,
+ /// Size along Y.
+ pub width: LengthExpr,
+ /// Height at the thick end, along Z.
+ pub height: LengthExpr,
+ /// The wedge's minimum corner. Default: the origin.
+ #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
+ #[schemars(with = "PointExpr3")]
+ pub corner: Option,
+ /// How the wedge combines with existing bodies. Default: new.
+ #[serde(default)]
+ pub operation: Option,
+ /// The bodies a join, cut or intersect works on. Default: every body in the feature's
+ /// component, not its sub-components (an intersect removes those the wedge doesn't meet).
+ /// Ignored when `participants` lists bodies.
+ #[serde(default)]
+ pub targets: Option,
+ #[serde(flatten, deserialize_with = "feature_common")]
+ pub common: FeatureCommon,
+}
+```
+
+- **Descriptions are the documentation.** The struct's doc comment is the command's summary and
+ each field's doc comment is its description in the schema, so put nothing else on those
+ lines. Say the unit or form, the default (`Default: …`) and when the key is ignored. Write for
+ someone who has only the schema. Check what each value does where the feature is evaluated
+ (`crates/doc/src/eval.rs` and the kernel), not only how the handler reads it: a limit the
+ evaluation enforces (a torus's `minor` must be less than its `major`) or a key it ignores
+ belongs in the description.
+- **Required or optional** follows the handler: a key it can't do without is a plain field;
+ any other is `#[serde(default)] Option`.
+- **`null`:** the common readers (`str_`, `num`, `bool_`, `expr`, `string_list`) read `null` as
+ absent, which a plain `#[serde(default)] Option` matches. Readers that parse `p.get(k)`
+ themselves (`features::feature_sketch`, `features::profiles`, the pick lists) refuse `null`;
+ for those keys use `#[serde(default, deserialize_with = "present", skip_serializing_if =
+ "Option::is_none")]` with `#[schemars(with = "T")]`. The key may then be absent but not
+ `null`, the schema has no `null` branch, and `skip_serializing_if` stops schemars publishing
+ `default: null`, which the schema itself would refuse.
+- **Use a shared type** for every value it fits (below) rather than `String` or `f64`: shared
+ types accept exactly what the handlers' readers accept, give the handlers' messages, and
+ publish the matching schema.
+
+### 4. Write the reply type
+
+A feature command whose handler returns `add_feature`'s reply unchanged returns
+`FeatureResult` (in `schema/features.rs`): use it, don't copy it. A command that returns
+anything else, including a feature command that reshapes the reply (`solid.thread` returns
+`{feature, name, thread}`), gets its own reply type:
+
+```rust
+/// What `wedge.measure` returns.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct WedgeMeasureResult {
+ /// The wedge's volume, in mm³.
+ pub volume: f64,
+ /// In the warn parameter-check mode: what the call's parameters got wrong.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub param_warnings: Vec,
+}
+```
+
+- Build the handler's reply from the type (`serde_json::to_value(reply)`), as `add_feature_in`
+ builds `FeatureResult`, rather than a `json!` literal next to it. Then the schema can't drift
+ from what the command returns.
+- Warn mode adds `param_warnings` to a successful reply that is a JSON object, so an object
+ reply type keeps that field. A reply that isn't an object (a list) is returned unchanged and
+ has no such field.
+
+### 5. Register them
+
+In the command file, next to its `COMMANDS`:
+
+```rust
+use crate::schema::features::FeatureResult;
+use crate::schema::wedge::WedgeParams;
+use crate::schema::{TypedContract, output_schema_for};
+
+const WEDGE_CONTRACT: TypedContract = TypedContract::new();
+
+// in COMMANDS:
+CommandSpec::new("solid.wedge", "Wedge", crate::checked!("solid.wedge", prim_wedge))
+ .at("SOLID", "CREATE")
+ .icon("wedge")
+ .contract(&WEDGE_CONTRACT)
+ .output(output_schema_for::)
+ .params("length, width, height: expr; corner?: [x,y,z] …"),
+```
+
+`.contract` and `.output` publish the schemas, and `checked!` checks each call against the
+contract that its id publishes, in front of the handler, so what is checked is always what is
+published. The handler itself doesn't change: it still reads the raw parameters. Keep the
+`.params(…)` prose: the command list, the palette and `describe_command`'s `params` still show
+it, until it is generated from the schemas.
+
+### 6. Test it
+
+In the module's tests file:
+
+- **`schemas_and_the_key_check_agree`:** add `assert_keys(input_schema_for::(),
+ &[…])` with the keys, sorted, `FeatureCommon`'s included. The keys then change only on
+ purpose.
+- **`strict_keeps_todays_errors`:** for calls the handler already refuses (a malformed value,
+ an unknown spelling), add cases to `assert_strict_keeps_todays_errors`: strict must give the
+ same message as the handler. Leave out the cases its documentation lists as different on
+ purpose, such as a missing required key (strict says `` `length` is required ``, the handler
+ something else).
+- **A reply test:** run the command and check the reply matches its output schema with
+ `conforms` (`replies_match_the_output_schema` in `schema/features_tests.rs` shows how; its
+ misspelt-key call checks that a reply carrying warnings still matches). Run every form the
+ command takes (each alternative key, such as `corner` or `center`, each `operation`, one name
+ and a list of names) in Warn, and check those replies have no `param_warnings`: Warn runs a
+ call the contract refuses anyway, so a matching reply doesn't show the contract accepts the
+ call. A reply that isn't an object never carries `param_warnings`; run those calls in Strict,
+ where a refused call is an error.
+
+`schema_defaults_are_valid` checks the `default` of each top-level parameter on its own; a
+nested type's defaults are yours to check.
+
+### 7. Converting a command that already exists
+
+Do steps 1 to 6, remove its line from `schema/unconverted.txt`, then check the contract against
+every caller the tests have: run the whole suite with the audit recorder and summarise it.
+
+```text
+mkdir -p audit
+SOLIDCRAFT_PARAM_AUDIT=$PWD/audit cargo test --workspace --no-fail-fast --features solidcraft-engine/param-audit
+python3 scripts/param_audit.py audit
+```
+
+The recorder doesn't create the directory, and it writes nothing if it can't, so check the
+summary's first line says at least one file. Each line under "SUCCEEDS TODAY, STRICT WOULD
+REFUSE" is a call that works today and that strict would refuse: a form the contract is
+missing (fix the contract) or a caller's mistake, such as a misspelt key (fix the caller). Put
+the summary in the pull request.
+
+## Shared types
+
+In `crates/engine/src/schema/types.rs`. Each accepts exactly what its reader accepts, most by
+calling that reader.
+
+| Type | For | Matches |
+| --- | --- | --- |
+| `LengthExpr`, `AngleExpr` | a number or an expression (`"w / 2"`, `"30 deg"`) | `params::expr` |
+| `Point3`, `Point2` | `[x, y, z]` / `[x, y]` or `{x, y, z}` of numbers, in mm | `params::vec3`, `params::vec2` |
+| `PointExpr3` | a placement point whose coordinates may be expressions | `features::point_param` |
+| `IdOrName` | a feature by id or name (extrude's `sketch`) | `features::feature_sketch` |
+| `SketchRef` | a sketch by id or name, with `features::sketch_id`'s message | `features::sketch_id` |
+| `StringList` | one name or a list of names | `params::string_list` |
+| `OperationParam` | new, join, cut, intersect and their spellings | `Operation::parse` |
+| `FaceRef` | a face by a point on it or its name | `face::face_ref` |
+| `FaceRefs` | the `faces` list of shell, draft, offset face, split face and `face.delete` (not `solid.replace_face`, whose messages differ) | `features::face_points` |
+| `EdgeRef`, `EdgeRefs` | an edge by a point on it or `{body, index}`; fillet's and chamfer's `edges` | `features::edge_points` |
+| `ProfilesParam` | which sketch profiles | `features::profiles` |
+| `FeatureCommon` | `name`, `body_name`, `body_names`, `participants`, flattened | `features::add_feature` |
+
+### When no shared type fits
+
+Add one to `types.rs`, next to the reader it mirrors:
+
+- Its `Deserialize` calls the **handler's own reader**, so "the contract accepts it" means "the
+ handler accepts it". Don't re-implement the parsing. Many readers are private to their command
+ file or need the design (`features::point_param` takes the `Session`). Split out the part that
+ only looks at the JSON as a `pub(crate)` function, have the handler call it, and re-export it
+ from `cmd/mod.rs`, as `face_ref_form` and `edge_ref_form` are; whether the value finds
+ something in the design stays in the handler.
+- On failure it gives the **handler's message**. Wrap a message that is already a whole
+ sentence, such as the handler's ``unknown operation `x` (…)``, in `whole(…)`, and the check
+ passes it on as it is. Otherwise start it with "must": the check names the key, so "must be a
+ point [x, y, z] of numbers" becomes ``"`corner` must be a point [x, y, z] of numbers"``. (Any
+ other message comes out as ``"`corner`: …"``.)
+- Its `JsonSchema` describes the same values, with a description. Where JSON Schema can't say
+ something the reader checks (ignoring case, a byte length), say it in the description.
+- Test both: values the reader accepts and refuses are accepted and refused by the type, and
+ they match the schema (the `conforms` helper in `schema/tests.rs`; see
+ `face_and_edge_refs_match_the_pick_readers`).
+- A handler that reads a key more leniently than any type can (a wrong-typed value read as if
+ the key were absent) gets the stricter type: that difference is what warn and strict report.
+
+## Checklist
+
+1. The contract's keys are exactly the handler's reads, including `add_feature`'s, the frame
+ mapping's and `live`.
+2. The struct and every field have descriptions, with defaults and when a key is ignored.
+3. Shared types wherever they fit; a new type calls the handler's reader and gives its message.
+4. `FeatureResult` for a command that returns `add_feature`'s reply unchanged, else a reply type
+ the handler builds its reply from.
+5. `checked!`, `.contract` and `.output` on the `CommandSpec`, and the `.params` prose kept.
+6. `assert_keys`, error-message cases, a reply test.
+7. For an existing command: its `unconverted.txt` line removed and the audit summary in the PR.
diff --git a/docs/mcp.md b/docs/mcp.md
index 955b43717..464d9dba3 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -65,8 +65,8 @@ temporary file by the app and read back by the server, so both must run on the s
### Parameter checking
-Commands with a typed parameter contract (`solid.box`, `solid.extrude` and `engine.describe`
-so far; `describe_command` shows a command's schemas) can be checked as they are called.
+Commands with a typed parameter contract (every new command, and more of the older ones as they
+are converted; `describe_command` shows a command's schemas) can be checked as they are called.
`--param-check off|warn|strict` sets the level for a headless session, including a script or
recipe given with `--in`; the default is `off`, which changes nothing. `warn` runs the call and
adds `param_warnings` to its result, such as ``unknown key `operaton`; did you mean
@@ -254,7 +254,7 @@ The `skill_reference` tool returns these documents from the copies built into So
| Tool | Arguments | What it does |
|---|---|---|
| `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. `filter` matches id, label, tab and panel. |
-| `describe_command` | `id` | One command's parameter docs (`params`) and, for commands with a typed contract (`solid.box`, `solid.extrude` and `engine.describe` so far), the JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); `null` for the others. The same as `execute` `engine.describe {command}`. |
+| `describe_command` | `id` | One command's parameter docs (`params`) and, for commands with a typed contract (every new command, and more of the older ones as they are converted), the JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); `null` for the others. The same as `execute` `engine.describe {command}`. |
| `execute` | `command`, `params?`, `verbose?` (default true) | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. A feature command replies with the feature (`feature`, `name`), every body (`bodies`) and the bodies it created, changed and removed (`created_bodies`, `changed_bodies`, `removed_bodies`). `verbose: false` uses the same compact reply as `batch`. |
| `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?`, `coalesce_parameters?` (default false) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`), every result before it, `rolled_back` (true only when the design really went back to where the batch started), `undone`, `applied` (the indices of the steps whose changes are in the design) and `not_run` (the steps never sent). A step may name a tool instead of a command, with that tool's arguments as `params`: `set_parameter` (runs `parameters.change`; `value` or `expression`), `list_commands` (`engine.commands`, filtered by `filter` as the tool filters it), `describe_command` (`engine.describe`), `execute` (`{command, params}`), `measure`, `inspect_design` (`document.inspect`: each sketch as its counts, not its full contents, and no joints), `undo`, `redo`, `export`, `save`, `open`, `new_design` and `crash_reports`. `screenshot`, `body_topology` (use `model.edges` and `model.faces`), `batch`, `pending`, `running` and `skill_reference` can't be steps: such a batch fails before anything is sent. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. `timings: true` adds `timings: [{index, command, ms}]` for every step run, the failing one included, and `total_ms`. `profile: true` also adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`, its time in kernel booleans, in tessellation and the rest. Steps are timed where they run: in the app when bridged. An app without `engine.batch` is timed step by step, without `profile`. `coalesce_parameters: true` sets each run of consecutive plain parameter edits (`parameters.change` or `set_parameter` with a name and a value, or `changes`) together, so the design rebuilds once per run instead of once per edit. Steps between runs see the design up to date. Each step keeps its own result (`coalesced`: the run's length), and the run is one undo step. The run skips the states between its edits, so an edit refused on its own can go through with the run's later ones. A refused run goes step by step, naming the refused step. |
| `inspect_design` | `measure?` (default true), `sketches?` (default true), `joints?` (default true) | Design properties (`metadata`: project, author… and other tools' keys; set them with `execute` `document.metadata.set`), parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible; `removed_later: true` while a sketch is being edited on a rolled-back timeline and a later feature deletes the body, which is then not shown), sketches (curves, points, constraints, profiles, DOF, solve status, visible), joints when the design has any (as `joint.inspect` gives them: each origin's occurrence, component and path, the snap as saved, the feature, face, edge or sketch curve (`sketch: {id, name, curve}`) its persistent names refer to, `resolves` and the `error` when it is lost; kind, offset, angle, flip, values, limits, expressions, motion links; `execute` `joint.inspect {joint}` gives one joint), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). |