feat(mechanisms): carry the laws every kinematics.py kept rewriting

Thirteen projects wrote the same textbook geometry out by hand, each in
its own frame and sign convention, and the numeric-only copies broke the
moment a symbolic driver reached them. solid_node.mechanisms carries
them once: the external spur-gear mesh and its inverse, the lead screw,
the planar slider-crank, linear delta kinematics, and the circle
geometry a linkage asks for.

Every law is a composition over solid_node.math and arithmetic, so it
computes on numbers and builds the viewer's deferred expression on
symbolic time or a driver, and emits no OpenSCAD builtin the ADR-022
parity corpus does not already pin. A gear library's convention enters
as two reference angles rather than a fork of the law: cq_gears' gap
centre at 180 / teeth, MrBunsy's at gap_angle / 2. There is no declared
face -- the laws carry degree literals the ADR-062 algebra cannot type
as angles, so a declared token raises at class definition and .value is
the documented way through.

delta_rod returns two rotations about constant axes rather than one
about the perpendicular the rod leans about, because a Rotation's axis
cannot carry a driver symbol; that finding cost kossel a rendered mesh
and is now a docstring and a spec scenario.

Checked against the function each law was lifted from, in that project's
own repository: gearbox at 2.27e-13 over 900 cases, wall_clock_01's real
train at 8.53e-14, and v8-engine, kossel, the grasshopper, openflexure
and Inmoov at exactly 0.0.

OpenSpec change mechanisms, archived; ADR-076.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147ScXEqYBQkKGv9ruLSmxR

Author: lfagundes

docs/adrs/MATH/ADR-076-mechanism-laws-as-compositions-over-expression-math.md

