Architecture

Tatbot is intentionally split into small build roots so a contributor can develop one surface without installing the entire robotics stack.

operator or test
      │
      ├── ROS 2 stack (ros/) ─┐  drawing: one arm, ballpoint
      ├── C++ teleop ─────────┤
      ├── LeRobot adapter ────┼── robot interface
      ├── Rust visiond ───────┘
      ├── Python simulator
      └── Web Inkmap ── placement JSON

placement text ── InkLang intent + body atlas ── rest-surface anchor
motif/style text ── Inkgen ── source PNG ── DrawingBot V3 ── artwork

TattooProgram ── SurfacePlacement ── InkProgram
 body-free art      target address     tool intent

plane design + fitted tool + registered page
      └── tatbot ros compile ── program.json ── tatbot ros draw
body placement ── measured address mapping still required (refused)

Boundaries

  • ros/ owns autonomous drawing: the ROS 2 Jazzy stack that compiles a design, registers the page, touches it and draws (ros/README.md).

  • cpp/teleop/ owns the high-rate leader/follower teleop loop.

  • python/lerobot_robot_tatbot/ owns the LeRobot adapter and episode API.

  • rust/visiond/ owns camera capture, synchronization, and replay data.

  • python/tatbot_sim/ owns hardware-independent fixtures and simulation.

  • web/inkmap/src/core/inklang/ owns the single placement-text to rest-surface-anchor implementation. Its JSON contracts are language-neutral.

  • web/inkmap/ owns browser-side placement confirmation, editing, and preview; Python simulation consumes canonical InkLang output rather than resolving a second semantic location.

  • web/inkgen/ owns artwork generation, never anatomy grounding.

  • firmware/estop_pico/ owns the e-stop heartbeat endpoint.

  • config/ and urdf/ are shared interfaces; consumers must record their revision in a run manifest.

The human-representation contracts preserve two different geometry authorities. A digest-bound SOMA mid surface may provide a nominal semantic, pose, and preview prior. A measured local tatbot.surface/1 remains the only metric surface an execution program may bind. Nominal geometry cannot fill a missing observed cell.

TattooProgram, SurfacePlacement, and InkProgram carry artwork, target addresses, and ordered tool intent. The robot draws plane designs: tatbot_ink compiles them into the ROS 2 stack’s program.json. Simulation lowers retained designs through the shared Cartesian compiler and C++ planner into checked tatbot.draw-samples/1. Neither supplies a body mapping.

The old ExecutionProgram/1 schema and synthetic fixtures remain readable for historical inspection, but its standalone compiler has been retired. Research and learned modules cannot write samples or import motion authority.

The pinned MHR-through-SOMA model spec has an explicit offline cache bootstrap and hash-only audit. It is the sole nominal-body provider and Inkmap default: a numeric BodyIdentity/1 is transferred through SOMA’s fixed mid topology, and named poses preserve those face addresses. This software cutover does not authorize deployment, capture, motion, emissions, or human contact.

Body cache verification

tatbot body bootstrap --spec SPEC --source-dir SOURCE --cache-dir CACHE copies an explicit, pre-downloaded allowlist into an immutable cache. tatbot body audit --spec SPEC --cache-dir CACHE verifies it by hash without deserializing model assets or using the network. State global --json before the command for machine output; --output DIR on audit optionally writes an immutable report outside the cache and repository.

The stdlib tatbot-contracts package owns canonical JSON and these validators. The CLI and simulator use the same reviewed spec digest and verify assets again at their respective input boundaries. Missing, changed, writable, symlinked, or unlisted assets are refusals. Hash verification is not model execution or hardware qualification.

A nominal body cannot supply a missing physical measurement.

Differentiable patches, proposal training, compliant phantom mechanics, coupled mechanics and generic anatomy are frozen experiments. Existing tests and historical reproducers remain, but new runtime consumers are rejected by the stdlib body check. Reopening requires a named consumer, measured baseline deficiency, experiment and acceptance criteria. See human-representation consumers and evidence for the maintained core and the next non-human fixture experiment.

The private deployment graph, node roles, credentials, and acceptance evidence are deliberately not part of this page.

See InkLang for the prompt-to-location contract and Inkmap for its browser consumer. Pose, support, world transforms, and reach enter only when a PlacementFile is compiled into a TattooScenario.

Change guide

Start with the smallest component README, add or update a focused test, then run scripts/check --light. If an interface crosses components, document the schema and compatibility rule before changing both sides.