docs: assemblies are out of scope by design, and the priority order

CIVICVS ruled on 11 SEP that the absence of an assembly layer is chosen, not unfinished. Positioning is field work. Parts made and shipped by different manufacturers have no knowledge of each other assembly tolerances, and interchangeable manufacture works because of that separation rather than in spite of it. Fit up is resolved on site against conditions no designer had. PRECISION.md section 7 now says so, and closes with read this as a boundary that was chosen, not a gap to be filled.

Section 10 corrected. Its lock is on this document subject, not on the software roadmap, and it was misread that way once. Section 7 holds two kinds of entry: limits that may be lifted by work, and boundaries that were chosen and should not be. Without that distinction section 7 reads as a to do list.

Section 7 also separates geometry interchange from machine instructions. An STL or STEP describes a shape; a toolpath describes what a machine should do. The first is in scope and planned, the second is not. The two sat one line apart with nothing saying they differ in kind.

HANDOFF section 5 corrected: STL export needs no CAD kernel. A member here is prismatic by definition, so an STL is two triangulated caps and a quad strip. Verified in CT 100 that shapely constrained_delaunay_triangles handles a polygon with a hole correctly, area exact and no triangle inside the hole. That second check is the one that matters, because a triangulator that fills bores produces an STL which looks right in a slicer and prints solid where the conduit goes. STEP still needs the kernel.

Priority order recorded with its reasoning so a successor can disagree with the argument rather than only the sequence. STL export first because it is the only item producing physical feedback. Then an authorship field in the design record, one field and a one way door. Then per member stock for the conduit core. Then persistence, which nothing has ever written despite MECHCOMP_DATA_DIR being declared since staging. Then ACL, last, because access control over nothing is machinery without a subject.

A node is not an assembly. It is another artifact with declared interfaces and stays in scope. What is out of scope is positioning artifacts relative to one another. The project obligation is therefore to make each artifact interchangeable, which is what the stock descriptor and the design record already exist for.
This commit is contained in:
2026-09-11 12:38:34 -05:00
parent 1fdb11542e
commit a7162bc1d5
2 changed files with 92 additions and 7 deletions
+58 -2
View File
@@ -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
+34 -5
View File
@@ -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