@@ -0,0 +1,143 @@
+# ADR-076: Mechanism Laws as Compositions Over Expression Math
+
+**Status:** Accepted
+**Date:** 2026-09-06
+**Depends on:**
+- [ADR-022: Cross-Runtime Degree-Trig Parity for `$t` Expression Evaluation](ADR-022-cross-runtime-degree-trig-parity-for-t-expressions.md)
+
+**Related to:**
+- [ADR-062: Typed Parameters and the Exponent Algebra](../NODE/ADR-062-typed-parameters-and-the-exponent-algebra.md)
+- [ADR-056: Signals, Drivers, Ports, and Stepped Simulation](../NODE/ADR-056-signals-drivers-ports-and-stepped-simulation.md)
+
+## Context and Problem Statement
+
+Thirteen mechanical projects in the development workspace carry a
+`kinematics.py`, and beneath each project's own arithmetic sit a handful
+of textbook mechanism laws, written again and again:
+
+- the **external spur-gear mesh**, four times — `conjugate_angle` in
+  `sandbox/gearbox` over cq_gears' conventions, and
+  `pinion_angle_for_wheel` / `wheel_angle_for_pinion` in three
+  `3DPrintedClocks` designs over the MrBunsy `Gear` object's;
+- the **lead screw**, three times, in `Inmoov-sim`,
+  `openflexure-microscope` and `snappy-reprap`, each `lead * angle / 360`
+  with its own sign;
+- **circle geometry**, three shapes — a circle-circle intersection with a
+  side, the law of cosines, and the `sqrt(L² − d²)` rise of a rigid link;
+- the **slider-crank**, in `v8-engine`;
+- **linear delta kinematics**, in `kossel`.
+
+Each is a law, not a design decision. Each copy nevertheless carried a
+convention its author had to rediscover against a rendered mesh — where a
+gear library says a tooth sits at zero, which way a screw's handedness
+falls, which of two circle intersections is meant — and getting one half a
+tooth wrong looks like nothing: the numbers still read plausibly, the
+leaves just land on the teeth.
+
+Worse, several copies were **numeric-only**. A law written with Python's
+`math` raises `TypeError: must be real number, not OpenSCADConstant` the
+instant a symbolic driver or `$t` reaches it (ADR-022), so it works under a
+keyframe test and kills `solid develop` at the first non-linear mechanism.
+
+The museum of printers the shop plans to simulate — deltas, corexy,
+i3-style — will write the delta and the screw again unless the framework
+carries them.
+
+## Decision Drivers
+
+- **A law belongs where it is written once.** Rediscovering a sign
+  convention per project is the cost this is meant to remove.
+- **Both faces, for free.** Anything a project's `simulate()` calls must
+  compute at a keyframe *and* build the viewer's deferred expression.
+- **No new cross-runtime surface.** ADR-022's parity is enforced by a
+  producer-generated fixture over a fixed corpus; a mechanism package that
+  emitted a new OpenSCAD builtin would silently widen the contract three
+  runtimes must satisfy.
+- **A library's convention must not fork the law.** Two gear libraries
+  already disagree about zero, and more will.
+- **The dimension algebra (ADR-062) cannot type a degree literal.** A
+  plain number is dimensionless and `Angle` is its own axis.
+
+## Considered Options
+
+1. **Leave the laws in the projects.** Each project keeps its copy.
+2. **A framework package named `solid_node.kinematics`.**
+3. **A mesh law that reads the gear object**, branching per library.
+4. **Add an `Angle`-typed literal to the dimension algebra**, so a law's
+   `+ 180` could be spelled in a class body and every law would have the
+   third, declared face too.
+5. **A framework package `solid_node.mechanisms`**, one module per family,
+   every law a composition over `solid_node.math`, gear conventions passed
+   in as reference angles, and no declared face.
+
+## Decision Outcome
+
+**Option 5.** `solid_node.mechanisms` carries the laws, with three
+properties that are the actual decision:
+
+**Compositions, not a new evaluator.** Every function is written over
+`solid_node.math` and ordinary arithmetic and has exactly one definition.
+It therefore inherits that module's numeric and symbolic faces, and the
+symbolic string it builds contains only calls ADR-022's corpus already
+pins. The `mechanisms` spec makes that a *requirement*: a future law that
+wanted a new builtin must go through `solid_node.math` first, where the
+corpus rule lives. The package needed no extension of the parity fixture.
+
+**Reference angles as the seam.** `meshed_angle` takes `driver_gap` and
+`driven_tooth` — plain angles saying where a gap centre and a tooth tip
+point at angle zero — and reads no gear object. cq_gears' convention is
+then `180 / teeth` and MrBunsy's is `gap_angle / 2`, two lines in the
+caller rather than a branch in the law. The two references are asymmetric
+on purpose: what defines a mesh is a tooth of the driven pointing into a
+gap of the driver.
+
+**Two faces, and the third refused loudly.** `meshed_angle` contains
+`+ 180` and `screw_travel` contains `/ 360`. Under ADR-062 a declared
+`Angle` plus a plain number raises, so a declared token reaching a law
+raises `DimensionError` at class definition — early and loud, rather than
+yielding a formula with a wrong dimension. The package states this and
+documents `.value` as the way through for a static mesh phase, which is
+the algebra's own escape hatch. One spec scenario pins both halves.
+
+Option 1 was rejected as the status quo the evidence indicts. Option 2 was
+rejected on naming: `kinematics.py` is what every project calls its own
+module, and the `kinematics` OpenSpec capability already means operations,
+poses and the expression contract. Option 3 was rejected because it makes
+the law's shape a function of a third-party object's API. Option 4 is a
+real gap in ADR-062 and would give these laws and any other degree-literal
+arithmetic a proper third face — but it is an algebra change with its own
+consequences and belongs to its own cycle; it is recorded as an open
+question rather than folded in here.
+
+## Consequences
+
+- The framework now has an opinion about mechanism conventions, and each
+  is stated in the family module a law lives in: the mesh's common frame
+  and reference angles, the screw's right-hand rule (handedness and
+  nut-versus-screw stay the caller's minus sign), the crank's
+  `(across, along)` plane with zero at top dead centre, the delta's
+  `radius` and its two-rotation posing recipe, and the linkage side rule.
+- Names are unique across families by rule — `crank_rod_angle`, not
+  `rod_angle`; `delta_rod`, not `rod_tilt` — so the flat re-export can
+  stay flat as families grow.
+- `delta_rod` returns two rotations about *constant* axes rather than one
+  about the perpendicular the rod actually leans about, because a
+  `Rotation`'s axis cannot carry a driver symbol (ADR-056). That framework
+  finding, which cost `kossel` a rendered mesh to discover, is now a
+  docstring and a spec scenario.
+- Nothing guards an unreachable configuration. A `sqrt` or `acos` out of
+  range raises numerically and is NaN symbolically, exactly as
+  `solid_node.math`, OpenSCAD and the viewer behave. A guard would have to
+  invent a pose that does not exist.
+- No existing behaviour changes: the package is new, imported by nothing at
+  startup, and depends only on `sin`, `cos`, `asin`, `acos`, `atan2` and
+  `sqrt`.
+- Each law was checked against the function it was lifted from, in that
+  project's own repository, as uncommitted evidence: gearbox 900 cases at
+  2.27e-13, wall_clock_01's real train at 8.53e-14, and v8-engine, kossel,
+  the grasshopper, openflexure and Inmoov at exactly 0.0.
+- Open questions carried forward: an `Angle`-typed literal in the algebra
+  (Option 4), and whether openflexure's four-bar `leg_lean` / `lever_rise`
+  becomes a law once a second flexure stage appears.
+
+Change record: `openspec/changes/archive/2026-09-06-mechanisms/`.

