TheRON
6836ece4ff
The oracle records six significant figures, so the last digit of an area near 200 mm2 is worth 0.001 mm2. Every measured disagreement between port and reference is one, two or three units in that place. SECTION_AREA_MM2, VOLUME_MM3 and MASS_G are now bounded at 8 ULP of the expected value. Everything that positions material keeps the declared 1e-4 mm and remains exact in all 123 cases. Option 1 scope kept, derivation rejected on measurement. Max |dA|/P over the accepted set is 1.434e-05 mm, one seven-hundredth of the 0.01 mm criterion, so a perimeter x 0.01 bound would have run 1800 to 4500 times the worst real discrepancy and caught nothing. Perimeter also anti-correlates with the error. Suite 468 passed, 0 failed. The 30 expected failures are resolved, not suppressed. Mutation tested before landing: worst case uses 37.5 percent of its bound, 12 ULP offsets and 1e-4 relative scalings are caught in all 113 cases, 1e-6 and 1e-5 correctly are not. Adds docs/ACCEPTANCE.md as the specification. Adds F-036, the venv interpreter error, same class as F-035. Corrects the F-034 per-profile distribution to Three-Fin 10, Y 7, A Frame 6, Rectangle 5, T 1, Four-Fin 1, which sums to the stated 30.
159 lines
6.9 KiB
Markdown
159 lines
6.9 KiB
Markdown
# ACCEPTANCE.md
|
||
|
||
**What the acceptance suite asserts, and to what tolerance.**
|
||
|
||
This document exists because until now the answer lived in two places, neither of
|
||
them readable: a `tolerance` block inside a hashed JSON fixture, and one line of
|
||
`test_oracle.py`. A person asking "how close does the port have to be?" had to
|
||
read code to find out, and the reason for the numbers was nowhere.
|
||
|
||
Last updated 2026-08-22, closing F-034.
|
||
|
||
---
|
||
|
||
## 1. What is being compared
|
||
|
||
The port is measured against a frozen 123-case oracle generated by the OpenSCAD
|
||
reference at revision 8.0.0, under OpenSCAD 2021.01 with BOSL2 `92d697c2`. 113
|
||
cases the reference accepted, 10 it rejected.
|
||
|
||
The oracle does **not** record full-precision geometry. It records what
|
||
OpenSCAD's `echo` printed, which is C's `%g` at default precision — **six
|
||
significant figures**. That fact is load-bearing and most of this document
|
||
follows from it.
|
||
|
||
## 2. Two tolerance regimes
|
||
|
||
**Regime A — declared absolute.** The oracle's own `tolerance` block:
|
||
`lengths_mm = 1e-4`, `areas_mm2 = 1e-3`. Applies to every compared float except
|
||
the three keys named below.
|
||
|
||
**Regime B — six-significant-figure last place.** Applies to
|
||
`SECTION_AREA_MM2`, `VOLUME_MM3` and `MASS_G` only.
|
||
|
||
```
|
||
ulp(v) = 10 ** (floor(log10(|v|)) - 5) the value of the last digit
|
||
the reference actually wrote down
|
||
bound = 8 * ulp(expected)
|
||
```
|
||
|
||
Concretely, across the oracle's observed magnitudes:
|
||
|
||
| key | magnitude | last place | worst observed | bound |
|
||
|---|---|---|---|---|
|
||
| `SECTION_AREA_MM2` | 117 – 474 mm² | 0.001 | 0.003 (3 ULP) | 0.008 |
|
||
| `VOLUME_MM3` | 11,742 – 47,364 mm³ | 0.1 | 0.3 (3 ULP) | 0.8 |
|
||
| `MASS_G` | 14.6 – 58.7 g | 0.0001 | 0.0005 (5 ULP) | 0.0008 |
|
||
|
||
The bound scales with magnitude by construction, so it needs no revision if a
|
||
future case is an order of magnitude larger or smaller.
|
||
|
||
## 3. Expectation statements
|
||
|
||
These are what a passing suite means. Each is asserted by a test.
|
||
|
||
**E-1 — Every accepted case builds.** `build(family, profile, params)` returns a
|
||
`Result` for all 113. A raise is a failure, not a rejection.
|
||
|
||
**E-2 — Every rejected case is rejected.** All 10 raise `ProfileRejected`, and
|
||
the message is non-empty and names the parameter and the limit. Reproducing the
|
||
geometry while accepting a case the reference refused is not a passing port.
|
||
|
||
**E-3 — Counts are exact.** `SECTION_PARTS`, `STRAP_CHANNELS` and
|
||
`BUNDLE_COUNT` match with zero tolerance.
|
||
|
||
**E-4 — Everything that positions material is exact to regime A.**
|
||
`ENVELOPE_X_MM`, `ENVELOPE_Y_MM`, `MIN_WALL_ACTUAL_MM` and every profile extra
|
||
(`AF_*`, `FIN_*`, `SPOKE_*`, `RING_*`, `T_*`) agree within 1e-4 mm.
|
||
|
||
Measured: **exact in all 123 cases, no exceptions.** This is the strongest claim
|
||
the project makes and regime B must never be extended to cover any of it. If a
|
||
future change makes one of these keys need a looser bound, the change is wrong.
|
||
|
||
**E-5 — The three discretisation-limited keys agree to regime B.**
|
||
`SECTION_AREA_MM2`, `VOLUME_MM3` and `MASS_G` agree within 8 ULP of the oracle's
|
||
six-significant-figure record.
|
||
|
||
These three are one underlying quantity reported three times: volume is area ×
|
||
100 mm, mass is volume × 1.24 g/cm³ ÷ 1000. Verified across all 113 accepted
|
||
cases — `VOLUME/AREA` is exactly 100.0 with a maximum deviation of 2.8e-14, and
|
||
`MASS/VOLUME` is uniform to 1e-8. One bound therefore governs all three
|
||
honestly, rather than three unrelated policies.
|
||
|
||
**E-6 — The tolerance policy is not vacuous.** For every compared value, the
|
||
bound in force is at most 1e-4 relative. This is asserted directly, so a future
|
||
edit that loosens the comparison until it stops catching regressions fails a
|
||
test rather than passing silently.
|
||
|
||
**E-7 — The oracle is unmodified.** Its recorded hash covers the whole document
|
||
except the hash field. Editing the fixture to make a test pass breaks this by
|
||
design.
|
||
|
||
**E-8 — The 2D path imports no CAD kernel.** Building a cross-section must not
|
||
pull in `cadquery`, `OCP` or `build123d`.
|
||
|
||
**E-9 — The suite is green.** There are no expected failures. A red `make test`
|
||
means something is wrong.
|
||
|
||
## 4. Why the accuracy criterion does not source these numbers
|
||
|
||
The project's stated accuracy criterion is 0.01 mm over the entire set
|
||
(`PRECISION.md`). The obvious move — bound the area error by
|
||
`perimeter × 0.01 mm` — was measured on 20260822 and rejected.
|
||
|
||
Re-expressing every measured area discrepancy as the uniform boundary
|
||
displacement that would produce it gives `|dA| / P`, which is directly
|
||
comparable to the criterion:
|
||
|
||
```
|
||
median 0.000e+00 mm
|
||
p95 9.075e-06 mm
|
||
max 1.434e-05 mm one seven-hundredth of the criterion
|
||
```
|
||
|
||
A `perimeter × 0.01` bound would be 1.86 mm² at the smallest section and
|
||
4.54 mm² at the largest — between 1,800 and 4,500 times the worst real
|
||
discrepancy. It would catch nothing.
|
||
|
||
Perimeter is also the wrong normaliser. It anti-correlates with the error: the
|
||
largest discrepancy, 0.003 mm², occurs at P = 209.26 mm, and the smallest,
|
||
0.001 mm², at P = 454.41 mm. The error is driven by how many corners tip from 12
|
||
arc segments to 13 (F-034), which is a property of the arrangement, not of
|
||
boundary length. Dividing by perimeter widens the spread from a factor of 3 to a
|
||
factor of 6.5.
|
||
|
||
The real quantiser is the reference's own six-significant-figure `echo`. Every
|
||
discrepancy in the set is 0.001, 0.002 or 0.003 mm² — one, two or three units in
|
||
the last digit the reference ever recorded. Regime B is a bound on the mechanism
|
||
that actually produces the disagreement.
|
||
|
||
Physically, both boundaries sit within 0.0027 mm (4x) and 0.0043 mm (3x) of a
|
||
true arc and within ~0.4 µm of each other. Two orders inside the criterion. The
|
||
geometry was never in question; only the comparison was.
|
||
|
||
## 5. What would invalidate this
|
||
|
||
- **Any case exceeding 3 ULP.** The mechanism would have changed and the bound
|
||
would no longer describe it. Investigate before widening.
|
||
- **A case where `VOLUME/AREA` is not the model length**, or where
|
||
`MASS/VOLUME` is not the density ÷ 1000. E-5's single-bound justification
|
||
rests on that propagation.
|
||
- **Regime B extended to any key in E-4.** See E-4.
|
||
- **A surviving mutation.** The bound must be demonstrated to catch a
|
||
deliberately introduced regression. A comparison that no longer notices is
|
||
worse than the 30 known failures were, because it is silent.
|
||
|
||
## 6. What this document does not say
|
||
|
||
It says nothing about whether a member is structurally adequate, and nothing
|
||
about manufacturing tolerance. Passing acceptance means *this implementation
|
||
reproduces the reference*, not *this part is fit for use*. `PRECISION.md` §7
|
||
holds the list of what the compiler does not do, and it governs.
|
||
|
||
## 7. Correction to HANDOFF.md §7
|
||
|
||
The per-profile breakdown recorded there — Three-Fin 9, Y 7, A Frame 5,
|
||
Rectangle 5, T 1, Four-Fin 1 — sums to 28 against a stated total of 30.
|
||
Measured, the distribution is **Three-Fin 10, Y 7, A Frame 6, Rectangle 5, T 1,
|
||
Four-Fin 1 = 30**. Three-Fin and A Frame were each undercounted by one.
|