Skeleton: design language, modules, archetypes, preflight
12,252 words17 subsections20 tables7 listingsPlan version 1.1
On this page17
14.1 What it owns
Skeleton owns what a robot is before anything moves: the design term and its two views (frob-design); the
reusable module format and its contracts (frob-design); the model compiler and its memo graph (frob-model);
import and export with loss reports (frob-io); the catalog of eighteen archetypes shipped in
assets/archetypes/; and the staging of the preflight that the verb design.check runs. The analyses the
preflight calls are Atelier's (§28, A-01 to A-16) and live in frob-analyze. Skeleton fixes their order, what
each stage may refuse, and the budgets they are measured against.
14.2 Decisions
- ADR-SKEL-01: a design is a term, and a file is a view of the term. The canonical form is JSON with schema
name
frob.design/1and extension.fbot.DesignIdis the BLAKE3 hash of the canonical bytes. Reason: constructors, typed edits, lineage and incremental compilation all need a tree with stable subterms, and a hash needs one byte representation. - ADR-SKEL-02: two lossless views, one identity. The same term can be read and written as an S-expression.
The two views are in bijection on canonical forms and yield the same
DesignId. The S-expression view is optional for every consumer. This closes OPEN-SKEL-1. Reason: agents edit nested terms more reliably in a syntax with one bracket kind and quantity atoms, while tools and wire formats want JSON. FrankenSim'sfs-iralready keeps canonical S-expressions and a lossless JSON mapping in step as a tested property (FACT:frankensim/crates/fs-ir/src/lib.rs), and its reader and quantity atoms are reused through the airlock if they pass admission; a design is not a FrankenScript program and carries no verbs. - ADR-SKEL-03: no physics field has a silent default. Fill, material, contact law, joint limits and an actuator's current convention must be written. Reason: each of these defaults yields a plausible wrong robot (§14.5 gives the mass case), and the standing rule is that a missing or misspelt parameter is a refusal.
- ADR-SKEL-04: symmetry is computed, and a declaration is an assertion. A design may state the groups it expects. The compiler computes Γ_mech and Γ_obs (§13.4) and refuses on a mismatch. The declared value never overrides the computed one. Reason: a declaration that is trusted is a way to tie weights under a false group.
- ADR-SKEL-05: modules are referenced by content hash and carry contracts. A substitution reuses exactly what the contract covers and invalidates the rest by rule (§14.6). Reason: reuse without a stated boundary is how a stale certificate survives an edit.
- ADR-SKEL-06: shared resources are parts of the design. The power bus and the shared thermal sink are written in the term, because they couple limbs that the kinematic tree separates.
- ADR-SKEL-07: optimizers move levers only. Continuous optimization and co-design may change a parameter only if the design declares it as a lever with bounds and a manifold kind. Agents may make any typed edit. Reason: an optimizer that can touch every number finds the numbers nobody meant to free.
- ADR-SKEL-08: preflight is
design check. There is one verb, with eight stages in a fixed order, each able to refuse the next. Stages 1 to 6 need only the design. Stages 7 and 8 also need a task and a scene and run when those are supplied. Reason: check before you simulate (§28), and a second pre-simulation gate with a second name would be two sources of truth. - ADR-SKEL-09: every compile product records the fields it read. Invalidation after an edit is computed from those records, not from a hand-kept table (§14.9).
14.3 The design term
A design is a term, not a file of numbers. Its leaves are components and its internal nodes are constructors.
- Components.
Body(a Region with a fill and a material),Joint(a screw basis with limits),Actuator(a card reference, §15),Transmission,Battery,Sensor(§20),Wheel,Track,Foot,Payload. Each exposes typed ports (C-12): mechanical (twist and wrench at a frame), shaft (ω, τ), electrical (V, I), thermal (T, Q̇) and signal (a typed message with a rate). A signal may fan out to several consumers. A power port joins exactly one junction, and a junction balances its flows; duplicating a power port as if it were a signal would double the energy and is refused (FROB-REF-108). - Constructors.
attach(parent_port, child),serial(k, link),mirror(plane, limb),radial(n, axis, limb),scale(factor, sub),replace(path, component),closure(port_a, port_b)for kinematic loops, anduse(module, port, bindings)for a module import (§14.6). - Parameters. Every parameter has a unit, bounds, a manifold kind (ℝ, ℝ₊, S¹, S², SE(3), the inertia cone,
or a finite set of catalog choices), and a provenance:
designed,datasheet,measuredorassumed. A parameter may also carry an uncertainty and, when it is a lever, a prior for search.
The two nested mirror constructors in the example of §14.4 make the symmetry C₂ × C₂ a property of the term,
not something to be rediscovered. The forward lidar in the same example reduces Γ_obs to C₂, and the design
says so in its symmetry block, which the compiler checks.
14.4 The .fbot format
A design is stored canonically as JSON with schema frob.design/1, and its DesignId is the hash of the
canonical form. A complete small design:
{ "schema": "frob.design/1", "name": "quad-a",
"root": { "body": "torso", "region": {"box": ["0.42 m", "0.20 m", "0.10 m"]},
"fill": {"shell": "2.5 mm"}, "material": "al-6061-t6",
"ports": {"hip_mount": {"xyz": ["0.19 m", "0.08 m", "0 m"]}} },
"limbs": { "mirror": "xz", "of": { "mirror": "yz", "of": {
"attach": "torso.hip_mount",
"chain": [
{ "joint": {"class": "R", "axis": [1,0,0], "limits": ["-45 deg", "45 deg"]}, "actuator": "qdd-m",
"body": {"region": {"capsule": ["0.03 m", "0.06 m"]}, "fill": "solid", "material": "al-6061-t6"} },
{ "joint": {"class": "R", "axis": [0,1,0], "limits": ["-90 deg", "150 deg"]}, "actuator": "qdd-m",
"body": {"region": {"capsule": ["0.025 m", "0.21 m"]}, "fill": {"shell": "2 mm"},
"material": "al-6061-t6"} },
{ "joint": {"class": "R", "axis": [0,1,0], "limits": ["-160 deg", "-30 deg"]}, "actuator": "qdd-m",
"transmission": {"belt": {"ratio": "1.55"}},
"body": {"region": {"capsule": ["0.02 m", "0.21 m"]}, "fill": {"shell": "1.5 mm"},
"material": "cfrp-ud"} },
{ "foot": {"region": {"sphere": "0.022 m"}, "fill": "solid", "material": "rubber-60a",
"contact": {"law": "foot-patch", "interface": "rubber-60a/default",
"torsion_radius": "8 mm"}} } ] } } },
"power_bus": { "id": "main", "battery": "li-6s-5ah", "nominal": "22.2 V", "current_max": "60 A",
"regen": "to-battery", "sink": {"conductance": "1.2 W/K"} },
"sensors": [ {"id": "imu", "card": "imu-generic", "parent": "torso", "rate": "500 Hz", "clock": "mcu"},
{"id": "enc", "card": "encoder-14b", "parent": "joints:*", "rate": "1000 Hz", "clock": "mcu"},
{"id": "fc", "card": "foot-contact", "parent": "feet:*", "rate": "500 Hz", "clock": "mcu"},
{"id": "lidar", "card": "lidar-2d-generic", "parent": "torso",
"mount": {"xyz": ["0.20 m", "0 m", "0.06 m"]}, "rate": "10 Hz", "clock": "lidar"} ],
"budgets": { "mass_max": "14 kg", "cost_max": "4000 USD", "power_peak_max": "900 W",
"envelope_max": ["0.70 m", "0.40 m", "0.50 m"] },
"levers": [ {"id": "thigh", "path": "/limbs/of/of/chain/1/body/region/capsule/1",
"bounds": ["0.15 m", "0.30 m"], "manifold": "R+"},
{"id": "knee_ratio", "path": "/limbs/of/of/chain/2/transmission/belt/ratio",
"bounds": ["1.0", "2.5"], "manifold": "R+"},
{"id": "knee_card", "path": "/limbs/of/of/chain/2/actuator",
"choices": ["qdd-m", "qdd-l"], "manifold": "finite"} ],
"symmetry": {"assert_mech": "C2xC2", "assert_obs": "C2"} }
All numbers in the example are illustrative. The same design in the S-expression view, abridged:
(design "quad-a" :schema "frob.design/1"
(root (body torso :region (box 0.42m 0.20m 0.10m) :fill (shell 2.5mm) :material al-6061-t6
:ports ((hip_mount :xyz (0.19m 0.08m 0m)))))
(limbs (mirror xz (mirror yz
(attach torso.hip_mount
(chain
(link :joint (R :axis (1 0 0) :limits (-45deg 45deg)) :actuator qdd-m
:body (:region (capsule 0.03m 0.06m) :fill solid :material al-6061-t6))
; two more links
(foot :region (sphere 0.022m) :fill solid :material rubber-60a
:contact (foot-patch :interface rubber-60a/default :torsion-radius 8mm)))))))
(power-bus main :battery li-6s-5ah :nominal 22.2V :current-max 60A :regen to-battery
:sink (:conductance 1.2W/K))
(budgets :mass-max 14kg :cost-max 4000USD :power-peak-max 900W :envelope-max (0.70m 0.40m 0.50m))
(levers (thigh :path "/limbs/of/of/chain/1/body/region/capsule/1" :bounds (0.15m 0.30m) :manifold R+))
(symmetry :assert-mech C2xC2 :assert-obs C2))
Field reference. Every field the compiler reads is listed. A field not listed is refused (FROB-REF-103).
| Block | Field | Required | Meaning and rule |
|---|---|---|---|
| Top | schema |
Yes | frob.design/1. An unknown major version refuses (FROB-REF-125) and names the migration. |
| Top | name, meta |
name |
Display name; author, licence and source. No mechanical compile product reads them. |
| Body | body |
Yes | An identifier unique in its scope. Constructors derive instance identifiers such as leg.fl.thigh. |
| Body | region |
Yes | A primitive (box, cylinder, capsule, sphere, ellipsoid), a union or difference of primitives, or a mesh by content hash. The Region is the mass support: all of the body's mass lies inside it. |
| Body | fill |
Yes | solid, {shell: thickness}, {lattice: fraction}, declared or massless (§14.5). No default (FROB-REF-105). |
| Body | material |
Unless declared or massless |
A material card with a density and its provenance, from fs-matdb through the airlock or from a local .fcard. |
| Body | mass_properties |
With declared |
Mass, centre of mass and inertia with provenance. Checked against C-03 and the mass-support bound, and compared with the geometry-derived values whenever both exist. |
| Body | collision, visual |
No | Collision proxy and visual mesh, kept apart from the mass Region. The collision proxy defaults to the Region, and the canonical form writes that out. |
| Body | ports |
No | Named mount frames relative to the body, each a mechanical port. |
| Joint | class |
Yes | fixed, R, P, H, C, E (planar), S or free. A universal joint and any other non-subgroup joint are written as a product of these (C-01). |
| Joint | screws, or axis with pitch |
Yes | The screw basis: for each screw a unit axis, a point on it and a pitch. axis is shorthand for one screw through the joint origin. The stated class is checked against the basis by T-11. |
| Joint | origin |
No | parent_from_joint at the reference configuration; identity if absent, written out in the canonical form. |
| Joint | limits |
Yes | An interval per coordinate, a swing-and-twist cone for S, or the word unbounded. An empty or inverted interval refuses (FROB-REF-107). |
| Joint | home, damping, friction, backlash |
No | Reference configuration, and joint-side overrides of the actuator card's values (§15.6). |
| Actuation | actuator |
No (a joint without one is passive) | A card identifier, or a card with overrides. An override is recorded with provenance designed and changes the instance's card hash (§15.3). |
| Actuation | transmission |
No | gear, belt, screw, linkage, cable, or coupling over several joints with a matrix (§15.9): signed ratio, efficiency pair or loss law, backlash, compliance. |
| End effector | foot, wheel, track |
— | Bodies that touch the world. They take every body field and a contact law. |
| End effector | contact |
Yes on end effectors | The law and its interface card: foot-patch with a torsion radius, wheel-rolling, roller-wheel with a roller angle, belt, skid or pad. The laws themselves are §18's. A missing or incompatible law refuses (FROB-REF-121). |
| Constructors | attach, chain, serial, mirror, radial, scale, replace, closure |
— | §14.3. Kept unexpanded in the canonical form; the expanded tree is a compile product. |
| Import | use with module, at, bind, rename |
— | A module by content hash, the port it mounts on, parameter bindings and identifier renames (§14.6). |
| Power | power_bus: id, battery, nominal, current_max, regen, harness_resistance, brownout, sink, members |
If any actuator exists | The shared electrical bus and the shared thermal sink (§15.10). members defaults to every actuator and is written out. |
| Sensing | sensors[]: id, card, parent, mount, rate, clock, fov, latency |
No | §20. Rates are rationals in hertz. A sensor without a parent frame, a rate or a clock refuses (FROB-REF-126). Sensors enter Γ_obs. |
| Payload | payloads[]: body fields, mount, removable |
No | Bodies a task may add or remove. A payload enters the mass roll-up and both symmetry groups. |
| Budgets | budgets: mass_max, cost_max with its currency, power_peak_max, energy_min, envelope_max, payload_min |
No | Limits checked at stage 6 of the preflight (FROB-REF-115). Cost is summed from card prices, each with its provenance. |
| Levers | levers[]: id, path, bounds or choices, step, manifold, prior, locked |
No | The parameters an optimizer may move (ADR-SKEL-07). manifold is one of ℝ, ℝ₊, S¹, S², SE(3), the inertia cone, or finite. A value outside its bounds refuses (FROB-REF-111). |
| Locks | locks |
No | Paths or block names that no edit may change without an explicit unlock (FROB-REF-111). |
| Symmetry | symmetry: assert_mech, assert_obs |
No | Group names or generator lists. An assertion; a mismatch refuses with the breaker (FROB-REF-109). |
Canonical form. Seven rules make the bytes unique.
- UTF-8; object keys sorted by code point; no insignificant white space; a duplicate key refuses.
- A quantity is a string of an exact decimal and a unit token (
"0.42 m"), or an object with that string and its provenance, uncertainty and source. A bare quantity string means provenancedesigned. Unit tokens and their parsing arefs-qty's (FACT:frankensim/crates/fs-qty/src/parse.rs), or those offrob-unitsif INT-TOOLCHAIN-01 forces the escape hatch. - The canonical unit is the coherent SI unit, and the canonical decimal is the shortest that equals the exact
rational value. A value with no terminating decimal is written as a ratio (
"1/3 m"). - An angle given in degrees or turns is kept as an exact rational of a turn (
"1/8 turn"); an angle given in radians keeps its decimal. Both are exact records of what the author wrote, which is what the exact symmetry route of §13.4 needs. - Integers above 2⁵³, content hashes and rationals travel as strings, so a client that parses numbers as binary64 cannot merge two of them.
- Every field the compiler will read is present. Schema defaults for non-physics fields are written out with
provenance
default, so a later schema version cannot change the meaning of an existing design. - Constructor terms stay unexpanded.
The S-expression view maps objects to keyword forms, arrays to lists and quantities to atoms such as 0.42m.
frob design view --as sexpr and --as json convert in either direction, and INV-SKEL-04 requires the round
trip to be the identity on canonical forms.
14.5 Mass from geometry: the fill rule
What it is. S. By default inertia is not a parameter: it is computed from a Region, a fill and a material density (C-03), so an agent designs shapes and materials. The fill says how the Region is occupied.
| Fill | Mass and inertia | Use |
|---|---|---|
solid |
Density times the Region's volume moments | Wheels, feet, small brackets, counterweights |
{shell: t} |
Density times the moments of the Region minus those of its inward offset by t | Torsos, housings, tubes, limb segments |
{lattice: φ} |
A fraction φ of the solid moments | Printed infill; a first-order model that states its own isotropy assumption |
declared |
Given mass properties with provenance; the Region is used for collision and as the mass support | Imported robots; parts with measured mass |
massless |
None | Frames and markers only. A massless body that carries an actuated joint must have a child with mass, or stage 2 refuses |
The rule. There is no default fill (ADR-SKEL-03). A solid-filled body that alone exceeds one quarter of the
design's mass_max carries an advisory in the check report (DESIGN: a heuristic threshold, advisory only,
because solid is sometimes what is meant).
Worked card (illustrative): the mass error the rule prevents. The torso of §14.4 is a box of 0.42 × 0.20 × 0.10 m in an aluminium alloy at 2,700 kg/m³.
- Read as a solid block it weighs 0.0084 m³ × 2,700 kg/m³ = 22.7 kg.
- Read as a 2.5 mm shell it weighs 1.92 kg: the inner box of 0.415 × 0.195 × 0.095 m removes 0.007688 m³.
- The solid reading is 11.8 times too heavy for a sheet-metal torso. Through the mass spiral of GB-03, with loop gain 0.59, each kilogram of structure costs 2.4 kg of robot, so a 20.8 kg error in one body becomes about 50 kg of robot that does not exist, and every actuator is then sized for it.
- Rescaling the density to hit the right mass does not repair the inertia. About the vertical axis the solid's radius of gyration squared is (0.42² + 0.20²)/12 = 0.0180 m², and the shell's is 0.0236 m², which is 31% larger, because a shell keeps its mass at the walls.
Shell moments. FrankenSim's material-derived inertia provides volume moments for a sphere, an ellipsoid, a
cuboid, a solid and a hollow cylinder and a tetrahedron, with a rigid transform (FACT:
frankensim/crates/fs-mbd-material/src/geometry.rs). It has no hollow cuboid, capsule or mesh shell. frob-model
therefore computes a shell as the difference of two solids, which is exact for a box, cylinder, sphere and
capsule with a uniform wall, and uses the inward offset of the distance field for a mesh. A shell thicker than
half the Region's smallest dimension refuses as a solid written as a shell (FROB-REF-105).
Mass support. S. When mass properties are declared, positivity of the pseudo-inertia is necessary and
not sufficient: it admits inertias that no body inside the declared Region could have. If all mass lies in a
sphere of centre o and radius R, then ‖c − o‖² + tr(I_C)/(2m) ≤ R², where c is the centre of mass and I_C the
inertia about it, because the left side is the mass-weighted mean squared distance from o. More generally, for
a bounding ellipsoid written as {x : [x; 1]ᵀQ[x; 1] ≥ 0}, a consistent pseudo-inertia P satisfies tr(P·Q) ≥ 0.
Both are linear tests on P and are run exactly at stage 2 (FROB-REF-106). The bound applies to the declared mass
support only, never to an unrelated collision proxy. A known answer is in §13.10.
14.6 Reusable modules: .fmodule
What it is. S for the format and the port contract; F for reuse of certificates and analyses under
substitution. A module is a design subterm with open ports, parameters and a contract, stored as canonical JSON
with schema frob.module/1 (and the same S-expression view), and referenced by content hash:
"std/leg-3r-qdd.fmodule@b3:9a4e…". Owner: frob-design. Verbs: module.list, module.show, module.check,
module.substitute.
{ "schema": "frob.module/1", "name": "leg-3r-qdd",
"ports": [ {"id": "mount", "kind": "mech", "frame": "hip_mount", "power": "into-module"},
{"id": "bus", "kind": "elec", "nominal": "22.2 V", "power": "into-module"},
{"id": "sink", "kind": "thermal", "power": "into-module"},
{"id": "state", "kind": "signal", "msg": "joint-state/3", "rate": "1000 Hz",
"latency_max": "1 ms"},
{"id": "sole", "kind": "contact", "law": "foot-patch"} ],
"params": [ {"id": "thigh", "unit": "m", "default": "0.21 m", "bounds": ["0.15 m", "0.30 m"]},
{"id": "knee_card", "kind": "card:actuator", "default": "qdd-m"} ],
"body": { "chain": [ "…the three links and the foot of §14.4…" ] },
"contract": {
"guarantees": { "mass": ["1.6 kg", "2.4 kg"], "port_inertia": "sym-psd-6",
"bus_demand": {"peak": "38 A", "profile": "per-task, time-resolved"},
"heat_to_sink": {"continuous_max": "60 W"} },
"assumes": { "bus_voltage": ["18 V", "25.2 V"], "sink_conductance_min": "0.4 W/K" },
"digest": "b3:…" } }
Port contract. Five kinds of port, with one sign convention: power is positive into the module.
| Kind | Effort and flow | Junction rule when two ports are joined |
|---|---|---|
mech |
Wrench and twist at a named frame | Twists are identified in a common frame and wrenches balance |
shaft |
Torque and angular velocity | Speeds are identified and torques balance |
elec |
Voltage and current | Voltages are identified and currents balance at the node |
thermal |
Temperature and heat rate | Temperatures are identified and heat rates balance |
signal |
A typed message with a rate and a latency bound | One producer, any number of typed consumers; carries no power |
A contact entry names an end effector that meets the world. It is listed because it is why a module's effect
on the robot cannot be summarized at its mount port alone. Joining ports checks kinds, frames and signs, sums
the power over the joined ports to zero, and resolves causality; an algebraic loop, a reversed sign or a copied
power port refuses (FROB-REF-108). On the referee the interconnection is FrankenSim's (FACT:
fs_phs::interconnection::interconnect_mapped exists at frankensim/crates/fs-phs/src/interconnection.rs).
Substitution contract. The contract holds what the rest of the robot may rely on without opening the module (guarantees) and what the module relies on from the rest (assumptions). Its digest covers the port signature, the parameter schema, the hash of the body term, the versions of the cards it names and its local certificates: inertia consistency of every body over the parameter box, which is structural for geometry-derived inertia, and passivity of every element (§15.5).
module.substitute replaces the module at a path by another. The substitution is leaf-local, and sibling
products are reused, exactly when all four of the following hold:
- the replacement has the same port signature: kinds, frames up to the declared mount, and sign convention;
- the replaced module is a leaf of the tree: no
closurelinks it to another branch; - it reaches shared resources only through its declared
elecandthermalports, and its assumptions are met by the bus and sink as they stand; - the consumer of each reused product read only fields outside the replaced subterm, by the influence records of §14.9.
| Product | After a leaf-local substitution | Reason |
|---|---|---|
| Sibling modules' expanded subtrees, frames and collision primitives | Reused | Their content hashes are unchanged |
| Sibling limbs' symbolic kinematics and closed-form inverse-kinematics kernels | Reused | They depend on the limb alone |
| Sibling limbs' local analyses: workspace, singular loci, self-collision inside the limb | Reused | Same |
| Derived kernels keyed by joint class and tree shape | Reused if the size bucket is unchanged (§17) | Kernels are keyed by shape, not by parameter values |
| Mass roll-up and composite inertia along the path to the root | Recomputed | Cheap, and always changed |
| Γ_mech and Γ_obs | Recomputed | A swapped limb can break or restore a symmetry |
| Budgets and co-design closure (A-10) | Recomputed | Whole-robot sums and a fixed point |
| Self-collision pairs between the new limb and the others | Recomputed | New geometry |
| Bus and sink analyses | Recomputed whenever the new guarantees differ from the old | Shared resources couple all limbs |
| Static stability, the baseline controller, any rollout, any verdict | Invalidated | Ground contact couples every limb through the base |
| Whole-robot certificates | Invalidated | Their statements quantify over the whole model |
A substitution that fails any of the four conditions is global: an edit to the bus or its battery, to the
shared sink, to a limb that takes part in a closure, or a change of port signature. A global substitution
invalidates everything downstream of ModelId.
Counterexample: a contract that carries only peaks can admit and cannot exclude. Two fingers share a bus
limited to one unit of current. Each finger's local summary says "peak demand one unit". A rule that adds peaks
concludes two units and prunes the design. But one finger draws at the first tick and the other at the second,
so the schedule is feasible. Adding peaks is a sound sufficient test and an unsound exclusion. A contract whose
bus_demand has no time-resolved profile is therefore usable for admission only, and the bus analysis of §15.10
is run in full before any design is excluded on electrical grounds.
The limb port interface. F. A tree limb attached at a mechanical port, with its joint torques known and its end effectors free, acts on its parent through two quantities: its articulated inertia at the port, a symmetric 6×6 matrix with 21 independent entries, and a bias wrench of 6 entries. The packet is 27 scalars (108 bytes in single precision). It is computed by the backward pass of the articulated-body recursion over the limb. Type sketch (DESIGN):
/// What a free tree limb presents to its parent at a mechanical port, at one instant.
pub struct LimbPortPacket { inertia: SymPsd6, bias: WrenchIn<PortFrame> }
The semidefinite caveat. Eliminating a joint with axis s from an articulated inertia I gives I − I·s·(sᵀI·s)⁻¹·sᵀI, and this matrix sends s to zero. With I the identity and s the first basis vector the result is diag(0, 1, 1, 1, 1, 1). The packet is positive semidefinite, never guaranteed definite, and the type says so. Three consequences bind every consumer:
- the packet cannot be inverted at the port. The parent adds its own inertia before any solve, and a chain of massless parents is singular, which is why stage 2 refuses it;
- the packet does not describe a limb whose end effector is in contact. Contact rows couple every limb through the base, and the coupled solve of §16 is the only correct path for them;
- the packet is a value for one configuration in one world at one instant. What a substitution reuses is the packet's layout and the sibling limbs' kernels, not numbers.
The interface serves the tree-operator route for mechanisms too large for a dense mass matrix (§16) and the per-limb caches of the analyses. It is not a way to decouple contact.
14.7 Typed edits
Edits are the morphisms of the design category. Each has preconditions, an inverse where one exists, a declared effect on both symmetry groups, and a scope of invalidation that §14.9 computes and this table predicts.
| Edit | Example | Symmetry effect | Invalidation scope |
|---|---|---|---|
set-param |
Thigh length 0.21 → 0.24 m | Preserved when applied under a constructor | The subterm and its dependents |
regear |
Knee belt ratio 1.55 → 1.8 | Preserved | Actuator binding; envelope analyses |
swap-actuator |
qdd-m → qdd-l at all knees |
Preserved; broken if applied to one leg | Binding, mass roll-up, bus analysis |
add-limb / remove-limb |
Add a tail with one joint | Reported: new group computed | Global |
move-mount |
Hip mount 2 cm forward | Reported | Kinematics from the mount down; whole-robot sums |
reshape |
Shank capsule → tapered capsule | Preserved under a constructor | The body's geometry and inertia |
mirror / radial |
Wrap a limb in a constructor | Group grows | Global |
closure-add / closure-remove |
Add a parallel knee linkage | Reported | Global: mobility changes |
set-fill |
Thigh solid → 2 mm shell | Preserved under a constructor | The body's inertia; whole-robot sums |
set-material |
Shank aluminium → carbon laminate | Preserved under a constructor | Same |
set-limits |
Knee range narrowed by 10° | Preserved under a constructor; a one-sided change is reported | Workspace, self-collision, the limit rows |
set-contact-law |
Foot foot-patch → pad |
Γ_mech reported if applied to one foot | Contact binding; every rollout |
swap-module |
Leg module by hash | Reported | Leaf-local or global by §14.6 |
add-sensor / move-sensor / remove-sensor |
Move the lidar 4 cm up | Γ_mech preserved; Γ_obs recomputed and reported | Sensor binding; observation layouts; coverage analyses |
retime |
Encoder rate 1 kHz → 2 kHz | Preserved | Clock plan (§20) |
add-payload / move-payload |
A 2 kg payload on the left side | Both groups recomputed | Whole-robot sums; symmetry |
set-bus / swap-battery |
6S → 8S pack | Preserved | Global on the electrical side: every envelope and thermal analysis |
set-budget |
Mass limit 14 → 12 kg | None | Stage 6 only |
declare-lever / set-lever / lock / unlock |
Free the hip mount within ±3 cm | None | None for a declaration; as set-param for a move |
assert-symmetry |
State assert_obs: C2 |
None; the assertion is checked | Stage 5 only |
rename |
Rename a body | None | None: no mechanical product reads names |
migrate |
Schema /1 → /2 |
None, by construction | None if the migration is certified meaning-preserving; otherwise global |
A design's history is a path of edits in a content-addressed lineage graph (§28).
14.8 Design patches and versioning
What it is. S. A patch is a document that applies typed edits to a named parent. Owner: frob-design.
Verb: design.patch (design.edit remains the single-edit form).
{ "schema": "frob.design.patch/1",
"parent": "design:b3:9f2c…",
"idempotency_key": "agent-7/turn-41/a",
"operations": [
{"op": "set-param", "path": "/limbs/of/of/chain/1/body/region/capsule/1", "value": "0.24 m"},
{"op": "set-fill", "path": "/limbs/of/of/chain/1/body", "value": {"shell": "1.5 mm"}} ],
"constraints": { "locked": ["power_bus", "payloads", "budgets/envelope_max"],
"require": ["A-11", "A-13"] } }
- Result. A new immutable design version with its
DesignId; a structural and parameter diff; the effect on Γ_mech and Γ_obs; and the invalidation set: the derived products, analyses, kernels and verdicts that no longer apply, each with the field that invalidated it. Nothing is modified in place. - Stale parent. If the named parent is not the head the caller believes it is patching, the patch refuses (FROB-REF-112) and returns the current head and the diff between the two.
- Locks and requirements. An operation that writes a locked path refuses (FROB-REF-111). The analyses named
in
requirerun before the version is created, and a refusal from any of them refuses the patch as a whole. - Idempotency. The same key with the same parent and operations returns the version already created. The same key with different content refuses. The binding is atomic, as §32 specifies.
- Inertia follows geometry. A patch never edits a derived inertia. It edits the Region, the fill or the
material, and the inertia is recomputed. A
declaredbody is the exception and is edited as data. - One settled pose per version. Each design version has its own settled initial state for each contact
surface class, computed by Kinesis (§16) and cached under its
ModelId. A comparison (§28) refuses a pair whose initial states were settled for only one of the two designs: a robot that starts with its wheels inside the floor invalidates the pair. A buildable design that then stalls is a failed trial, not an invalid one. - Which verdicts survive. A verdict names the fields its evidence read. After a patch, a verdict whose fields are untouched is reported as still applying, with that justification, and every other verdict is listed for revalidation. Rollouts are not reused across a mass or geometry edit: the share of a rollout that could be reused exactly was assessed as about a tenth of its compute or less (HYPOTHESIS until our own dependency profile is measured), so the memo graph stops at analyses, step plans, kernels and scene compiles.
- Schema versions and migration. A schema has a major and a minor number and a canonicalization revision. A
minor version adds optional fields. A major version needs a migration, which reads the old object, writes a
new one with a
migratelineage edge and its provenance, and leaves the old object in place so that old runs replay against the compiler version that produced them..fbotand.fmodulefiles travel in the common artifact envelope of §34, which carries the schema, the canonicalization revision, the payload and parent digests, the generator pin, the validity region and the licence.
14.9 The compile pipeline and its memoization
Design → elaborate (expand constructors, import modules, resolve parameters) → validate (ports, units,
bounds, fills) → five functors (C-12): kinematic tree with loop closures; collision primitives and inertia
from Regions, fills and materials; actuator and sensor binding, including the joint rows of §15.6; budget
relations; symmetry generators → RobotModel, immutable, with a ModelId. The model then lowers four ways:
- to an
fs_mbd::articulated::ArticulatedModelfor the referee tier, through the airlock; - to packed structure-of-arrays buffers for the batched tiers, with depth levels and a path table for sparse Jacobians;
- to analysis views for Atelier (symbolic kinematics for one limb, the leg-permutation group, the budget graph);
- to a variant record inside a size bucket, so that many different robots can share one batch (§17).
Compilation is memoized per subterm by content hash, so an edit recompiles only what it touched (INV-SKEL-02).
| Stage | Product | Memo key |
|---|---|---|
| Parse and canonicalize, from either view | Typed term | Hash of the input bytes |
| Elaborate | Expanded tree with resolved parameters | Subterm hash with the digests of the modules and cards it names |
| Validate | The same tree, or a refusal | Subterm hash |
| Kinematic functor | Frames, screws, tree, closures | Hash of the subtree's mechanical fields |
| Geometric and inertial functor | Collision primitives; volume moments by fill; pseudo-inertia | Body hash with the material card's version |
| Binding functor | Actuator and sensor channels; row descriptors | Joint hash with the card versions |
| Budget functor | Budget relations and per-subtree summaries | Subtree summary hashes |
| Symmetry functor | Γ_mech, Γ_obs, representations, breakers | Canonical tree form with the digest of sensors, payloads and task terms |
| Assemble and lower | RobotModel, ModelId, the four lowerings |
ModelId with the compiler version |
Influence records (ADR-SKEL-09). Each product stores the set of source paths it read, at field granularity.
The invalidation set of an edit is the set of products whose read set meets the edit's write set. Moving a
camera changes extrinsics, coverage and Γ_obs; renaming a body rebuilds nothing. Two designs with different
DesignId can therefore share a ModelId, and INV-SKEL-01 still holds: the model is determined by the design,
the compiler version and the card versions.
What the memo graph covers. Compile products, static analyses, step plans, derived kernels and scene compiles. It does not cover rollouts (§14.8). The ceiling of the benefit is the share of an agent's edit-to-first-step time that is spent recompiling unchanged subterms, which is small once a rollout takes seconds; the memo graph is kept for correctness of invalidation first and for latency second.
14.10 Archetypes: the eighteen
Archetypes are designs with parameters, shipped in assets/archetypes/ and listed by design.templates. Each
exists to exercise named mechanisms, and each has a known answer that fails if the mechanism is wrong.
Reference robots are imported public models used as parity fixtures and benchmark baselines (licences in
Appendix G). The symmetry column gives Γ_mech as built, before any sensor is mounted. The first archetypes, which
land at M1, are quad-mammal, humanoid, diff-drive and mecanum; the other fourteen land at M3 with their
baseline controllers, and the tracked and hybrid ones at M4 with their contact laws (GATE-REFLEX-01).
| # | Archetype | Layout | Actuated coordinates | Γ_mech as built | What it tests | Reference robots |
|---|---|---|---|---|---|---|
| 1 | quad-mammal |
Dog-like quadruped, three joints per leg | 12 | C₂ × C₂ | Floating-base dynamics (C-04); the gait atlas with trot, pace and bound (C-10); 27 contact strata (§13.6); Γ_obs = C₂ with a forward sensor; knee thermal limits on a stair task | Unitree Go1, Go2, A1; ANYmal B, C; Spot (BSD-3 models) |
| 2 | quad-sprawl |
Sprawled quadruped with wide stance | 12 | C₂ × C₂ | Large static margins against high holding torque: the design is stable and still fails A-11 thermally; stiction at near-stall joints | None on file |
| 3 | hexapod-radial |
Radial hexapod, three joints per leg | 18 | D₆ (C₆ with handed legs) | Character tables and orbit counts for D₆ (86,185); complex-type blocks when the legs are handed; tripod gait as an (H, K) pair; static walking with three feet down | None with a permissive model on file (OPEN-ARENA-2) |
| 4 | octopod |
Eight-legged, three joints per leg | 24 | D₈ radial; C₂ in a spider layout | Contact capacity and size buckets with eight feet (§17); redundancy when a leg fails | None on file |
| 5 | biped-point |
Point-foot biped | 6 | C₂ | Underactuation; no static stability, so A-08 must report and not refuse; impact events; the hardest case for the baseline controller | Cassie (MIT model) |
| 6 | humanoid |
Humanoid with arms and waist | 29 | C₂ | The upper end of the dense mass matrix; coupled ankle and waist transmissions (§15.9); self-collision over large ranges; import parity | Unitree G1 (already in fs-mbd::robot_models), H1 |
| 7 | diff-drive |
Two driven wheels and a caster | 2 | C₂ | Growth vector (2, 3) and the sideways cost of GB-05; the closed-form SE(2) exponential; the raised-threshold oracle: at a lip of height h a wheel of radius r has lever arm √(2rh − h²) | Stretch 3 base (Apache-2.0 model) |
| 8 | ackermann |
Car-like, steered front axle through a linkage | 3 | C₂ | Closure and mobility of the steering linkage (A-01); growth vector (2, 3, 4); turning radius L/tan δ for wheelbase L | None on file |
| 9 | mecanum |
Four mecanum wheels | 4 | C₂ × C₂ | The roller contact law; reflection parity on roller axes (§13.3); growth vector (3); the negative control with all rollers parallel | TIAGo omni base (Apache-2.0 model) |
| 10 | omni-3 |
Three omni wheels at 120° | 3 | D₃ | Holonomic base with an odd rotation order; the 3 × 3 wheel-to-body velocity map and its inverse | None on file |
| 11 | swerve-4 |
Four steer-and-drive modules | 8 | D₄ on a square base | Nested symmetry of module and hub (§13.6); scrub torque from the spin component of the contact cone (§18); the singular pose with all wheel axes through one point | None on file |
| 12 | tracked-flipper |
Two tracks with front and rear flippers | 6 | C₂ × C₂ | The belt law; skid steering, where turning in place must cost scrub work; stair nosing with flippers; thermal duty on a long climb | None on file |
| 13 | wheel-leg |
Quadruped with driven wheels as feet | 16 | C₂ × C₂ | Two contact laws on one end effector class; switching between rolling and stepping; wheels and legs in one mobility analysis | None on file |
| 14 | tri-wheel-stair |
Two tri-wheel clusters on a chassis | 4 | C₂; C₃ or D₃ in each cluster | Cluster geometry against riser and tread (fs-mbd::tri_wheel_cluster has the geometry, FACT); a three-fold group inside a mirror group |
None on file |
| 15 | rocker-bogie |
Six wheels on a passive rocker-bogie suspension | 6 | C₂ | Passive joints and a differential closure in A-01; obstacle climbing without actuated suspension; static stability on slopes | None on file |
| 16 | mobile-manipulator |
Seven-joint arm on a wheeled base | 9 | Trivial with the arm off-centre | Workspace and singular loci (A-05, A-06); tray and shelf heights; a payload that breaks symmetry; import parity | KUKA iiwa 7 (already in fs-mbd::robot_models); Stretch 3, TIAGo |
| 17 | snake-crawler |
Planar serial chain with passive wheels | 8 | C₂ under head-to-tail reversal | Locomotion as holonomy (C-08, A-09); the curvature sign of §13.8; serial(k, link) at scale |
None on file |
| 18 | balancer-2w |
Two-wheeled inverted pendulum | 2 | C₂ | An unstable equilibrium: the estimator and the baseline controller must work on the first step; the open-loop pole against its closed form; sensitivity to latency, stiction and backlash (§15.6) | None on file |
The known answer for a differential drive uses the closed form Δp = v·Δt·sinc(δ/2)·(cos(θ + δ/2), sin(θ + δ/2))
with δ = ω·Δt, not fs-mbd::planar_drive, which has a reported defect near straight-line motion (FACT to
recheck; §33 carries the admission test and the upstream work item).
Variants outside the eighteen exist behind feature flags and are off the critical path. Each belongs to the chapter that owns its physics.
| Variant | Adds | Tier | Owner of the physics |
|---|---|---|---|
| Open modular class | Any composition of modules; random designs from this class drive the property tests of GATE-SKEL-02 | S | This chapter |
| Parallel delta arm; parallel ankles | Closures produced by the bounded exact synthesis lane | F | §25 |
| Dual-arm base | Two arms closing a loop through a grasped payload | F | §16 |
| Dexterous hands | Compliant tactile pads on fingers | M | §18 |
| Aerial-terrestrial hybrid | Rotor ports on a legged or wheeled chassis (§15.4) | M | §16 |
| Continuum arm | A rod as a generalized joint | M | §16 |
14.11 Preflight: eight stages that are design check
What it is. frob design check <design> [--task T --scene S] [--stages a-b] [--strict-data] runs the stages
below in order and stops at the first refusal, unless --all asks for every finding. Stage 1 is the compile of
§14.9. Stages 2 to 8 call Atelier's analyses and live in frob-analyze. Every stage returns an evidence class
and the model identity, and every refusal carries ranked repairs as typed edits, which become the envelope's
next_actions.
| Stage | What runs | Analyses | What it refuses | Time target, 95th percentile (TARGET) | Tier |
|---|---|---|---|---|---|
| 1 Form | Parse either view; canonicalize; expand constructors and modules; unit and dimension algebra; fills; levers and locks | — (feeds A-02) | Unknown or misspelt field (103); unit or dimension error (102); port mismatch (101); missing fill or a solid written as a shell (105); lever out of bounds or a locked field (111); module digest or signature mismatch (114); missing contact law (121); sensor without frame, rate or clock (126); a card that fails its own checks (130, 134) | 100 ms | S |
| 2 Mass | Mass roll-up by subtree; pseudo-inertia positivity by exact LDLᵀ; mass support for declared bodies; massless chains | A-02 | Inconsistent inertia, with the offending pivot and the nearest consistent matrix (104); mass-support violation (106) | 50 ms | S |
| 3 Mechanism | Hervé class of each screw basis; loop assembly; mobility; singularity at the reference pose; self-collision and ground clearance over the declared ranges | A-01, A-06 (reference pose), A-13 | Class and basis disagree (101); empty range (107); over-constrained closure (110); self-collision or interpenetration (123) | 400 ms | S; F for lattice mobility |
| 4 Motion | Growth vector of the rolling distribution for wheeled and tracked bases; connection curvature for kinematic shape-changers | A-07, A-09 | The base cannot produce a motion the task class requires (118), with the missing direction and the roller, steering or joint edit that restores it | 200 ms | S growth vector; F curvature |
| 5 Structure | Γ_mech and Γ_obs with breakers; the symmetry assertion; port power balance, sign conventions and algebraic loops | A-03 | Declared symmetry differs from computed (109); power sign, copied power port or algebraic loop (108) | 150 ms | S |
| 6 Statics and sizing | Support and tip-over margins; co-design closure; torque, speed and voltage envelope at the standing, crouching, stepping-up and nominal-gait points; thermal steady state with temperature-dependent resistance; bus feasibility; budgets | A-08, A-10, A-11 | A required static margin not met (124); the mass spiral does not close (116); an operating point outside the envelope (131); no thermal equilibrium or one above the limit (132); bus cannot supply the demand (133); budget exceeded (115); a card field assumed under --strict-data (113) |
600 ms | S |
| 7 Place | Reach against the task's heights; sensor coverage of footholds and route; clearance of the swept body through the scene's clearance complex | A-05, A-07 (door and aisle passability), A-14 | No admissible route (119), with the bottleneck named and, if one exists in the catalog of §19, the retrofit that removes it; a required height out of reach (119) | 2 s per scene with a compiled clearance complex | F |
| 8 Information | Search for two admitted worlds with the same observation transcript and disjoint safe actions | A-14 and the alias search below | An observation alias (120), with the two worlds, the transcript and the cheapest separating sensor, rate or probe | 10 s by default; the budget is the caller's | F |
On the time targets. The figures are budgets per stage for any of the eighteen archetypes on the reference
host, with an empty memo graph. They are not predictions and are not added into a headline. The one total this
plan commits to is the existing bound: stages 1 to 6 complete within 2 s at the 95th percentile on the
archetypes (GATE-ATEL-02). That gate reports the measured median and 95th percentile of every stage, and a stage
that misses its budget is a finding even when the total passes. Stages 7 and 8 depend on the size of the scene
and of the world family and carry no total. A stage that exhausts its budget returns undecided with what it
had established. undecided is never a pass and never a refusal.
The analyses not in the preflight remain separate verbs, because they cost more or need a choice from the caller: A-04 gait atlas, A-12 modes, the full form of A-15 structural margin, A-16 sensitivity, and the full-range forms of A-05 and A-06. The beam rung of A-15 runs in stage 6 under the bounded load set, as a validity check on declared link walls (§31.23).
| Analysis | Stage | Analysis | Stage |
|---|---|---|---|
| A-01 Mobility | 3 | A-09 Connection curvature | 4, for kinematic shape-changers |
| A-02 Mass roll-up | 2 | A-10 Co-design closure | 6 |
| A-03 Symmetry | 5 | A-11 Actuator envelope | 6 |
| A-04 Gait atlas | Separate verb | A-12 Modes | Separate verb |
| A-05 Workspace | 7, for the task's heights | A-13 Self-collision and clearance | 3 |
| A-06 Singularities | 3, at the reference pose | A-14 Sensor coverage | 7 and 8 |
| A-07 Maneuverability | 4; passability in 7 | A-15 Structural margin | 6, beam rung under the bounded load set; full form a separate verb |
| A-08 Static stability | 6 | A-16 Sensitivity | Separate verb |
Stage 4 needs both tests. Counterexample: a mecanum base assembled with all four roller axes parallel. The map from body twist to wheel rates drops from rank 3 to rank 2: the wheels command translation along one direction and rotation, and the base slides freely along the other. Its controlled distribution has growth vector (2, 3) where an omnidirectional base must have (3), and stage 4 refuses it against the class the archetype declares. A curvature test applied to the same base passes, as it passes a differential drive, because the missing direction is still reached by a bracket. Curvature is the right test for a snake-like crawler and the wrong one for a wheel layout, so stage 4 runs the growth vector on wheeled and tracked bases and curvature on shape-changers.
Stage 8: the observation alias. F. Inputs: the task's admitted world family, finite or quantized as the
task declares; the sensor suite with its resolution, range, field of view, rate and noise floor, which together
define a quantized transcript; a prefix horizon; and the safe-action sets the task's requirements define. The
stage searches for worlds w₁ and w₂ in the family whose transcripts agree over the prefix and whose safe-action
sets at the decision instant are disjoint. If it finds them, no policy on this sensing interface succeeds in
both, and with the two worlds equally likely and noisy sensors no policy succeeds with probability above
(1 + TV)/2, where TV is the total-variation distance between the two transcript distributions. Two labels
keep the claim honest: aliased-passive when the transcripts agree for the nominal action sequence, which is
an advisory that names a probing action if one separates the worlds; and aliased-all-probes when they agree
for every action sequence in the task's finite probe family, which is the refusal. The repair is the cheapest
entry of the sensor catalog whose transcript differs on the pair, a higher rate, or a probe.
Known answer (hand-checkable). Two range beacons at (−1, 0) and (1, 0). A robot at (0, 1) and a robot at (0, −1) both read √2 from each, and the local information matrix is the identity at both points, so a local observability test passes. If the task requires moving toward the positive side, the two worlds need opposite actions: an alias. A third beacon at (0, 2) reads 1 in one world and 3 in the other and separates them whenever the range error is below 1.
14.12 Import and export (frob-io)
- URDF and MJCF import, through a small in-house XML reader (elements and attributes; no entities or DTDs), so no third-party parser enters the core (L-5). FrankenSim's own robot models are hand-transcribed from pinned URDF sources and do not parse at run time (FACT), so this reader is new work. The supported subset of each format is documented, and every element outside it is echoed in the loss report with its file and line.
- Macros are expanded outside.
frob-iodoes not run xacro or any other macro processor and executes no script found in a model. It accepts the expanded document and records its hash and the name of the tool the user says produced it. - Every import produces a loss report: fields dropped, defaults filled, contact parameters that have no exact
equivalent, inertias that fail C-03 with the proposed repair, actuator limits absent and filled from a card
marked
assumed. Imported bodies getfill: declaredwith the source's inertial values; the mass-support bound is applied to them only where the source states a mass Region, and is otherwise reported as not checked. Mimic joints becomecouplingtransmissions. - Export to URDF and MJCF for use elsewhere, with the same loss report in reverse: closed loops,
transmissions and couplings, sensor latency and clocks, contact laws, the power bus, fills (the export writes
explicit inertials), levers, budgets, symmetry assertions and controller assumptions have no full equivalent
and are listed. glTF export for visuals goes through FrankenSim's GLB exporter (FACT:
fs-geomexports GLB). - Round trips compare meaning, not bytes: forward kinematics, mass properties and the map of identifiers.
- SDF import is added through a feature matrix when a consumer needs it. OpenUSD import is Frontier. Only the core specification is settled and robotics schemas are still vendor extensions (FACT, Appendix H), so it waits for a real consumer.
14.13 Refusals instead of repairs in silence
An invalid design is refused with a stable code, a message, and ranked repairs expressed as typed edits. Codes 101 to 129 belong to this chapter; 130 to 139 are Sinew's (§15.13).
| Code | Refused | Code | Refused |
|---|---|---|---|
| FROB-REF-101 | Port type mismatch; joint class and screw basis disagree | FROB-REF-114 | Module digest or port signature mismatch on import or substitution |
| FROB-REF-102 | Unit or dimension error | FROB-REF-115 | A design budget exceeded: mass, cost, peak power, energy or envelope |
| FROB-REF-103 | Unknown, misspelt or duplicate field | FROB-REF-116 | Co-design does not close: loop gain at or above one |
| FROB-REF-104 | Inertia not physically consistent (the smallest eigenvalue of the pseudo-inertia is reported) | FROB-REF-118 | The base cannot produce a motion the task class requires |
| FROB-REF-105 | A body without a fill; a solid written as a shell | FROB-REF-119 | No admissible route or reach in the scene |
| FROB-REF-106 | Declared mass properties violate the mass-support bound | FROB-REF-120 | Observation alias under every admitted probe |
| FROB-REF-107 | Empty joint range | FROB-REF-121 | Contact law missing or incompatible with its end effector |
| FROB-REF-108 | Power sign mismatch, copied power port or algebraic loop | FROB-REF-122 | An unsupported element in an import under --strict |
| FROB-REF-109 | Declared symmetry differs from computed symmetry | FROB-REF-123 | Self-collision or interpenetration at the reference pose or over declared ranges |
| FROB-REF-110 | A closure that over-constrains the mechanism (mobility below one) | FROB-REF-124 | A static margin the task requires is not met |
| FROB-REF-111 | A lever outside its bounds; an edit to a locked field | FROB-REF-125 | Unsupported schema version |
| FROB-REF-112 | Stale parent in a patch | FROB-REF-126 | A sensor without a parent frame, a rate or a clock |
| FROB-REF-113 | An actuator card with a required field of class assumed when the caller asked for --strict-data |
Each component family has a first rejection fixture in the negative-control registry of §38. A check that lets its fixture through is broken, whatever else it reports.
| Family | First rejection fixture | Caught by |
|---|---|---|
| Rigid link | Principal moments that violate the triangle inequalities | Stage 2 (104) |
| Joint | A prismatic travel in millimetres read as radians | Stage 1 (102) |
| Transmission | Reverse drive that produces free electrical energy | Card check (130, §15.9) |
| Actuator | Stall torque available indefinitely at high speed | Stage 6 (131) |
| Drive wheel | A changed wheel that intersects the body at its nominal mount pose | Stage 3 (123) |
| Track | Turning in place at zero scrub work on a frictional floor | The belt-law known answer of §18.16 (under exact lateral no-slip the yaw rate is zero, so a turn in place costs scrub work) |
| Foot | A point foot that silently acquires torsional support | Stage 1 (121): a torsion radius above the foot's own contact radius |
| Sensor | Measurements with no timestamp or an unknown frame | Stage 1 (126) |
| Power source | An empty battery that keeps supplying commanded power | Run-time refusal (135, §15.10) |
| Passive part | Swapping a payload that leaves the assembly inertia unchanged | INV-SKEL-06 |
14.14 Invariants, proof obligations, known answers
| ID | Invariant |
|---|---|
| INV-SKEL-01 | A RobotModel is immutable and fully determined by its DesignId, the compiler version and the card versions it references. |
| INV-SKEL-02 | Incremental compilation equals full compilation, bit for bit. |
| INV-SKEL-03 | Every inertia in a compiled model passes C-03, and every parameter has a unit and a provenance. |
| INV-SKEL-04 | The JSON and S-expression views of a design have the same DesignId, and converting between them is the identity on canonical forms. |
| INV-SKEL-05 | Every body's mass comes from a Region, a fill and a material, or is declared with provenance; no fill is defaulted. |
| INV-SKEL-06 | The invalidation set of an edit contains every product that differs after a full recompile; a product outside the set is bit-identical. |
| INV-SKEL-07 | A declared symmetry never replaces a computed one, and no consumer reads the declaration. |
| INV-SKEL-08 | An optimizer changes only declared levers, inside their bounds and on their manifolds. |
| INV-SKEL-09 | A module substitution classed leaf-local satisfies the four conditions of §14.6; every reused product is bit-identical to its recompiled value. |
| ID | Statement | Verification |
|---|---|---|
| PO-SKEL-01 | Canonicalization is idempotent and both views parse to the same typed term. | Property test over 10⁴ random designs and the eighteen archetypes; hash equality. |
| PO-SKEL-02 | Shell moments equal the closed forms for box, cylinder, sphere and capsule shells. | Exact rational comparison; the worked card of §14.5 as a fixture. |
| PO-SKEL-03 | The influence record of each product is a superset of the fields it reads. | Mutation of every field outside a product's record leaves the product bit-identical; mutation inside is allowed to change it. |
| PO-SKEL-04 | A limb port packet is symmetric positive semidefinite and reproduces the limb's reaction on its parent. | Comparison with the full articulated recursion on random limbs; the diag(0, 1, 1, 1, 1, 1) case as a fixture. |
Known answers owned by this chapter (numbered in §38):
| Known answer | Expected | Guards against |
|---|---|---|
| Box 0.42 × 0.20 × 0.10 m at 2,700 kg/m³, solid and as a 2.5 mm shell | 22.68 kg and 1.923 kg; vertical-axis gyration radius squared 0.01803 m² and 0.02357 m² | A solid default; density rescaling in place of a shell |
| Raised threshold: wheel radius 0.060 m and 0.075 m at a 0.012 m lip | Lever arm 36.0 mm and 40.7 mm; horizontal push over axle load 0.750 and 0.646 | A wheel edit judged by one of its two effects |
| Ackermann base | Turning radius L/tan δ | A steering linkage with the wrong closure |
| Mecanum with parallel rollers | Twist-to-wheel map of rank 2; growth vector (2, 3) in place of (3); a curvature test passes | Curvature used as a wheel-layout test |
| Two fingers on a one-unit bus, drawing at different ticks | Feasible; the peak-adding rule excludes it | Exclusion from peak-only contracts |
| Mirror swap of a leg module; edit of the shared bus | Siblings reused; everything electrical invalidated | An invalidation rule that is too wide or too narrow |
| Two beacons, mirrored robot positions | Alias found; a third beacon at (0, 2) separates for range error below 1 | Local observability taken for global |
Forward lidar on quad-mammal with assert_obs: C2xC2 |
Refused (109) with the lidar mount as breaker | A trusted symmetry declaration |
14.15 Gates, kill gates, open questions
| Gate | Threshold (TARGET) |
|---|---|
| GATE-SKEL-01 | Each reference robot imports with forward-kinematics parity against the oracle within 10⁻⁹ m and 10⁻⁹ rad over 10⁴ configurations, and its loss report lists every dropped field found by a field-coverage diff. |
| GATE-SKEL-02 | Functor laws and INV-SKEL-02 hold on 10⁴ random designs and edits. |
| GATE-SKEL-03 | Each of the eighteen archetypes compiles, passes stages 1 to 6 of design check with no refusal, has the symmetry groups on file, and stands or rolls under its baseline controller at the milestone GATE-REFLEX-01 gives for it. |
| GATE-SKEL-04 | Of 100 seeded defects for stages 1 to 6, with at least two per refusal code, all 100 are refused and at least 95 by the stage and code that own them; zero refusals on the eighteen archetypes and on 10³ random valid designs. For stages 7 and 8, of 40 planted cases at least 36 are decided correctly within budget and none is decided wrongly. |
| GATE-SKEL-05 | INV-SKEL-04 and PO-SKEL-01 hold on 10⁴ random designs; a JavaScript client's round trip of every wide integer and hash matches the native decoder. |
| GATE-SKEL-06 | Substitution controls: the mirror swap reuses every sibling product bit-identically; the shared-bus edit invalidates every electrical and thermal product; a reversed port sign refuses; INV-SKEL-06 holds on 10⁴ random edits. |
| GATE-SKEL-07 | PO-SKEL-02 holds exactly; the mass of each archetype lies within 15% of the mass on file for its reference robot where one exists. |
| GATE-SKEL-08 | Patches: a stale parent refuses in 100 of 100 trials; a repeated idempotency key returns the same DesignId; a schema migration leaves forward kinematics and mass properties bit-identical and old runs replayable. |
| ✖ KILL-SKEL-SUBST | Trigger: any reused product differs from its recompiled value after one repair cycle, or leaf-local reuse saves less than 20% of compile time on the archetypes. Fallback: every substitution is global; the memo graph keeps subterm reuse by content hash only. |
| ✖ KILL-SKEL-PORT | Trigger: PO-SKEL-04 fails, or the tree-operator route of §16 is not funded. Fallback: no limb port packets; all dynamics go through the whole-model path. |
| ✖ KILL-SKEL-ALIAS | Trigger: stage 8 returns a witness that a hand-built policy defeats, or decides fewer than half of the planted cases within budget. Fallback: stage 8 becomes an advisory report built on A-14 coverage and refuses nothing. |
| ✖ KILL-SKEL-SEXPR | Trigger: INV-SKEL-04 cannot be held after one repair cycle. Fallback: the S-expression view is removed and JSON is the only syntax, as OPEN-SKEL-1 originally defaulted. |
Frontier items in this chapter, with what must precede funding:
| Item | Ceiling of the benefit, stated before any measurement | Paper-scale pilot and its falsifier | Kill gate |
|---|---|---|---|
| Certificate and analysis reuse under substitution F | The share of edit-to-first-step time spent recompiling and re-analysing unchanged limbs. Rollouts are never reused, so the end-to-end gain is bounded by that share. | For a single-limb swap on each archetype, list by hand the products the four conditions allow to be reused, and compare with a full recompile diff. Falsifier: one reused product that differs. | KILL-SKEL-SUBST |
| Limb port interface F | Enables the tree-operator route above the dense range; no benefit inside it | The two-link limb by hand: packet from the recursion against the reaction computed from the full equations. Falsifier: disagreement, or a definite matrix where a semidefinite one is correct. | KILL-SKEL-PORT |
| Stage 7 against clearance complexes F | Removes designs that cannot pass a doorway before any rollout; the gain is the share of candidates that fail on clearance, which is task-dependent and may be nil | One doorway and one box-shaped robot by hand, with the passing and failing widths. Falsifier: a route reported through a gap narrower than the body. | §19's kill gate for clearance complexes; fallback is A-07 passability on route graphs |
| Stage 8 observation alias F | Removes missions that no policy can solve on the given sensors; the gain is the training not spent on them | The beacon fixture and a left-or-right payload fixture by hand. Falsifier: a policy that succeeds in both worlds of a returned witness. | KILL-SKEL-ALIAS |
| OpenUSD import F | Access to assets published only in that format | Import one published robot asset by hand-mapping its schema. Falsifier: a mechanical field with no mapping. | Not built until a consumer exists |
- OPEN-SKEL-1. Closed by ADR-SKEL-02: JSON is canonical and the S-expression view is lossless and optional. The identifier is retired, not reused.
- OPEN-SKEL-2. Where card prices come from and under what licence. Default: prices are
assumed, the cost budget is advisory, and--strict-datarefuses a cost verdict. Owner: project lead. Blocks no gate before the build-packet work of §31. - OPEN-SKEL-3. How a task with continuous world parameters declares the finite family stage 8 searches. Default: the task's own randomization grid, with the grid recorded in the witness. Owner: Arena lead. Decide before stage 8 is funded.
- OPEN-SKEL-4. Whether the
latticefill needs anisotropy. Default: isotropic fraction only, with the assumption printed in the check report. Owner: Foundry lead. Blocks nothing before §31.
14.16 Module capability tables and the composed quasi-static screen
Capability tables F. This extends the substitution contract of §14.6. The contract there carries what the rest of the robot may rely on as scalars and ranges. A capability table carries what a module can do at its ports over a declared operating box, characterized once and cached by content, so that an assembly of modules can be screened by composing tables before any whole-robot computation runs. It adds nothing to what a contract may claim about contact dynamics: the three consequences listed for the limb port packet stand.
/// What a module can do at its ports over a declared operating box. DESIGN sketch: intent, not signatures.
pub struct CapabilityTable {
module: ModuleHash, cards: Vec<CardVersion>, version: CharacterizationVersion,
operating_box: OperatingBox, // end-effector pose cells in the port frame, speed bound, duty bins, bus range
wrench_outer: Vec<SupportRows>, // per pose cell: h(u) ≥ max uᵀw over attainable w, outward-rounded
wrench_inner: Vec<VertexSet>, // per pose cell: attained wrenches; their hull lies inside the true set
power: Vec<PowerBounds>, // electrical power over (wrench cell, speed, duty)
heat: Vec<HeatBounds>, // steady heat to the sink over the same cells
port_inertia: SymPsd6Range, first_mode: FrequencyInterval,
validity: Validity, // quasi-static; Froude number ≤ 0.5; bound on the neglected inertial wrench
}
Characterization. For each pose cell and each direction u of a fixed direction set, one cone program over the
module's own kinematics and cards (the program of A-24) gives the support value h(u) and an attaining wrench. Outer
rows are rounded outward and inner vertices are attained points, so the true attainable set lies between the two.
Power and heat rows come from the card laws of §15 at the attaining operating points. The table is a memo node
(§28.14) keyed by the module hash, card versions, operating box and characterization version; set-param, regear
or swap-actuator inside one module re-characterizes that module only. Verb: module.characterize (run).
The composed screen. For an assembly, a stance set σ (the modules bearing load, taken from the gait atlas or the task) and a quasi-static requirement with external wrench w_ext at the base,
find w_i ∈ W_i (i ∈ σ) with Σ_{i ∈ σ} Ad*(g_i)·w_i + w_ext = 0.
- With the outer sets, each enlarged by the validity record's bound on the neglected inertial wrench, infeasibility
excludes the assembly for that requirement and stance, with an
lp-farkascertificate. The result is typedouterand names its load-sharing model (rule 1 of §28.4). - With the inner sets, each shrunk by the same bound, feasibility is a typed
innerwitness. - Otherwise the assembly is
unresolvedand goes to the next rung. - The electrical bus is checked by the joint time-indexed schedule of A-23, never by a sum of peaks, and heat by the sink balance of the contract.
The screen runs at stage 6 of design.check and at stages 1 and 2 of the cascade (§28.11). Its margins (payload
margin, estimated energy per metre) are a screening signal under §28.10: they discard only in strata where rank
agreement has been measured.
Known answers. Four identical one-joint legs, each a horizontal link of 0.25 m with a torque limit of 10 N·m, can each press with at most 40 N. Under a 16 kg body (156.96 N) on a square stance with feet at (±0.2, ±0.2) m:
- centre of mass centred: 39.24 N per foot, admitted;
- centre of mass 0.05 m forward: the front pair must carry 0.625 × 156.96 = 98.1 N > 2 × 40 N, excluded for every force distribution. The certificate is the vertical force balance plus the pitch moment balance.
Counterexample: a table is valid for its stance set only. The centred body above is admitted with four feet down. In a trot two diagonal feet carry the weight, 78.48 N each against 40 N. A screen that reuses the four-foot result for a trotting requirement admits a robot that cannot trot. The stance set is part of the query and of the result.
What the screen may not conclude. An outer exclusion is an exclusion of the quasi-static requirement in the
declared stance. A dynamic strategy that uses momentum is outside it, as the approach-energy case of §28.4 shows.
Above the validity regime the screen returns unresolved, never a verdict.
Cost and ceiling. TARGET, unmeasured: characterization of one module in seconds on the CPU (64 pose cells × 26 directions = 1,664 small programs); a composed screen under 1 ms, so on the order of 10³ assemblies per core-second. Ceiling, stated first: the screen decides only what static composition can decide. It removes whole-robot work for the candidates it excludes or admits and none for the rest, and limbs coupled through a light moving base are not isolated at their ports, which is why no dynamic verdict is composed.
| Gate | Claim | Threshold (TARGET) | First milestone |
|---|---|---|---|
| GATE-SKEL-09 | Known answer | The two stance cases and the trot counterexample exactly; inner ⊆ outer on 10⁴ random directions per archetype module; an edit inside one module re-characterizes one table and no other | M3 |
| GATE-SKEL-10 | Design comparison | On 200 assemblies across the wheeled, tracked, legged and hybrid families, on carrying, ramp and threshold tasks inside the validity regime: discarding the bottom 90% by the composed screen keeps at least 9 of the true top 10 found by batched evaluation; Spearman ρ at least 0.75 on energy per metre and on payload capacity; every audited outer exclusion fails its quasi-static requirement on the referee |
M4 |
| Kill gate | Trigger | Fallback |
|---|---|---|
| ✖ KILL-SKEL-CELL | Top-10 recall below 90% or ρ below 0.75 at GATE-SKEL-10: no automatic discard from the screen. One unsound outer exclusion: the exclusion rule is suspended under the prune-soundness audit of §28.12 |
Tables remain as a sizing report for agents; design.check runs its whole-robot analyses as before |
14.17 Folding fixed joints, and reduced models
What it is. S A rule for lumping a link behind a fixed joint into its parent, in import (§14.12) and in the
lowering of §14.9, and a rule for a model that leaves parts out. A folded model is the same rigid body. A model that
omits mass is a different robot and is named as one. Owner: frob-io (import), frob-model (lowering). Verbs:
design.import, design.check stage 2.
The fold. For a child with pseudo-inertia 𝖯_c (§11.5) attached by the fixed transform G = parent_from_child, the parent's pseudo-inertia becomes 𝖯_p + G·𝖯_c·Gᵀ (§11.4). That one sum carries the mass, the first moment and the second moment about the parent's origin, and it is exact in rationals. Every named attachment of the child (sensor frames, collision shapes, contact sites, port frames) is re-parented with the composed transform and keeps its identifier. The loss report lists each folded link.
Hand case. A parent of 2 kg with rotational inertia 0.02·I kg·m² about its origin carries a welded child of 1 kg with inertia 0.01·I about its own centre, placed at (0.3, 0, 0) m. The fold has mass 3 kg, centre of mass at (0.1, 0, 0) m, inertia diag(0.03, 0.12, 0.12) kg·m² about the parent origin and diag(0.03, 0.09, 0.09) about the combined centre. Adding the two inertias without the offset term gives 0.03·I about the origin, wrong by 0.09 kg·m² on two axes. Dropping the child gives 2 kg.
Reduced models. DESIGN. A design that leaves out bodies of the source carries reduced: { omitted: [...], omitted_mass }, and every result on it cites the reduction. An import that drops a body of nonzero mass without
declaring a reduction is refused (refusal: mass dropped at import without a declared reduction). Import parity
(§14.10) is judged against the full source: a round trip compares total mass, first moment and pseudo-inertia of every
folded group, and the map of named attachments.
FACT (frankensim/crates/fs-mbd/src/robot_models.rs:398–403 at 483d09c682f2, read 2026-11-21): the suite's G1
catalog builder states that fixed rubber hands, head, pelvis contour, logo, waist supports and sensor attachments are
omitted and that "their nonzero masses are not lumped into retained links". Its 30 retained links sum to 31.96314202
kg (summed for this section from the source table). FACT (the pinned upstream description of the same robot; reported,
to be re-read from the primary source before a gate cites it): four welded links, the head, the logo and the two
hands, add 1.377 kg, for 33.34014202 kg over 38 links.
Known answer. At 9.81 m/s² the reduced model weighs 313.5584 N and the source assembly 327.0668 N. A static support
rated at 320 N passes on the reduction and fails on the robot. The builder is therefore used as the profile
g1-reduced-30, and the humanoid archetype's import parity is against the 38-link source.
| GATE-SKEL-11 | Known answer. On 10³ random trees with fixed joints the folded model's mass, first moment and pseudo-inertia equal the sums over the unfolded links exactly in rationals and to 10⁻¹² relative in double precision; forward dynamics of the folded model and of the unfolded model with the joints held as constraints on the referee agree to 10⁻⁹; every named attachment resolves to the same world pose at 100 random configurations. The hand case is exact, and the mutant without the offset term fails it. The g1-reduced-30 profile reports its omissions, sums to 31.96314202 kg, and the 320 N fixture passes on it and fails on the full import. M1. |