docs/adrs/README.md

@@ -85,6 +85,7 @@ that way.
 
 ### MATH — expression evaluation parity
 - [ADR-022](MATH/ADR-022-cross-runtime-degree-trig-parity-for-t-expressions.md) — Cross-runtime degree-trig parity for `$t` and driver expressions — **Accepted**, revised 2026-09-06 (defect fixed and parity enforced 2026-08-26; vocabulary widened beyond trigonometry, and the corpus must cover every emitted name)
+- [ADR-076](MATH/ADR-076-mechanism-laws-as-compositions-over-expression-math.md) — Mechanism laws as compositions over expression math — **Accepted**, depends on 022
 
 ### TEST-FRAMEWORK — CAD testing
 - [ADR-009](TEST-FRAMEWORK/ADR-009-trimesh-based-mesh-assertions-for-cad-testing.md) — Trimesh mesh assertions — **Accepted**, extended by 025

docs/animation.rst

@@ -184,6 +184,26 @@ by a driver-derived angle survives the viewer::
 about=...)`` turns a 2D point about a centre, and ``rotate_x``,
 ``rotate_y`` and ``rotate_z`` turn a 3D point about an axis. All
 degrees, all right-handed, all returning plain tuples.
+Before writing a mechanism out longhand over those functions, look in
+`solid_node.mechanisms`: it carries the laws projects kept rewriting —
+the external spur-gear mesh, the lead screw, the slider-crank, linear
+delta kinematics, and the circle geometry a linkage keeps asking for.
+Each is a composition over `solid_node.math`, so it has that module's
+numeric and symbolic faces — and only those two: a mechanism law carries
+degree literals the dimension algebra cannot type, so unlike the
+functions of `solid_node.math` it has no third, declared face, and
+reaching one from a class body raises there. Each states its frame, its
+zero and its sign in the family module it lives in. See :doc:`the API
+reference <api-reference>`.
+
+The delta is the worked reason the package exists. A rod leaning toward
+a moving effector leans about a direction that the effector's position
+decides — and a `Rotation`'s axis is a *constant*: it cannot carry a
+driver symbol, so ``rotate(angle, computed_axis)`` works in a test and
+fails in the viewer. `delta_rod` therefore returns two rotations about
+constant axes, ``-tilt`` about Y then ``azimuth`` about Z, which is the
+same pose and survives symbolically. That finding cost one project a
+rendered mesh to discover; it is now a docstring.
 
 .. _time-base:
 

docs/api-reference.rst

@@ -249,7 +249,7 @@ scenario tests.
 .. autofunction:: solid_node.simulation.qualified_instructions
 
 Expression math
-===============
+========
 
 ``solid_node.math`` is the one expression semantics: OpenSCAD's degree
 conventions, computed on plain numbers, deferred as an OpenSCAD
@@ -315,6 +315,111 @@ counter-clockwise, as everywhere else.
 .. autofunction:: solid_node.math.rotate_x
 .. autofunction:: solid_node.math.rotate_y
 .. autofunction:: solid_node.math.rotate_z
