--- title: "Architecture Garden — dropcut-studio" description: "Architecture Garden — dropcut-studio dropcut-studio is a TypeScript CAM monorepo with a nested Go controller (makera-z1-cli) that commands a Makera Z1 CNC machine over a single TCP connection. This …" doc_version: 1 last_updated: 2026-10-17 canonical_url: "http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/readme" --- # Architecture Garden — dropcut-studio Architecture Garden — dropcut-studio dropcut-studio is a TypeScript CAM monorepo with a nested Go controller (makera-z1-cli) that commands a Makera Z1 CNC machine over a single TCP connection. This … ## Tags - `architecture-garden` - `dropcut-studio` - `cnc` - `protocol` - `command-control` - `safety` - `go` ## Content # Architecture Garden — dropcut-studio `dropcut-studio` is a TypeScript CAM monorepo with a nested Go controller (`makera-z1-cli`) that commands a Makera Z1 CNC machine over a single TCP connection. This Garden project studies the **communication / command-control protocol** between the Go controller (`z1ctl`) and the machine firmware — not the CAM compiler, the JavaScript scripting host, or the machining certificate, which are covered by the repository's own docmgr tickets (MZ1-004 and the CAM series). The controller is better structured than a typical ad hoc CNC client: typed motion operations, an explicit risk-class ladder, a no-retry rule for motion, fresh preflight, a dead-man jog, and loopback-first web posture are all sound. The reusable pattern documented here is the one that sits underneath all of those and that is the most broadly portable to other command-control line protocols: how a host that does **not** own a device's output stream still delimits and correlates per-command replies. > [!summary] > - The controller speaks a framed binary protocol to the machine and uses an > **injected sentinel** (`echo \x04`) to mark the end of each command's > output, relying on the firmware's ordered line queue. > - The pattern is portable to any command-control line protocol where the > host cannot frame the peer's replies directly (embedded serial shells, > GRBL/Smoothieware-derived firmware, U-Boot, Expect-style automation). > - Its correctness hinges on one distinction: a **constant sentinel is a > delimiter, not a correlation identifier**. A correct design correlates by > value (a per-command nonce) or quarantines the session on any ambiguous > timeout — it never treats a timed-out exchange as silently resumable. ## Design entries - [[Research/Software Architecture Garden/dropcut-studio/designs/04 - First-Class Session with Typed State Machine, Unique Correlation, and Quarantine Recovery|04 — First-Class Session: Typed State Machine, Unique Correlation, Quarantine Recovery]] *(overarching pattern — the session skeleton; the entries below are its facets)* - [[Research/Software Architecture Garden/dropcut-studio/designs/01 - Sentinel-Delimited Command Completion over an Ordered Line Queue|01 — Sentinel-Delimited Command Completion over an Ordered Line Queue]] *(facet: correlation / identity)* - [[Research/Software Architecture Garden/dropcut-studio/designs/02 - Latched Safety Channel over a Lossy Inbound Queue|02 — Latched Safety Channel over a Lossy Inbound Queue]] *(facet: safety delivery / observability)* - [[Research/Software Architecture Garden/dropcut-studio/designs/03 - Dead-Man Keepalive - Fail-Safe Motion by Causal Inversion|03 — Dead-Man Keepalive: Fail-Safe Motion by Causal Inversion]] *(facet: fail-safe action)* ### Implementation-derived entries added 2026-09-13 - [[Research/Software Architecture Garden/dropcut-studio/designs/06 - Consecutive Evidence Observer - Completion Without Owning the Operation|06 — Consecutive Evidence Observer]] — a domain-classified reducer for consecutive completion evidence, independent of polling and transport. - [[Research/Software Architecture Garden/dropcut-studio/designs/07 - Browser Intent Ownership - Confirm Once and Renew Only While Held|07 — Browser Intent Ownership]] — one-shot confirmation and held-gesture lifecycles outside React, with stale-response fencing and explicit cleanup limits. These entries describe commits `a5faea1` and `8b8d947`; they do not replace the historical analysis above or establish new hardware acceptance. ### Bounded observation and subscription pattern added 2026-09-13 - [[Research/Software Architecture Garden/dropcut-studio/designs/08 - Bounded Cursor Broadcast - Independent Readers with Explicit Gaps|08 — Bounded Cursor Broadcast: Independent Readers with Explicit Gaps]] — one bounded shared history, independent reader cursors, explicit retention loss, snapshot-to-subscription continuity and cancellation independent of machine operations. Updated after implementation commit `be7c744`: the entry now documents the concrete `pkg/broadcast.Buffer[T]` API and all three integrations—protocol observations, controller snapshots/subscriptions and the legacy diagnostic message journal. The shared extraction is implemented and its focused race tests and vet pass. The pattern requires neither a message broker nor a lossless journal. Earlier entries remain historical analyses, not a claim that old grant/dead-man proposals are current stock-firmware capabilities or current P3 requirements. ### Controller ownership and evidence separation added 2026-09-13 - [[Research/Software Architecture Garden/dropcut-studio/designs/09 - Single-Owner CNC Controller - Worker Ownership Separate from Operation Evidence|09 — Single-Owner CNC Controller: Worker Ownership Separate from Operation Evidence]] — the actual controller architecture, two identified command/review slots, concrete evidence checks, cancellation/reconciliation behavior and a deliberate complexity budget. Implemented cleanup at `da0d33d`; broader P3 and production cutover remain incomplete. ## Proposals - [[Research/Software Architecture Garden/dropcut-studio/proposals/01-z1-communication-api-design-and-implementation-guide|01 — Z1 Communication API: Design and Implementation Guide (Intern Edition)]] — a concrete `pkg/z1session` API design realizing designs 01–04 above. ## Source provenance The detailed study behind this Garden project is a docmgr ticket, `MZ1-005`, authored in the source repository's `ttmp/` tree (branch `task/cnc-control- dropcut`, local commit `5f33ba1`, not yet pushed at analysis time). The Garden entry is the cross-project distillation; the ticket is the full evidence-led investigation. Where they disagree, the ticket has the deeper line-anchored evidence and the Garden entry has the portable abstraction. ## Wiki Links - Research/Software Architecture Garden/README - Research/Software Architecture Garden/dropcut-studio/designs/01 - Sentinel-Delimited Command Completion over an Ordered Line Queue - Research/Software Architecture Garden/dropcut-studio/designs/04 - First-Class Session with Typed State Machine, Unique Correlation, and Quarantine Recovery - Research/Software Architecture Garden/dropcut-studio/designs/01 - Sentinel-Delimited Command Completion over an Ordered Line Queue - Research/Software Architecture Garden/dropcut-studio/designs/02 - Latched Safety Channel over a Lossy Inbound Queue - Research/Software Architecture Garden/dropcut-studio/designs/03 - Dead-Man Keepalive - Fail-Safe Motion by Causal Inversion - Research/Software Architecture Garden/dropcut-studio/designs/06 - Consecutive Evidence Observer - Completion Without Owning the Operation - Research/Software Architecture Garden/dropcut-studio/designs/07 - Browser Intent Ownership - Confirm Once and Renew Only While Held - Research/Software Architecture Garden/dropcut-studio/designs/08 - Bounded Cursor Broadcast - Independent Readers with Explicit Gaps - Research/Software Architecture Garden/dropcut-studio/designs/09 - Single-Owner CNC Controller - Worker Ownership Separate from Operation Evidence - Research/Software Architecture Garden/dropcut-studio/proposals/01-z1-communication-api-design-and-implementation-guide ## Backlinks - [research/software-architecture-garden/dropcut-studio/designs/03-dead-man-keepalive-fail-safe-motion-by-causal-inversion](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/03-dead-man-keepalive-fail-safe-motion-by-causal-inversion) - [research/software-architecture-garden/dropcut-studio/designs/02-latched-safety-channel-over-a-lossy-inbound-queue](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/02-latched-safety-channel-over-a-lossy-inbound-queue) - [research/software-architecture-garden/dropcut-studio/proposals/01-z1-communication-api-design-and-implementation-guide](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/proposals/01-z1-communication-api-design-and-implementation-guide) - [research/software-architecture-garden/dropcut-studio/designs/05-exclusive-renewable-authority-a-linearizable-lease-for-hazardous-continuation](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/05-exclusive-renewable-authority-a-linearizable-lease-for-hazardous-continuation) - [research/software-architecture-garden/dropcut-studio/designs/08-bounded-cursor-broadcast-independent-readers-with-explicit-gaps](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/08-bounded-cursor-broadcast-independent-readers-with-explicit-gaps) - [research/software-architecture-garden/dropcut-studio/designs/01-sentinel-delimited-command-completion-over-an-ordered-line-queue](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/01-sentinel-delimited-command-completion-over-an-ordered-line-queue) - [research/software-architecture-garden/dropcut-studio/designs/09-single-owner-cnc-controller-worker-ownership-separate-from-operation-evidence](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/09-single-owner-cnc-controller-worker-ownership-separate-from-operation-evidence) - [research/software-architecture-garden/dropcut-studio/designs/04-first-class-session-with-typed-state-machine-unique-correlation-and-quarantine-recovery](http://parc.yolo.scapegoat.dev/note/research/software-architecture-garden/dropcut-studio/designs/04-first-class-session-with-typed-state-machine-unique-correlation-and-quarantine-recovery) ## Sitemap - [Home](http://parc.yolo.scapegoat.dev/) - [Home markdown mirror](http://parc.yolo.scapegoat.dev/index.md) - [Markdown sitemap](http://parc.yolo.scapegoat.dev/sitemap.md)