TheRON
eb537768ef
The marker vocabulary had six entries - REQ, PREF, PROVEN, ASSUMED, DEFERRED, INSTANCE. They could say how strong a requirement was and where it came from. None could say it was not being met. That gap is why five unmet REQs in this document went unrecorded for weeks: there was no notation to write them in, so nobody wrote them.
DIVERGENCE is added as the seventh, with the rule attached. A REQ that stops being met does not become a PREF and is not rewritten to describe what was built. It stands, the gap is recorded, the correction is owed by the thing. A specification that agrees with whatever exists specifies nothing. No requirement in this revision was lowered.
DIV-001 at section 14 item 11: the AGPL section 13 source link is a numbered constraint the application code will follow, and it is not met on a public deployment. DIV-002 at section 9 twice and section 8.3: the FastAPI control plane, the worker unit and the SQLite queue do not exist, and five declared dependencies are imported by nothing. DIV-003 at sections 1.3 and 5.2: the instance is publicly reachable against three REQs. DIV-004 at section 11: eight declared keys are read by nothing.
Section 11 also gains MECHCOMP_MAX_EXPORT_MM, read by the code since cdde394 and declared nowhere. That is the divergence running the other way and the harder one to notice, because a missing key looks like nothing at all.
Section 5.2 records that the divergence may be a misfiling rather than a violation. WORK-ORDER-004 section 3 says dev abbreviates Mechanical Compiler Developers, that the name is production, and that it appears on printed material. If that reading holds, 5.2 never applied to this instance and 5.3 does. Written as a decision, not a correction.
Section 1.1 gets a note that it was right about CadQuery all along. DIV-005 was opened against this paragraph rather than against HANDOFF section 5, which had it backwards for three weeks.
Section 15 gate 3 now states its status: dependencies, toolchain image and scaffolding all met, worker unit not met, gate does not pass. Section 19 records the port complete since 20 AUG, retained because the rejected cases being part of the contract is why the oracle means anything.
STAGING-STATE specification reference updated from revision 5 to 5.4.
Applied by anchored patcher. The first attempt failed on one anchor - the env block comment column was 35, not 39 - and nothing was written, including the thirteen correct patches. Suite 643 passed, oracle intact. Documentation only.
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.