+=======
+Mechanisms
+==========
+
+The textbook mechanism laws, importable from
+``solid_node.mechanisms``. Each is a composition over
+``solid_node.math`` and so has two of that module's three faces: it
+computes a number when the node is posed at a keyframe, and builds the
+equivalent deferred OpenSCAD expression when its driving argument is
+animation time or a driver. The third — a formula over declared
+parameters — it deliberately does not have; see below. Every angle is
+in degrees, positive by the right-hand rule about the axis each family
+states. Read the family module's docstring for its frame, its zero and
+its sign before calling into it.
+
+There is **no declared (class-body) face**. The laws carry degree
+literals — the mesh adds ``180``, the screw divides by ``360`` — and the
+dimension algebra has no way to type a plain number as an angle, so a
+declared token reaching a law raises ``DimensionError`` at class
+definition. A class body that needs a static mesh phase computes it over
+``.value`` operands, the algebra's stated escape hatch::
+
+    class Train(AssemblyNode):
+        wheel = Count(60)
+        pinion = Count(8)
+        phase = Angle(0.0)
+        pinion_phase = meshed_angle(phase.value, wheel.value, pinion.value)
+
+Gears
+-----
+
+The external spur-gear mesh. A pair is meshed when a tooth of the driven
+points into a gap of the driver along the line of centres; where a tooth
+sits at zero is the gear library's business, so the law takes it as two
+plain reference angles and reads no gear object. ``driver_gap`` is the
+direction of a gap centre in the driver's own frame at angle zero,
+``driven_tooth`` the direction of a tooth tip in the driven's. cq_gears
+centres a tooth on +X, so its gap centre is ``180 / teeth``; MrBunsy's
+``Gear`` starts at a gap, so its gap centre is ``gap_angle / 2`` and its
+tooth tip ``gap_angle + tooth_angle / 2``, both negated for a flipped
+part and zero for a lantern pinion.
+
+.. autofunction:: solid_node.mechanisms.meshed_angle
+
+.. autofunction:: solid_node.mechanisms.driving_angle
+
+Screws
+------
+
+The lead screw, right-hand and sign-neutral: a positive turn by the
+right-hand rule about the screw's own axis advances it along that axis
+relative to its nut. A left-hand thread, a nut moving instead of a
+screw, or a lever that inverts is the caller's minus sign, where it can
+be read beside the reason for it. ``lead`` is the advance per turn —
+pitch times starts, never bare pitch.
+
+.. autofunction:: solid_node.mechanisms.screw_travel
+
+.. autofunction:: solid_node.mechanisms.screw_angle
+
+Cranks
+------
+
+The planar slider-crank, in the crank's own plane: the crank axis is the
+plane normal, the cylinder axis is *along*, the other coordinate is
+*across*, and the crank angle is measured from *along*, zero at top dead
+centre. A caller whose crank axis is elsewhere maps these with its own
+frame rotation.
+
+.. autofunction:: solid_node.mechanisms.crank_pin
+
+.. autofunction:: solid_node.mechanisms.crank_rod_angle
+
+.. autofunction:: solid_node.mechanisms.piston_height
+
+Deltas
+------
+
+Linear delta kinematics: towers on a circle about Z, carriages riding
+vertically, a diagonal rod to the effector. ``radius`` is the horizontal
+distance from an effector joint to its carriage joint with the effector
+at the origin. ``delta_rod`` returns two rotations about *constant* axes
+rather than one about the perpendicular the lean happens about, because
+a ``Rotation``'s axis cannot carry a driver symbol; pose a rod authored
+along Z by ``-tilt`` about Y, then ``azimuth`` about Z.
+
+.. autofunction:: solid_node.mechanisms.delta_carriage
+
+.. autofunction:: solid_node.mechanisms.delta_rod
+
+Linkages
+--------
+
+Circle geometry. ``side = 1`` picks the intersection to the left of the
+direction from the first centre to the second. None of the three guards
+an unreachable configuration: a ``sqrt`` or ``acos`` out of range raises
+numerically, exactly as ``solid_node.math`` raises, and is NaN
+symbolically, exactly as OpenSCAD and the viewer are — a guard would
+have to invent a pose that does not exist.
+
+.. autofunction:: solid_node.mechanisms.circle_intersection
+
+.. autofunction:: solid_node.mechanisms.triangle_angle
+
+.. autofunction:: solid_node.mechanisms.link_rise
 
 Testing
 =======

docs/architecture.md

@@ -1018,6 +1018,28 @@ round-half-to-even included, for the same reason. The fixture itself is
 committed in the viewer repository (ADR-068), so widening the vocabulary
 is one change here and one there.
 
