TheRON/mechanical-compiler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

STAGING-STATE: reconcile against the host, and close DIV-005 as recorded backwards

Browse Source 
DIV-005 is withdrawn. It claimed requirements-cad.txt declared a CAD dependency set that was not installed. Verified in CT 100 today: cadquery and OCP both import from the venv. build123d does not, and correctly so - requirements-cad.txt names it as a viable alternative on the same OCCT kernel, not as an installed package. The file declares one requirement, cadquery greater-or-equal 2.4, and it is satisfied. The manifest and the container agree.

The false statement was in HANDOFF section 5, which said no CAD kernel is installed and that cadquery, OCP and build123d are all absent. True when written on 19 AUG, carried forward by hand for three weeks. STAGING-STATE section 5 recorded cadquery 2.8.0 in the venv for the same period. Two documents, each stating it as fact, disagreeing, and neither noticing.

The entry was recorded backwards: it named the manifest as diverging from the container when the container matched the manifest and a third document was wrong about both. Its evidence was a session record rather than an observation, which is why it carried do-not-close, and that marking is the only reason this was checked instead of acted on. The index note is corrected from three-of-six to two-of-six.

A roadmap item was deprioritised on the same false premise. HANDOFF section 4 listed STEP export as needing a CAD kernel that was not installed. It is installed.

STAGING-STATE section 5 opened with a transcribed repository block: HEAD at the seed commit c7e32d8, tests 3 passed and 236 skipped, and absent the Shapely port itself. All three were true on 18 AUG and none after 20 AUG, while the checklist directly below was kept current. Facts three weeks apart in one section, the maintained half lending credibility to the stale half. Removed rather than corrected. One line in it was still accurate - the venv cadquery 2.8.0 - and it was the only correct statement about the CAD kernel in the repository when it was deleted.

Section 3a said Kane Fabric is where SASE, HOA Diagnostics, the Mechanical Compiler and other SASE-consuming projects are implemented. Nothing here is implemented on Kane Fabric. Each project has its own FQDN and container and they share the bridge, the hub and the proxy. SASE was used and never defined anywhere in this repository. Section 3a also said no interface between the two projects exists and none is assumed; IDENTITY-CONTRACT.md specifies one.

Section 4 gave AllowedIPs on the hub peer entry for srv-b as 10.110.0.0/22, four paragraphs after correctly giving it as 10.110.0.12/32. The 22 is srv-b own AllowedIPs for the hub, recorded in section 1. The two ends of one tunnel were conflated, in the paragraph describing the security boundary. WORK-ORDER-004 section 0 settles it: all twenty peers carry a 32.

Also: the toolchain image box is ticked, verified present in CT 100. The baseline result is marked overdue against DIV-006. The Shapely port gates nothing. HANDOFF rewrap owed from 61b8f1e is applied.

