mechanical-compiler/docs/ROADMAP.md

# ROADMAP.md

What the Mechanical Compiler is for.

**This document records intent, not commitment.** It is a reference for what the
project aims at and why; it does not schedule work and nothing here is a promise
that something will be built. `HANDOFF.md` §4 holds the actual order. Where the
two disagree, §4 wins on sequence and this document wins on purpose.

§§1, 2, 3 and 7 are the durable parts and are still correct. §4's sequence and
§5's production assumptions have both drifted since 18 AUG; the divergences are
recorded as open questions in `HANDOFF.md` §11 rather than patched here, because
resolving them needs the whole repository in view at once.

| | |
|---|---|
| Updated | 2026-08-18 |
| Companions | `PROCESS.md`, `ENVIRONMENT.md`, `STAGING-STATE.md`, `FAILURES.md` |

---

## 1. Mission

**Build the capacity to construct real structures from reclaimed and
commodity materials, using whatever fabrication a person actually has.**

The reference case is a faceted timber shell: planar panels meeting along
straight fold lines, converging on nodes, sitting on a platform. Buildable
without a factory, from 3D printing, tabletop CNC, welding, cement casting, and
COTS stock — provided someone has worked out what the pieces are and how they
meet.

That last clause is the whole project. The Mechanical Compiler exists to make
the pieces computable, qualifiable, and reproducible by someone who was not
present when they were designed.

**Explicitly not in scope:** building codes, permitting, and jurisdictional
approval. Qualification and compliance are different animals. A qualification
says *this member is what it claims to be, made this way, from this stock*.
Compliance is a jurisdiction-specific argument someone else may build on top.
Plenty of legitimate contexts — agricultural, temporary, accessory, artistic —
never need the second thing.

The cheap hedge, taken deliberately: **record physical claims, never verdicts.**
Section modulus, moment of inertia, material provenance, process parameters.
Those cost nothing to capture, since the geometry layer computes most of them
anyway, and they are what any future argument would need. Recording a pass/fail
verdict would bake in a jurisdiction we do not want to be bound to.

Measure and attest. Never adjudicate.

---

## 2. Three artifact classes

Reading the reference structure back into components gives three kinds of
thing, only one of which currently exists.

### Members — prismatic, exists

Straight runs where panels meet along a fold line. Fixed cross-section, 10 to
100 feet, made from pallet-strap bundles in a printed enclosure.

This is the strap-beam work. Eleven profiles, locked at revision 8.0.0, frozen
as a 123-case fixture oracle.

Read as edge conditions rather than as shapes, the catalogue stops looking
arbitrary:

| Profile | Edge condition |
|---|---|
| T | panel-edge stiffener — flange takes the sheet, stem is the web |
| Y, Three-Fin | seams where three surfaces converge along a line |
| A Frame | a gable in section |
| Ring profiles | closed torsion boxes — perimeter, sill, deck edge |

The fins are not decoration. They are where the panel gets fastened.

### Nodes — non-prismatic, does not exist

Where fold lines converge. Look at the hipped ends of the reference structure:
four or five edges meeting at a vertex, at angles that differ at every corner.

Short, geometrically unique, almost certainly fully printed or cast. **Not a
strap beam, and will not come out of the current library.** No representation
exists yet.

### Panels — sheet, does not exist

The planar faces. CNC-cut from sheet goods. Every face in the reference
structure is planar, which is a hard constraint on the form and also exactly
what makes it buildable from sheet plus edge members.

Convenient technical note: planar polygon algebra, edge extraction and
unfolding are precisely what Shapely and CadQuery are good at. The toolchain
choice looks better after seeing the reference than before it.

**This is why interface contracts sit at the centre of the design.** A node
declares what member ends it accepts; a member declares what end it presents; a
panel declares its edges. Without that, three artifact classes are three
unrelated generators.

---

## 3. The gap that changes the backlog

If two panels meet at 137°, none of the eleven profiles gives you a member for
it.

`a_frame_leg_angle_deg` is the only dihedral-ish parameter anywhere, and the
crossbar geometry pins it to 20–53°. The Three-Fin's fins are locked at 120°
because they derive from a regular polygon. The library solves placement
against **webs** — the PLA between strap channels — but nothing solves
placement against **the angle between attachment faces**.

Closing this is an addition the architecture already supports:
`sb_member_on_edge` takes an arbitrary direction, `sb_fin_profile` takes N, and
the solver converges on measured quantities. A dihedral-parameterised family is
a new call into the same machinery, not a new machine.

**It moves ahead of the rebar-core bore variant in priority.**

---

## 4. Sequence

### Done

- **Rev 8.0.0 generators.** Six 3x profiles, five 4x profiles, shared N-generic
  library. Every wall measures its declared minimum; symmetric profiles are
  provably non-chiral; profile parameters are isolated from one another.
