TheRON
56e0570f10
ROADMAP.md was described as a reference rather than a commitment -- something
that documents intent and will eventually become a roadmap. The header now says
so, and says that HANDOFF section 4 holds the actual order. Sections 1, 2, 3 and
7 are durable and still correct; section 4's sequence and section 5's production
assumptions have drifted since 18 AUG.
Principle 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, but none 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 remains perfectly correct about what it was built
from. Where a suggestion informed a build, the record's note field says so,
being already excluded from both hashes. No new field is needed and the
discipline is written down before there is anything to guard against.
Principle 18: a contribution is admitted by the oracle, not parsed by the
compiler. Author in whatever notation suits you, freeze the cases inside the
pinned toolchain, port, and admit when the oracle passes byte-identically. This
has happened twice, with both .scad generators -- it describes what was done
rather than what is planned. Two consequences: 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.
A third principle was drafted and dropped -- that artifacts cross a service
boundary and geometry does not. Section 4a's own rule is that use cases precede
interface proliferation, and writing a principle about a kernel service boundary
while the kernel is not a service is precisely that. It is a gate, not a
principle, and the kernel can acquire one when it acquires a boundary.
HANDOFF section 11 gains rows 12 through 16, all found by reading ROADMAP.md
properly rather than grepping it. Section 5 names a production FQDN that the
printed name contradicts. Section 5 says the production proxy is not on the
WireGuard side, for a reason the DNAT at 1fdb115 removed. Section 4a says no use
case crosses the Kane Fabric boundary and that neither project defines the
interface -- membership-gated export is that use case, and IDENTITY-CONTRACT.md
defines the identity half, while the siting interface 4a is actually about
remains undefined and should stay so. ROADMAP section 4 and HANDOFF section 4
are different lists. And legacy/ is misnamed.
None are resolved here. Two are CIVICVS's, two want the whole repository in view
at once, one is cosmetic. Recorded so the reconciliation pass finds them written
down rather than rediscovering them cold.
Mechanical Compiler
Build the capacity to construct real structures from reclaimed and commodity materials, using whatever fabrication is actually to hand — 3D printing, tabletop CNC, welding, cement casting, COTS stock.
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, provided someone has worked out what the pieces are and how they meet. That last clause is the project. The Mechanical Compiler exists to make the pieces computable, qualifiable, and reproducible by someone who was not present when they were designed.
Scope
In scope: geometry, qualification, and reproducibility of structural members and their interfaces.
Not in scope: building codes, permitting, jurisdictional approval. Qualification and compliance are different things. 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.
The project records physical claims, never verdicts — section modulus, moment of inertia, material provenance, process parameters. Those are what any future argument would need. A pass/fail verdict would bake in a jurisdiction we do not want to be bound to. Measure and attest; never adjudicate.
Repository layout
docs/ specification, state, failure log, roadmap
legacy/openscad/ rev 8.0.0 generators — reference, not a live target
fixtures/ frozen acceptance oracles
tools/reference-toolchain/ pinned OpenSCAD + BOSL2, build-time only
src/mechcomp/ the application
tests/ acceptance against the oracle
Read docs/ROADMAP.md first for what this is, then docs/ENVIRONMENT.md for
how an instance is built. If you are writing provisioning automation, read
docs/FAILURES.md before the specification — every entry is something a
script written from the specification alone would have got wrong.
Getting started
make deps # virtualenv, base + CAD requirements
make verify-oracle # confirm the frozen oracle is intact
make test # pytest -n auto
make verify-oracle needs nothing but Python. It should pass on any machine at
any time; if it does not, stop.
The oracle
fixtures/strap-beam-8.0.0/ holds 123 frozen cases — 113 accepted, 10
rejected — produced by OpenSCAD 2021.01 with BOSL2 at 92d697c2. It is the
acceptance criterion for any reimplementation of the generators.
The ten rejected cases are part of the contract. A port that accepts them is wrong, however good its numbers look elsewhere. It is easy to reproduce the geometry and quietly lose the constraint that made it trustworthy.
The generators under legacy/openscad/ are the reference implementation, kept
so the oracle can be regenerated. They are not a live target and the running
application has no OpenSCAD dependency.
Provenance
This project's documents, code and roadmap are LLM-generated under human direction. That is stated plainly here and in any downstream submission. We do not obscure it.
The maintainer reviews and owns every line. Anything that could not be defended in a review thread does not ship.
Licence
AGPL-3.0-or-later. See LICENSE.
Section 13 obliges us to offer source to users interacting over a network, so any deployed web tier carries a visible link back to this repository. That is a licence obligation, not a courtesy.