civicus-build
c7e32d8e07
Reference implementation of the strap-beam generators at revision 8.0.0, kept so the acceptance oracle can be regenerated. Not a live target; the running application has no OpenSCAD dependency. The oracle holds 123 frozen cases, 113 accepted and 10 rejected, produced by OpenSCAD 2021.01 with BOSL2 at 92d697c2. The ten rejections are part of the contract: a port that accepts them is wrong. tests/test_oracle.py specifies the port API and was written before the port, so the interface follows from what must be verified rather than what is convenient to implement. Proven by adversarial stub: a build() that rejects everything passes all 10 rejection tests and fails all 226 acceptance tests.
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|