- **Fixture oracle frozen.** 123 cases, `ddd0f154…`, pinned to OpenSCAD 2021.01
  and BOSL2 `92d697c`. The ten rejected cases are part of the contract.
- **Staging infrastructure accepted, 2026-08-16.** Host, both containers,
  network isolation, bastion access, TLS trust, reverse proxy and the
  application filesystem foundation are proven on `srv-b`. Mail alerting and
  explicit disk monitoring are deferred; backup strategy is postponed by
  operator decision; application deployment remains blocked on application
  code. See `STAGING-STATE.md`.
- **Mail alerting accepted, 2026-08-17.** Delivered end to end and received
  twice.
- **Disk monitoring accepted, 2026-08-17.** Four P410i members explicitly
  monitored, four test alerts received, serial numbers recorded, reboot-proven.
- **Container SMTP egress blocked, 2026-08-17.** The project-local half of F-025
  is corrected; the estate question about `wg-pk` client trust remains open.
- **Repository seeded, 2026-08-18.** Reference implementation, frozen oracle,
  pinned toolchain and test harness at `c7e32d8`. Dependencies installed, oracle
  verified in-container, `3 passed, 236 skipped`.
- **Container baseline established, 2026-08-18.** All three containers on
  `srv-b` conform, asserted by an executable check rather than by inspection.

### Next — the port

Port `sb-geom` to Shapely; `pytest -n auto` green against all 123 cases. A port
that accepts the ten rejections is wrong.

Why this rather than more OpenSCAD: exceptions can be caught. Roughly half the
defensive complexity in the current library exists because an OpenSCAD assert
is fatal and uncatchable — `sb_path_max_round()` exists solely because a radius
could not be probed and the failure caught. Testing becomes pytest in CI rather
than bash scraping echo lines. And SVG generated from Python can emit the
outline, each strap channel and the bore as separately classed paths, which is
what makes hover and layer toggling possible in the catalogue.

### Then, roughly in order

1. **Dihedral-parameterised members** — see §3.
2. **Rebar-core bore variant** — Utility One's 40-ft side member is three strap
   chords around a rebar core. The bore stops being a byproduct of the inside
   walls and becomes a declared interface with a diameter and a fit class.
3. **Catalogue front end** — the reason for the web application. Customizer is
   too limiting; SVG plus JavaScript, driven by the same generators.
4. **Node connectors** — new artifact class, new representation.
5. **Panels and unfolding** — new artifact class.
6. **Interface contracts** — formalised once two classes exist to connect. Not
   before; §6 of Part I is right that use cases precede interface
   proliferation.
7. **Qualification and attestation** — physical claims bound to a generator
   revision. `SB_REVISION` already exists for this.
8. **Production instance** — automation derived from the proven staging
   procedure. See §5.
9. **YunoHost packaging** — see §6.

Higher polygon counts are **not** on this list. 4x is the end of the N-strap
family; hexagons and above compose from triangles and squares rather than
getting their own generators.

---

## 4a. Parallel project

**Kane Fabric** — a separate project on the same host, and the platform on
which SASE, HOA Diagnostics, the Mechanical Compiler and other SASE-consuming
projects are implemented.

It is recorded here so its existence is known, not because it creates work.
Kane Fabric owns geographic state; the Mechanical Compiler owns member
geometry, qualification and workflow state. Both sets of documents describe a
future interface between them; **neither defines it, and that is deliberate.**
Part I §6 holds that use cases precede interface proliferation, and no use case
crosses the boundary yet.

The contract becomes real work when a compiled member first needs to be sited
somewhere. It will be cheaper to define then, against a concrete artifact.

---

## 5. Staging to production

`srv-b` is standalone and will remain so. Promotion is export/restore, not
cluster migration.

The order is deliberate: **manual first, then automation derived from the
proven procedure.** `FAILURES.md` is the evidence for why. Three specification
assumptions were wrong in ways only contact with a host revealed, and scripts
written from the specification alone would have faithfully reproduced all
three — one of them producing a container that booted, looked healthy, and had
four broken services.

When production is provisioned, the automation is written from `FAILURES.md`
first and `ENVIRONMENT.md` second.

Production differs from staging in four known ways, recorded so they are not
invented under pressure:

| | Staging | Production |
|---|---|---|
| Certificate | local staging CA | Let's Encrypt, per-name, no wildcard |
| FQDN | `mechanical-compiler.dev.infra` | `mechanical-compiler.manufacturing.kane-il.us` |
| Proxmox firewall | disabled | must be revisited |
| Proxy location | CT 101 on the same host | undecided — **not on the WireGuard side**, since the current NAT is outbound-only |

