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.
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# Acceptance oracle — strap-beam revision 8.0.0
|
|
|
|
123 cases. 113 accepted, 10 rejected. `sha256 ddd0f154…`
|
|
|
|
## What it is for
|
|
|
|
This is the acceptance criterion for any reimplementation of the generators. A
|
|
port is correct when it reproduces these values — not when it looks right, and
|
|
not when it renders something plausible.
|
|
|
|
## The rejected cases are part of the contract
|
|
|
|
Ten cases were rejected by the reference, each with a message naming the
|
|
parameter and the limit. **A port that accepts them is wrong**, however good its
|
|
numbers are elsewhere.
|
|
|
|
This is the part a naive reimplementation loses. Reproducing geometry is
|
|
straightforward; keeping the constraint that made the geometry trustworthy is
|
|
the actual work. `tests/test_oracle.py` asserts both directions.
|
|
|
|
## What the fields mean
|
|
|
|
| Key | Role |
|
|
|---|---|
|
|
| `MIN_WALL_ACTUAL_MM` | thinnest surviving material anywhere in the section |
|
|
| `SECTION_PARTS` | connected solids; must be 1 |
|
|
| `STRAP_CHANNELS` | separate strap slots; must equal the member count |
|
|
| `RING_*`, `FIN_*`, `AF_*`, `SPOKE_*` | solved placement values — these pin the solvers |
|
|
|
|
The first three are invariants. The solved values are what catch a port that
|
|
reaches the right shape by a different route, which will diverge later.
|
|
|
|
`tolerance` in the document governs comparison: lengths to 1e-4 mm, areas to
|
|
1e-3 mm², counts exact.
|
|
|
|
## The hash
|
|
|
|
`fixtures_sha256` covers the document **without that field**, serialised with
|
|
`indent=2` and `sort_keys=True`. Hashing the file will not reproduce it.
|
|
|
|
```bash
|
|
python3 make_fixtures.py --verify
|
|
```
|
|
|
|
That needs nothing but Python and should pass anywhere, any time.
|
|
|
|
## Regenerating
|
|
|
|
Only inside the pinned toolchain, never on a host whose OpenSCAD merely looks
|
|
similar:
|
|
|
|
```bash
|
|
./tools/reference-toolchain/verify.sh --full
|
|
```
|
|
|
|
The `frozen` date changes on every regeneration, so a one-line diff there is
|
|
expected. **Any other difference means the toolchain has drifted** — stop and
|
|
investigate. A drifting oracle is worse than no oracle.
|
|
|
|
## Coverage
|
|
|
|
Beyond the eleven default profiles: bundle counts 2 and 3; conditioned
|
|
intermediate stock at 13.4 mm and steel strap at 0.79 mm on every profile;
|
|
asymmetric walls as a chirality regression; parameter sweeps across corner
|
|
radius, corner web, leg angle, fin projection, fillet radius, bore size,
|
|
rotation, junction webs, triangle shape and rectangle aspect; and four
|
|
cross-profile isolation cases proving one profile's parameters cannot affect
|
|
another's.
|