Read-only verification was run before writing, per PROCESS section 2. Had it not been, this commit would have deleted the one true CAD statement and left the false one standing. Suite 643 passed, oracle intact. Documentation only.
This commit is contained in:
TheRON
2026-09-14 04:14:18 -05:00
parent 61b8f1eb4c
commit bc291822e1
3 changed files with 107 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DIVERGENCES.md
+30 -5
View File
@@ -217,6 +217,26 @@ DIV-004, and the third instance of a manifest describing an unbuilt architecture
**Owed by.** Two cheap reads before anything else.
**Resolution 2026-09-13 — NOT A DIVERGENCE. Closed.**
Verified in CT 100: `cadquery` and `OCP` both import from
`/var/www/mechcomp/venv`. `build123d` does not, and correctly so —
`requirements-cad.txt` names it as a viable alternative on the same OCCT kernel,
not as an installed package. That file declares exactly one requirement,
`cadquery>=2.4`, and it is satisfied. The manifest and the container agree.
The false statement was in `HANDOFF.md` §5: *no CAD kernel is installed in
CT 100; `cadquery`, `OCP` and `build123d` are all absent.* True when written on
19 AUG, carried forward by hand for three weeks, and corrected in the same
commit as this line. `STAGING-STATE.md` §5 had recorded `cadquery 2.8.0` in the
venv throughout.
**This entry was recorded backwards.** It named the manifest as diverging from
the container, when the container matched the manifest and a third document
disagreed with both. Its evidence was a session record rather than an
observation — which is why it carried *do not close*, and that marking is the
only reason this was checked rather than acted on.
---
## 6. DIV-006 — conformance has not been re-run since the host changed
@@ -259,10 +279,15 @@ believed to cover.
| DIV-002 | Specified service architecture never built | yes, `app.py` | a decision | open |
| DIV-003 | Instance public against three REQs | yes, `WORK-ORDER-004` | a decision | open |
| DIV-004 | Eight declared config keys unread | yes, `app.py` | documentation | open, blocked on DIV-002 |
| DIV-005 | `requirements-cad.txt` vs CT 100 | **no** | verification first | open — **do not close** |
| DIV-005 | `requirements-cad.txt` vs CT 100 | yes, 2026-09-13 | — | **closed — recorded backwards** |
| DIV-006 | Conformance not re-run since host changed | documents only | one run | open |
**Three of six — DIV-002, DIV-004 and DIV-005 — are the same shape:** a manifest
or specification describing an architecture that was not built, with nothing
recording the difference. That pattern is the reason this file exists, and it is
worth watching for in anything written next.
**Two of six — DIV-002 and DIV-004 — are the same shape:** a manifest or
specification describing an architecture that was not built, with nothing
recording the difference. That pattern is the reason this file exists.
DIV-005 looked like a third and was not. The manifest was honest, the container
matched it, and a third document was wrong about both. The pattern is real, and
matching a new observation to it without checking is how that entry came to be
written backwards — which is worth watching for in anything written next at
least as much as the pattern itself.
docs/HANDOFF.md
+26 -10
View File
@@ -170,11 +170,12 @@ internet → WireGuard → `srv-b` → containers. Containers cannot reach the h
LAN and cannot send mail.
`ct-baseline.sh` is read-only, runs any time, exits non-zero on divergence.
Installed at `/usr/local/sbin/`. **Last run 2026-08-18: 62 passed, 0 failed —
which predates the DNAT rule and the placeholder service replacement, both of
which `PROCESS.md` §9a names as requiring a run. Overdue. See DIV-006.** **A property it
does not check is not part of the standard** — that is what makes conformance
terminate rather than recur.
Installed at `/usr/local/sbin/`. **Last run 2026-08-18: 62 passed, 0 failed.**
That predates the DNAT rule and the placeholder service replacement, both of
which `PROCESS.md` §9a names as requiring a run, so it is overdue — see DIV-006.
**A property it does not check is not part of the standard** — that is what
makes conformance terminate rather than recur.
**Settled decisions. Do not reopen any of these:**
@@ -350,8 +351,10 @@ Roadmap items — read `ROADMAP.md` before starting any:
persist anything or show a bill of materials. `payload["defaults"]` is sent to
the browser and nothing reads it — dead weight, and it is what made a
verification grep lie on 11 SEP.
- STEP export. Needs a CAD kernel and none is installed in CT 100 (§5).
STL needs none — a member is prismatic by definition. See §5.
- STEP export. **The kernel is installed** — `cadquery` and `OCP` both import in
CT 100, verified 2026-09-13. This item sat low on the list partly because §5
said no kernel was present; it is closer than that implied. STL needs none —
a member is prismatic by definition. See §5.
- `mechcomp-worker.service`. `src/mechcomp/worker/` is still a 36-byte stub and
nothing needs a worker yet.
- Nodes (non-prismatic) and panels (sheet). No representation exists for either.
@@ -439,9 +442,22 @@ Shapely 2.1.2 on GEOS 3.13.1 — keep these in step, boolean results on
near-degenerate geometry can shift between GEOS releases. numpy 2.4.6. Shapely is
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.
**A CAD kernel is installed in CT 100.** `cadquery` and `OCP` both import from
the venv — verified 2026-09-13 by `importlib.util.find_spec` under
`/var/www/mechcomp/venv/bin/python`. `build123d` does not, and correctly so:
`requirements-cad.txt` names it as a viable alternative on the same OCCT kernel,
not as an installed package. The file declares one requirement, `cadquery>=2.4`,
and it is satisfied.
An earlier version of this paragraph said all three were absent. That was true
when written on 19 AUG and was carried forward by hand for three weeks, while
`STAGING-STATE.md` §5 recorded `cadquery 2.8.0` in the venv for the same period.
Two documents, each stating it as fact, disagreeing. See DIV-005.
**The 2D path must still import no CAD kernel**, and that is asserted by test —
`ACCEPTANCE.md` E-8. Separability is enforced by the suite, not by the kernel
being absent, and `requirements-cad.txt` says so itself: the suite must pass
with that file absent.
**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
docs/STAGING-STATE.md
+51 -22
View File
@@ -4,7 +4,7 @@ Live state of the Mechanical Compiler staging instance on `srv-b`.
| | |
|---|---|
| Updated | 2026-09-11, after the composer was published at `dev.mechcomp.kane-il.us` |
| Updated | 2026-09-13, after the documentation audit |
| Instance | Staging / development |
| Specification | `ENVIRONMENT.md` revision 5 |
| Failure log | `FAILURES.md` |
@@ -376,6 +376,13 @@ result 62 passed, 0 failed, 3 informational
scope srv-b, CT 100, CT 101, CT 102
```
**Overdue — see DIV-006.** `PROCESS.md` §9a requires a run after any change to a
container or to host firewall rules. Since that run a DNAT rule was added to
`nat PREROUTING` and persisted, and `mechcomp-placeholder.service` was replaced
by `mechcomp.service` in CT 100. Either the check was run and not recorded, or
it was not run. A conformance result with no date after the changes it covers is
not evidence.
**A property not checked by that script is not part of the standard.** That is
what makes it terminate. Divergence used to be discovered by asking, one
property at a time, whenever something behaved oddly — which never finishes,
@@ -422,9 +429,15 @@ exiting 0 — and it becomes part of restore verification.
## 3a. Parallel project on this host
**Kane Fabric** is a separate project sharing `srv-b`. It is where SASE, HOA
**Kane Fabric** is a separate project sharing `srv-b`. Each project has its own
FQDN and its own container. They share the service bridge, the WireGuard hub and
the proxy — that is the whole of the relationship.
An earlier version of this paragraph said Kane Fabric was where SASE, HOA
Diagnostics, the Mechanical Compiler and other SASE-consuming projects are
implemented.
implemented. That is not the arrangement: nothing here is implemented on Kane
Fabric. `SASE` was also used without being defined anywhere in this repository.
Corrected 2026-09-13 on the operator's statement of the topology.
| | |
|---|---|
@@ -445,7 +458,10 @@ send mail, that will present as a Postfix failure with a non-obvious cause.
repurposes the other's containers. Any integration is through an explicit
contract, not through co-location on `srv-b`.
No interface between the two projects exists today, and none is assumed.
**That is no longer true.** `IDENTITY-CONTRACT.md` specifies the identity half
of such an interface and `CONSUMER_INTERFACE_GATES.md` records gates against it.
Neither is implemented, so nothing crosses between the two projects today — but
an interface is specified, and it is no longer unassumed.
---
@@ -517,30 +533,41 @@ portless bridge with LAN traffic dropped.
The `srv-b` half needs no change, verified 2026-09-11: `ip_forward=1`,
`FORWARD` policy `ACCEPT`, a direct route on `vmbr1`, and none of the three
`FORWARD` rules matches hub-initiated inbound traffic. The single gate is
`AllowedIPs` on the hub's peer entry for `srv-b`, currently `10.110.0.0/22` --
WireGuard drops by cryptokey routing before consulting any routing table, so a
route without that entry does nothing.
`AllowedIPs` on the hub's peer entry for `srv-b` -- WireGuard drops by cryptokey
routing before consulting any routing table, so a route without that entry does
nothing.
**Correction 2026-09-13: that entry is `10.110.0.12/32`**, as stated earlier in
this section and as all twenty peers are. An earlier version of this paragraph
gave it as `10.110.0.0/22`, which is `srv-b`'s own `AllowedIPs` *for the hub* --
section 1 records it. The two ends of one tunnel were conflated, in the
paragraph describing the security boundary, four paragraphs after the correct
value appears.
No DHCP anywhere. Two containers with fixed addresses on a portless bridge is the
entire address space.
---
## 5. Blocked on application code
## 5. Application code — delivered
Repository state:
The port is complete, the composer is live, and nothing here is blocked.
```
HEAD c7e32d8e0772d89d1117bab7ff08d61e5b2a497e
top level .gitignore LICENSE Makefile README.md docs/ fixtures/ legacy/
pyproject.toml requirements-*.txt src/ tests/ tools/ venv/
remote ssh://git@gitea.barternetwork.us:42022/TheRON/mechanical-compiler.git
deploy key srv-b-ct100, read/write
venv Python 3.11.2, shapely 2.1.2, cadquery 2.8.0, mechcomp editable
tests 3 passed, 236 skipped
oracle ddd0f154... verified in-container
absent the Shapely port itself
```
This section used to open with a transcribed repository state block: `HEAD` at
the seed commit `c7e32d8`, `tests 3 passed, 236 skipped`, and `absent the
Shapely port itself`. All three were true on 2026-08-18 and none was true after
2026-08-20 — while the checklist directly below them was kept current. Facts
three weeks apart sat in one section, and the maintained half lent its
credibility to the stale half.
**Removed rather than corrected.** `git rev-parse HEAD` reports the commit,
`make test` the suite, `venv/bin/pip list` the environment, `git remote -v` the
remote.
One line in that block was still accurate when it was deleted — the venv's
`cadquery 2.8.0` — and it was the only correct statement about the CAD kernel
anywhere in this repository at the time, `HANDOFF.md` §5 having said the
opposite since 19 AUG. See DIV-005.
None of the following can be honestly completed, and none may be fabricated by
provisioning:
@@ -556,7 +583,8 @@ provisioning:
see `deploy/README.md`
- [ ] `mechcomp-worker.service` — no worker exists yet; `src/mechcomp/worker/`
is still a stub
- [ ] Reference toolchain image `mechcomp/reference-toolchain:8.0.0`
- [x] ~~Reference toolchain image `mechcomp/reference-toolchain:8.0.0`~~ — present
in CT 100, image `1a9d9a6853fd`, verified 2026-09-13
- [ ] Fixture reproduction against `ddd0f154...`
- [ ] Application-runtime acceptance — partial. The composer serves, is
reachable through CT 101 internally and at
@@ -571,7 +599,8 @@ provisioning:
`install_dir`, so anything writing to `$HOME` writes into the working tree
(F-029).
The Shapely port gates all of the above.
The Shapely port completed 2026-08-20 and gates nothing. Items still unchecked
above are unchecked on their own merits.
---