diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index c2ae8db..c7279ff 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -220,6 +220,38 @@ deliverable he wants. Two consequences: after export. `ROADMAP.md` §4 orders it third; that ordering predates this and should be read against it. +**Priority order, decided 11 SEP when CIVICVS delegated it.** The reasoning is +given so a successor can disagree with the argument rather than only the +sequence. + +1. **STL export.** No new dependency, no kernel, and it is the only item that + produces *physical* feedback. Everything so far is verified against a frozen + oracle; a printed coupon is the first test against reality, and the first + real measurement of whether `fit_clearance_mm` suits the operator's printer. + The composer already makes stock, fit and walls configurable, which was his + stated precondition for printing anything. +2. **An authorship field in the design record.** One field, and a one-way door. + Records created before it exists can never be attributed. Cheap now, + impossible retroactively — and a multi-user system needs the record to answer + *who* as well as *what*. +3. **Per-member stock — the conduit core.** What CIVICVS asked for on 22 AUG and + still cannot be done: `Geo` is global to a build, so every member is the same + rectangular strap by construction. Reaches into `join.py` and + `arrangements.py`; the first change that puts the oracle's own geometry at + risk rather than merely near it. +4. **Persistence.** `MECHCOMP_DATA_DIR=/var/lib/mechcomp` has been declared since + staging and nothing has ever written to it. Every design currently exists only + for the duration of one HTTP request. This is the prerequisite for a library + of saved designs *and* for access control. +5. **ACL.** Deliberately last. There is nothing to control until 4 exists — + access control over nothing is machinery without a subject. Note that the + service is world-reachable and unauthenticated today, which is acceptable for + a development name and should be a conscious decision before anything else is + published this way. + +**Assemblies are not on this list and should not be added.** See `PRECISION.md` +§7: positioning is field work, ruled out by design on 11 SEP. + Roadmap items — read `ROADMAP.md` before starting any: - Dihedral parameterisation. If two panels meet at 137°, none of the eleven @@ -317,8 +349,21 @@ in `requirements-base.txt`, the 2D path's own dependency set. **No CAD kernel is installed in CT 100.** `cadquery`, `OCP` and `build123d` are all absent, though `requirements-cad.txt` says it is installed by default. That -is the strictest environment for developing the 2D path and will matter when STL -and STEP export begins. +is the strictest environment for developing the 2D path. + +**STL export does not need one, and an earlier version of this section implied +it did.** A member here is prismatic by definition — a 2D section swept along a +straight axis — so an STL is two triangulated caps plus a quad strip down the +boundary. That is not a kernel problem. + +Verified in CT 100 on 11 SEP: `shapely.constrained_delaunay_triangles` is +present in Shapely 2.1.2 and triangulates a polygon **with a hole** correctly — +summed triangle area equals the polygon area exactly, and no triangle falls +inside the hole. The second check is the one that matters: a triangulator that +fills bores would produce an STL that looks right in a slicer and prints solid +where the conduit goes. + +STEP does need the kernel. `requirements-cad.txt` pins `cadquery>=2.4` for it. ### What is verified against the reference @@ -497,6 +542,17 @@ physical claims, never verdicts. Measure and attest; never adjudicate. Three artifact classes: **members** (prismatic, exist — the eleven profiles), **nodes** (non-prismatic, no representation yet), **panels** (sheet, none yet). +**A node is not an assembly.** It is another artifact — non-prismatic, carrying +several declared interfaces — and it stays inside scope. What is out of scope is +positioning artifacts relative to one another, which is field work and belongs +to whoever is holding them. `PRECISION.md` §7 states the ruling and the reason. + +The consequence is the project's actual obligation: **make each artifact +interchangeable.** Fully specified, independently reproducible, carrying its own +declared interfaces so the field can fit it to whatever it meets. The stock +descriptor and the design record exist for exactly that, and it is the standard +any new capability should be judged against. + **The output must eventually be sealed manifolds and printable STL.** The 2D section is where manifold validity is decided, not downstream in the CAD kernel — `is_region_simple` is already a build-blocking check, and a self-touching outline diff --git a/docs/PRECISION.md b/docs/PRECISION.md index f03c47e..b21dce9 100644 --- a/docs/PRECISION.md +++ b/docs/PRECISION.md @@ -225,10 +225,22 @@ of a millimetre. This section is as important as section 6 and should be read with equal weight. -**It has no assembly layer.** It describes the cross-section of *one* member. -Nothing positions multiple members in a shared coordinate frame. For a bridge, -each component would be modelled to the accuracy above — arranging them into a -structure does not exist here and belongs in separate software. +**It has no assembly layer — by design, not by omission.** It describes the +cross-section of *one* member. Nothing positions multiple members in a shared +coordinate frame, and nothing ever should. + +Positioning is field work. Parts made and shipped by different manufacturers +have no knowledge of each other's assembly tolerances; interchangeable +manufacture works *because* of that separation, not in spite of it. A bolt +supplier holds a thread specification, not a tolerance stack for the bridge the +bolt ends up in. Fit-up is resolved on site, against conditions no designer had. + +The compiler's obligation is therefore to make each member independently +reproducible and to state its interfaces plainly. How members meet belongs to +whoever is holding them. + +**Read this as a boundary that was chosen, not a gap to be filled.** A future +contributor proposing an assembly layer is proposing a different product. **It models one shape family.** Prismatic members: a two-dimensional cross-section swept along a straight axis. Not tapers, not curved axes, not @@ -258,7 +270,12 @@ criterion rather than 0.0001 mm. **It says nothing about surface finish, material properties, or joining.** Per section 0. -**It does not generate machine instructions.** No toolpaths, no G-code, no slicing. +**It does not generate machine instructions.** No toolpaths, no G-code, no +slicing. + +Geometry interchange is a different thing and is *not* excluded here. An STL or +a STEP file describes a shape; a toolpath describes what a machine should do. +Exporting the former is in scope and planned; producing the latter is not. --- @@ -276,6 +293,7 @@ section 0. with the square root of radius. - Accuracy does **not** degrade with object size. - **One member at a time. No assembly. No structural analysis. No toolpaths.** + The first three are chosen boundaries, not unfinished work — see section 7. --- @@ -313,6 +331,17 @@ reproducible with `make test`. **This document is scoped by section 0. Additions that widen the scope should be refused, not accommodated.** +**Section 0's lock is on this document's subject, not on the software's +roadmap.** It exists to stop this becoming a general precision guide whose +borrowed figures would look as authoritative as the measured ones. It is not a +freeze on what the compiler may one day do, and it was misread that way once. + +**Section 7 holds two kinds of entry, and they are not the same.** Some are +*limits* that may be lifted by work — untested ranges, absent export formats. +Others are *boundaries* that were chosen and should not be — the absence of an +assembly layer, of structural analysis, of toolpaths. Do not read section 7 as +a to-do list. Each entry says which kind it is. + If a reader needs casting tolerances, weld distortion, surface roughness or lithography, the answer is a different document — not another row in section 3's table. Every such row would look as authoritative as the measured ones while