+### Mechanisms (MATH · in spec `mechanisms`)
+
+`solid_node/mechanisms/` carries the textbook mechanism laws that a
+project's own `kinematics.py` kept rewriting (ADR-076): the external
+spur-gear mesh and its inverse, the lead screw, the planar slider-crank,
+linear delta kinematics, and the circle geometry a linkage asks for. One
+module per family — `gears`, `screws`, `cranks`, `deltas`, `linkages` —
+with the family's frame, zero and sign stated once at its top, and an
+eager flat re-export whose names are unique across families.
+
+Three properties make it a subsystem rather than a utility drawer. Every
+law is a **composition over `solid_node.math`** and arithmetic, so it has
+that module's numeric and symbolic faces and emits **no OpenSCAD builtin
+the parity corpus above does not already pin** — the `mechanisms` spec
+requires that, so a law wanting a new builtin must go through `math.py`
+first. A gear library's convention enters as **reference angles**
+(`driver_gap`, `driven_tooth`), not as a fork of the law or a read of a
+gear object. And there is **no declared face**: the laws carry degree
+literals the ADR-062 algebra cannot type as angles, so a declared token
+reaching one raises `DimensionError` at class definition, with `.value`
+as the documented way through.
+
 ## Load-bearing invariants
 
 The short list that changes must not silently break:
@@ -1117,6 +1139,7 @@ The short list that changes must not silently break:
 | Node model | `solid_node/node/`, `solid_node/exact.py` | `node-model`, `exact-geometry`, `flexible-parts` | 001–004, 006, 026, 044–045, 047, 053–055, 057 |
 | Build parameters | `solid_node/parameters.py`, `node/declarative.py` | `declarative-nodes` | 061–065 |
 | Kinematics | `node/operations.py`, `node/assembly.py`, `math.py` | `kinematics` | 008, 022, 023, 028 |
+| Mechanisms | `solid_node/mechanisms/` | `mechanisms` | 022, 076 |
 | Build pipeline | `solid_node/core/` | `build-pipeline` | 005–007, 018, 026 |
 | CLI | `cli.py`, `solid_node/manager/` | `cli` | 021, 024, 068 |
 | Test framework | `solid_node/test.py`, `manager/test.py` | `test-framework` | 009–011, 025, 029, 040, 048, 052, 070, 073 |

docs/changelog.rst

@@ -36,6 +36,27 @@ with a declared parameter, which used to render the declaration's
 ``repr()`` into the published expression, now raises. See
 :ref:`Non-linear kinematics <non-linear-kinematics>`. (OpenSpec change
 ``expression-math``; ADR-022, revised.)
+**The mechanism laws, carried once.** ``solid_node.mechanisms`` holds
+the textbook geometry thirteen projects' ``kinematics.py`` kept
+rewriting, each in its own frame and sign convention: the external
+spur-gear mesh and its inverse (``meshed_angle``, ``driving_angle``),
+the lead screw (``screw_travel``, ``screw_angle``), the planar
+slider-crank (``crank_pin``, ``crank_rod_angle``, ``piston_height``),
+linear delta kinematics (``delta_carriage``, ``delta_rod``) and the
+circle geometry a linkage asks for (``circle_intersection``,
+``triangle_angle``, ``link_rise``). Every one is a composition over
+``solid_node.math``, so it computes on numbers and builds the viewer's
+expression on symbolic time or a driver, and emits no OpenSCAD builtin
+that module does not already emit. A gear library's convention is two
+argument values rather than a fork of the law: cq_gears' gap centre at
+``180 / teeth``, MrBunsy's at ``gap_angle / 2``. There is no declared
+(class-body) face — the laws carry degree literals the dimension
+algebra cannot type as angles, so a declared token raises there and
+``.value`` is the way through. Lifted from ``sandbox/gearbox``,
+``3DPrintedClocks`` (``wall_clock_01`` and the grasshopper),
+``v8-engine``, ``kossel``, ``openflexure-microscope``, ``Inmoov-sim``
+and ``snappy-reprap``, and checked against each of their own functions.
+(OpenSpec change ``mechanisms``.)
 
 **Several models in one project.** A manifest may declare its models by
 name in ``[tool.solid-node.models]``, with ``model`` naming the default