diff --git a/docs/DIVERGENCES.md b/docs/DIVERGENCES.md index 5a17d87..a3cba1f 100644 --- a/docs/DIVERGENCES.md +++ b/docs/DIVERGENCES.md @@ -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. diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 3830d7e..42609f1 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -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 diff --git a/docs/STAGING-STATE.md b/docs/STAGING-STATE.md index e823bb6..65d7e66 100644 --- a/docs/STAGING-STATE.md +++ b/docs/STAGING-STATE.md @@ -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. ---