mechanical-compiler/docs/DIVERGENCES.md

# DIVERGENCES.md

**Requirements that stand and are not met.**

| | |
|---|---|
| Tier | record |
| Audience | whoever is deciding what to fix next |
| Tense | past — each entry describes a moment |
| Status | 6 entries; 5 verified, 1 unverified |
| Defers to | `FAILURES.md` on what was observed; `STAGING-STATE.md` on host facts |
| Opened | 2026-09-12, from the documentation audit against `cdde394` |

---

## 0. What this document is, and how it differs from `FAILURES.md`

`FAILURES.md` records **something that went wrong**: an action was taken, it did
not work, and the entry says why.

This document records **something that is wrong now**: a requirement was
written, it stands, and the thing it governs does not comply. Nothing failed.
Nobody was surprised. The divergence was simply never written down, because
there was no notation for it.

That absence is the reason this file exists. `ENVIRONMENT.md` carries six markers
for a requirement's strength and provenance — **REQ**, **PREF**, **PROVEN**,
**ASSUMED**, **DEFERRED**, **INSTANCE** — and none meaning *this requirement is
not currently met*. Every entry below was visible in the documents for weeks and
recorded in none of them.

### The rule these entries follow

A requirement is never made true by lowering it to match what was built. The
requirement stays where it is, the divergence is recorded against it, and the
correction is owed by the thing, not by the document.

### Form

Append-only. Never edit an entry except to add a `Resolution` line. Each entry
carries:

- **Requirement** — what is required, and the document and section stating it
- **Actual** — what is true at the stated commit
- **Evidence** — how that was established, and how far it was checked
- **Consequence** — what it costs. An entry with no consequence is either not
  understood or not worth recording
- **Owed by** — code, configuration, host, or a decision

Ids are assigned when an entry is recorded, not by severity. The index in §7
carries priority.

---

## 1. DIV-001 — AGPL section 13 is not satisfied on a live public deployment

**Requirement.** Root `README.md`: section 13 obliges an offer of source to
users interacting with the software over a network, so any deployed web tier
carries a visible link back to this repository. The document calls this *a
licence obligation, not a courtesy*.

**Actual.** At `cdde394` the served page carries no such link.

**Evidence.** `src/mechcomp/web/app.py` read in full. The page is the single
`PAGE` constant. Its `<header>` holds the title and one line of description. The
document contains no anchor element except the one created in JavaScript at
download time to save the STL blob. `do_GET` serves `/`, `/api/build` and
`/m/stl`, and 404s everything else — there is no `/source` route. The composer
became publicly reachable at `https://dev.mechcomp.kane-il.us` on 2026-09-11
(`1fdb115`, `WORK-ORDER-004`).

**Consequence.** The obligation the front door states in its own words is unmet,
on a public name, and has been since 11 SEP. This is the only entry in this
register whose consequence falls outside the project.

It is also the only one where the **document is right and the code does not
comply**. Every other entry is a requirement the code declined to follow for
reasons that may be sound; this one has no such reading.

**Owed by.** Code. A visible link in `PAGE`'s header, and nothing else.

**Priority: first.** Smallest remedy in the register, largest exposure.

---

## 2. DIV-002 — the specified service architecture was never built

**Requirement.** `ENVIRONMENT.md` §9, marked **REQ**: two units split along a
control-plane / execution-plane boundary.

- `mechcomp.service` — FastAPI/uvicorn; serves the catalogue, accepts jobs,
  returns cached artifacts, and **never runs geometry**
- `mechcomp-worker.service` — consumes the queue, runs generators, writes
  artifacts

§9 further REQs a SQLite-backed in-process job queue. §15 gate 3 requires both
units active. §1.1 calls the control-plane / execution-plane separation a
requirement *regardless of distribution*.

**Actual.** `web/app.py` is a standard-library HTTP server that builds geometry
synchronously in the request thread. `src/mechcomp/worker/` is a 36-byte stub.
There is no queue and no database, and nothing has ever written to
`MECHCOMP_DATA_DIR`.

**Evidence.** `app.py` read in full at `cdde394`. Its imports are `json`, `os`,
`traceback`, `http.server`, `typing`, `urllib.parse` and `mechcomp.svg`. It runs
a `ThreadingHTTPServer`; `do_GET` calls `build_payload` -> `build(...)` inline.
Its own docstring states the constraint deliberately: *standard library only —
`http.server`. No framework, no build step, no new dependency.*

`requirements-base.txt` read: it does declare `fastapi`, `uvicorn`, `pydantic`,
`sqlalchemy` and `jinja2`, matching `ENVIRONMENT.md` §8.3 exactly. Those five are
not imported by the composer. **Not checked across the rest of `src/`** — only
`app.py` was read.

**Consequence.** Geometry runs in the request path on a world-reachable service
with no authentication. A long build occupies a request thread; the ceiling at
`MECHCOMP_MAX_EXPORT_MM` bounds the response size but not the computation, and
`/api/build` has the same exposure with no ceiling at all. The separation §1.1
requires is the mitigation, and it does not exist.

Five declared dependencies are installed on every instance and appear unused.

**Owed by.** A decision before any code. Either the architecture is built, or §9
is formally superseded by a written decision — not edited away.

---

## 3. DIV-003 — the instance is publicly reachable against three REQs

**Requirement.** `ENVIRONMENT.md` §1.3: staging is not publicly reachable and
does not use the public FQDN, *so the promotion path is exercised rather than
assumed*. §5.2, marked **REQ** for non-production instances: no public DNS
record, and no publicly-trusted certificate — because it consumes rate limit
against a name production needs clean, and puts a development host on the
internet.