Three variables change in `mechcomp.env`: `MECHCOMP_ENV`, `MECHCOMP_BIND`,
`MECHCOMP_BASE_URL`. Nothing else.

---

## 6. Distribution

**YunoHost and Docker are parallel targets, not sequential.** YunoHost apps
install natively — apt, venv, systemd, nginx — and the project does not want
Docker inside YunoHost. Neither blocks the other, and neither should be built
"in order to" reach the other.

On the catalog's weight criterion: it reads "resource-hungry **compared to
their features**" and is aimed at marginal apps. `fab-manager_ynh` is in the
catalog; `paperless-ngx_ynh` declares nine apt dependencies including
postgresql and redis. The useful comparison is those, not a hello-world.

On provenance: the project is LLM-generated under human direction, stated
plainly in the README and in any submission. The catalog policy is a **quality
bar with a disclosure requirement, not a ban** — it rejects generated packages
that do not follow `example_ynh`, citing verbose code, hallucinated helpers and
non-standard directory architectures, then explicitly permits AI use where the
maintainer is transparent and can explain every line.

Two consequences. The package is drafted against `example_ynh` and reviewed by
CIVICVS as his own work; anything he would not defend in a review thread does
not ship. And disclosure belongs in the README, not in the pitch — if
provenance becomes the pitch, the project gets judged on that axis instead of
on whether it makes distributed manufacturing capacity legible.

---

## 7. Standing principles

1. **Measure, do not assume.** Every wall thickness in rev 8 is a measured
   value. Connectivity is necessary and never sufficient — revision 7 passed
   cross-sections joined by 0.13 mm.
2. **Solve numerically against the real quantity.** Closed-form placement is
   where the wrong-by-a-cosine errors came from.
3. **Structure before decoration.** Members butt through their neighbours;
   fillets are applied on top of that overlap, never instead of it.
4. **Hash inputs, not outputs.** Mesh bytes are not reproducible across
   toolchain versions. Hashing parameters plus generator revision keeps a
   qualification valid across an upgrade that did not change the geometry.
5. **A permanent deviation is not a deviation — it is the specification.**
   Promote it and delete the exception.
6. **Record the failure before correcting it.** Then apply the smallest
   corrective change, not the one that also fixes three things you were
   worried about.
7. **Prove the negative.** Isolation is asserted by showing the forbidden path
   fails, never by showing the interface is gone (F-018). Health is asserted
   after a reboot, never before (F-021).
8. **Handoff is not delivery.** An upstream acceptance code proves the message
   left, not that it arrived (F-023). The same distinction applies wherever a
   subsystem reports success on behalf of something downstream.
9. **Record what a change grants, not only what it repairs.** A trust rule
   added to fix one rejection may authorise far more than the case that
   prompted it (F-025).
10. **Shared infrastructure is not ours to reconfigure.** An instance may
   configure its own client side; changes further down the chain are escalated
   with evidence.
11. **A test must distinguish tool failure from the condition it tests.** One
   whose failure mode is indistinguishable from success manufactures
   confidence (F-027). Every negative assertion first establishes that it could
   have observed the positive case.
12. **A component surviving its own restart is not proven to survive the
   host's.** Different machinery; assert against the one that matters (F-026).
13. **A standard must be executable.** If conformance cannot be asserted by
   running something, it is not a standard but a recollection, and it will
   drift. A property not checked is not part of the standard (F-031).
14. **Check the thing, not something related to it.** An assertion inferred
   from an adjacent observation is not evidence, however reasonable the
   inference (F-031).
15. **Verify by counting, not by scanning.** A long, correct-looking list is
   exactly where an unexpected 437 files hide (F-029).
16. **Conformance precedes backup.** Backing up an unverified configuration
   preserves the confusion along with the data, and a restore returns it
   faithfully.
17. **Nothing approximate may write to anything reproducible.** Principle 4
   governs what is hashed; this governs what may reach the thing being hashed.
   A search index, a documentation system or a language model may read design
   records freely and may suggest anything to a person. None of them may
   originate a parameter that lands in a record. The failure is silent and
   compounding: if suggestions become records and records become the corpus,
   the corpus teaches itself its own guesses, and every record is still
   perfectly correct about what it was built from. A suggestion is an input to
   a person, never an input to a build — and where one informed a build, the
   record's `note` field says so, being already excluded from both hashes.
18. **A contribution is admitted by the oracle, not parsed by the compiler.**
   The path from a new profile to the catalogue runs: author it in whatever
   notation suits you, freeze its cases inside the pinned toolchain, port it,
   and admit it when the oracle passes byte-identically. This has happened
   twice, with both `.scad` generators. The consequence is that no second
   geometry engine is ever kept in step with the first, and `legacy/` holds the
   reference tier rather than superseded code. When someone asks for another
   input format, the answer is that notation never runs in production — only
   the kernel does.