**Actual.** `dev.mechcomp.kane-il.us` has public `A` and `AAAA` records and
terminates a Let's Encrypt certificate on `wg-pk`, expiring 2026-12-10.

**Evidence.** `WORK-ORDER-004`, closed 2026-09-11, §1 and §2. All eight
acceptance criteria met and recorded.

**Consequence.** Three **REQ**-marked statements are false of the running
instance, and §5.2's reasoning is a live claim nobody has rebutted: a rate limit
is being consumed against a name, and a non-production host is on the internet.

`WORK-ORDER-004` §3 records a related open item: the first renewal for this name
is due before 2026-12-10 and **no renewal has ever been observed to succeed**.
The other four certificates on `wg-pk` are managed identically, which is
reassuring but not evidence.

**Owed by.** A decision. Either §5.2 is superseded — the name may no longer be
"non-production", since `WORK-ORDER-004` §3 records that `dev` abbreviates
*Mechanical Compiler Developers*, the name is production, and it appears on
printed material — or the exposure is closed. The two documents currently
disagree about what kind of instance this is.

---

## 4. DIV-004 — the configuration contract declares eight keys nothing reads

**Requirement.** `ENVIRONMENT.md` §11 and `STAGING-STATE.md` §1 both carry the
`MECHCOMP_*` contract; `/etc/mechcomp/mechcomp.env` sets twelve keys.

**Actual.** The composer reads four: `MECHCOMP_BIND` and `MECHCOMP_PORT`
(`resolve_binding`), `MECHCOMP_MAX_EXPORT_MM` (`max_export_mm`), and
`MECHCOMP_BASE_URL` (`base_url`) — each checking the process environment before
the file.

Not read in `app.py`: `MECHCOMP_ENV`, `MECHCOMP_DATA_DIR`, `MECHCOMP_LOG_LEVEL`,
`MECHCOMP_DB_URL`, `MECHCOMP_WORKER_CONCURRENCY`, `MECHCOMP_CAD_BACKEND`,
`MECHCOMP_ARTIFACT_RETENTION_DAYS`, `MECHCOMP_SECRET_KEY`.

The omission also runs the other way: **`MECHCOMP_MAX_EXPORT_MM` is read by the
code and absent from `ENVIRONMENT.md` §11.** It was added at `cdde394`.

**Evidence.** `app.py` read in full. **Not checked across the rest of `src/`.**

**Consequence.** Most of the eight belong to the architecture DIV-002 records as
never built, so this is largely the same divergence seen from the configuration
side. It is recorded separately because it is the cheapest thing here to check
and the easiest to mistake for settled: a key present in an env file, a
specification and a state document looks live from all three.

`MECHCOMP_SECRET_KEY` deserves its own note. A secret that nothing reads is not
protecting anything, and its presence implies a session or signing mechanism
that does not exist.

**Owed by.** Documentation, once DIV-002 is decided. §11 should state which keys
are live and which are reserved for unbuilt components, and should add
`MECHCOMP_MAX_EXPORT_MM`.

---

## 5. DIV-005 — `requirements-cad.txt` declares a set that is not installed

**Requirement.** `requirements-cad.txt` declares a CAD dependency set and,
per `HANDOFF-2026-08-19.md` §3, says it is installed by default.

**Actual.** That same section records that `cadquery`, `OCP` and `build123d` are
**all absent from CT 100**, and notes the absence *will matter when STL and STEP
export starts*.

STL export started. It landed at `0545b79` on 2026-09-12.

**Evidence.** `HANDOFF-2026-08-19.md` §3, a session record, not a current
observation. **Unverified at `cdde394`.** `requirements-cad.txt` (347 b) and
`src/mechcomp/stl.py` (11,318 b) have not been read. **Do not close on this
evidence.**

**Consequence.** Unknown until verified. Note that the absence may be correct:
`ACCEPTANCE.md` E-8 requires the 2D path to import no CAD kernel, and asserts it
by test. If `stl.py` also needs none, the divergence is only that the manifest
describes an installation that does not happen — the same shape as DIV-002 and
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

**Requirement.** `PROCESS.md` §9a, marked **REQ**: run `ct-baseline.sh` after any
change to a container or to host firewall rules.

**Actual.** `STAGING-STATE.md` §3b records the last run as **2026-08-18**,
62 passed, 0 failed.

Since then: a DNAT rule was added to `nat PREROUTING` and persisted
(`WORK-ORDER-004` §1, 2026-09-11), and `mechcomp-placeholder.service` was
replaced by `mechcomp.service` in CT 100. Both are changes the REQ names.

**Evidence.** Documents only. **It is not known whether the check was run and
not recorded, or not run.** Either way the record is wrong: a conformance result
with no date after the changes it is supposed to cover is not evidence.

**Consequence.** The conformance claim is the basis for *the three containers are
configured identically*. That claim currently rests on a run that predates two
host changes by three and a half weeks.

`WORK-ORDER-004` §2 is partial mitigation — it verified `POSTROUTING` order
unchanged and confirmed mail still delivers after `iptables-save` rewrote the
ruleset. That is careful work and it is not the same as the baseline.

`FAILURES.md` F-037 is also relevant: `ct-baseline.sh` exits 0 with the F-037
condition present, so a passing run does not cover everything the standard is
believed to cover.

**Owed by.** One run, and a dated line in `STAGING-STATE.md` §3b.

---

## 7. Index

| Id | Divergence | Verified | Owed by | Status |
|---|---|---|---|---|
| DIV-001 | AGPL §13 link absent from a public deployment | yes, `app.py` | code | **open — do first** |
| 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 | yes, 2026-09-13 | — | **closed — recorded backwards** |
| DIV-006 | Conformance not re-run since host changed | documents only | one run | open |

**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.