mechanical-compiler/docs/ENVIRONMENT.md

# ENVIRONMENT.md

Specification for a Mechanical Compiler instance.

| | |
|---|---|
| Revision | 5.4 (2026-09-13) |
| Supersedes | Revisions 1 through 4 |
| Basis | Revision 5.3, reconciled against the running instance during the documentation audit of 2026-09-13. Divergences recorded; no requirement lowered. |
| Scope | **Host-agnostic.** Applies to any instance. |
| Instance state | `STAGING-STATE.md`, and later `PRODUCTION-STATE.md` |
| Failure evidence | `FAILURES.md` |
| Project sequence | `ROADMAP.md` |
| Working method | `PROCESS.md` |

---

## 0. How to use this document

This describes what an instance must **be**. It does not describe what any
particular host currently **is** — that lives in the corresponding state file.

Revision 4 mixed the two, which is why it aged badly the moment a real host
disagreed with it. Everything specific to `srv-b` has been removed.

### Authority order

0. **`PROCESS.md`** — how work is done. Read before issuing any command.
1. **The instance state file** — factual, wins on any question of what is true.
2. **`FAILURES.md`** — evidence from contact with hosts. Read this *before*
   writing automation, not after.
3. **This document** — the specification, corrected whenever proven facts
   invalidate it.
4. **`ROADMAP.md`** — product sequence. Environment work never invents
   application code.

### Markers

| Marker | Meaning |
|---|---|
| **REQ** | Required. The work is blocked or wrong without it. |
| **PREF** | Preferred. Substitute freely, but record the substitution. |
| **PROVEN** | Established by a real build. Do not re-derive; see the cited failure. |
| **ASSUMED** | Decided without confirmation. Listed in §16. |
| **DEFERRED** | Deliberately postponed. Not a defect, not a gap. |
| **INSTANCE** | A value supplied per instance, not fixed here. |
| **DIVERGENCE** | The requirement stands and is **not currently met**. Cites its entry in `DIVERGENCES.md`. |

**DIVERGENCE is never a reason to lower a requirement.** A REQ that stops being
met does not become a PREF, and it is not rewritten to describe what was built.
It stands, the gap is recorded, and the correction is owed by the thing rather
than by this document. A specification that agrees with whatever exists
specifies nothing.

Added 2026-09-13. Its absence is why five unmet requirements in this document
went unrecorded for weeks — there was no notation to write them in, so nobody
wrote them. The six markers above could say how strong a requirement was and
where it came from, and none could say it was not being met.

### Provisioning method

**REQ — manual first.** One command group at a time. Failures are recorded
before they are corrected. The smallest corrective experiment is preferred over
the one that also fixes three adjacent worries.

Automation is **derived from a proven manual procedure**, never written ahead of
one. Revision 4 said the opposite. `FAILURES.md` is why it changed: three of
this document's assumptions were wrong in ways only a real host revealed, and
one of them (F-003) produced a container that booted, reported success, and had
four broken services.

---

## 1. Five decisions that shape everything below

### 1.1 The 2D path and the 3D path are separable

The catalogue's product is a 2D cross-section rendered to SVG. Shapely plus our
own code covers that completely. CadQuery/OCCT is needed only for STEP and mesh
export.

They stay separate — separate requirements files, separate code paths, and a CI
job running the suite with the CAD dependencies absent. Three reasons, none of
which is packaging politics:

1. Part II §16 requires the control-plane / execution-plane separation
   regardless of distribution.
2. A slow OCCT import must never land in the request path for a page that only
   draws a cross-section.
3. Test-suite speed — the difference between running 123 fixtures on every save
   and only before commit.

**CadQuery is a default-installed dependency.** Revision 1 restricted it as a
defence against YunoHost's "resource-hungry" criterion; that was overcalibrated.
The criterion reads "compared to their features" and is aimed at marginal apps.
The boundary stays; the apology is gone.

**Verified 2026-09-13** — `cadquery` and `OCP` both import in CT 100. This
document was correct; `HANDOFF.md` §5 had said the opposite for three weeks, and
DIV-005 was opened against this paragraph rather than against that one. Closed,
and recorded there as having been written backwards.

### 1.2 YunoHost and Docker are parallel targets, not sequential

YunoHost apps install natively — apt, venv, systemd, nginx — and the project
does not want Docker inside YunoHost. Neither blocks the other, and neither
should be built "in order to" reach the other.

### 1.3 Every instance mirrors production topology, not production exposure

An instance runs **two containers**: an application container that never
terminates TLS, and a reverse proxy that does. A single container serving
directly would never exercise the `X-Forwarded-Proto` path.

Staging is not publicly reachable and does not use the public FQDN. That forces
the promotion path to be exercised rather than assumed.

**DIVERGENCE (DIV-003)** — the `srv-b` instance has been publicly reachable at
`dev.mechcomp.kane-il.us` since 2026-09-11. The requirement stands and the
instance does not meet it. §5.2 carries the same divergence with its reasoning.

### 1.4 Directory layout mirrors YunoHost conventions

`install_dir`, `data_dir`, a dedicated system user, a port treated as data. The
eventual `manifest.toml` resource block then describes what already exists.

### 1.5 Configuration comes from the environment, never the filesystem

No path, port, URL or secret is hardcoded or discovered by convention. One env
file; the same variables become `ENV` in a Dockerfile and `ynh_add_config`
substitutions in a package.

The check: moving an instance to a different hostname is a one-variable change.

---

## 2. Host requirements

**REQ** — Proxmox VE 8.x, Debian 12 base.

**REQ** — Two bridges (§3). **REQ** — Directory storage for backups and
templates; LVM-thin or equivalent for container volumes.

**PREF** — At least 12 CPU threads and 24 GiB RAM if the instance is also a
development host. The geometry solvers are single-threaded, so single-thread
performance governs fixture regeneration while thread count governs test
parallelism. An older CPU without AVX is acceptable; all compiled wheels target
an SSE2 baseline.

**REQ** — Time zone and NTP configured; clock synchronised.

**INSTANCE** — Hostname, addressing, storage pool names, template path.

---

## 3. Network

### 3.1 Two bridges

**REQ** — A **management bridge** with a physical port, carrying the host's own
address. The host uses it for egress and administration.

**REQ** — A **service bridge with no physical port**, carrying the host at
`.1`. This is the only network the containers sit on.

A portless bridge needs no cable, no switch configuration and no spare NIC. It
exists so the containers cannot be reached from the physical network at all.

### 3.2 Containers have exactly one interface

**PROVEN (F-017)** — Each container has a single interface on the **service
bridge only**, with the host as gateway. No management-network interface.

Revision 4 gave each container an address on both bridges, on the unstated
assumption that a workstation on the physical LAN would browse the instance.
That assumption was wrong and put both containers on the operator's home
network.

**PROVEN (F-021)** — After any interface change, the guest's
`/etc/network/interfaces` must be inspected. `pct set --delete netN` removes the
LXC interface but leaves the stanza in the guest, and `ifup -a` then fails at
boot on a device that no longer exists. See §15 gate 1 for the assertion that
catches this.

### 3.3 Isolation is routing, not interfaces

**PROVEN (F-018)** — Removing an interface removes an address, not a route. With
forwarding enabled and a masquerade for internet access, containers reach the
physical LAN through the host, translated to its address.

**REQ** — These rules, in this order:

```
nat POSTROUTING
  -s <SVC_NET> -d <LAN_NET>          -j RETURN       # before any masquerade
  -s <SVC_NET>            -o <WG_IF> -j MASQUERADE
  -s <SVC_NET>            -o <MGMT>  -j MASQUERADE

filter FORWARD
  -s <SVC_NET> -d <WG_NET> -p tcp
     -m multiport --dports 25,465,587 -j DROP     # containers do not send mail
  -s <SVC_NET> -d <SVC_NET>          -j ACCEPT
  -s <SVC_NET> -d <LAN_NET>          -j DROP
```

**PROVEN (F-025)** — The SMTP rule is not optional where the host masquerades
containers onto a network carrying a mail relay. Without it the containers
inherit whatever relay authority the host's source address holds. The host's own
alerting is unaffected: it originates mail locally, so it takes OUTPUT and never
enters FORWARD. Prove that rather than assuming it.

**REQ** — Rule order is load-bearing. `RETURN` must precede both masquerades.
Rules must be persisted, and the persisted set verified to match the live set.

**REQ** — The isolation must be asserted **negatively**: the LAN gateway is
unreachable from both containers. Asserting that the interface is gone is not
sufficient — that is exactly the mistake F-018 records.

**Expected and correct:** containers *can* reach the host itself. A container
addressing its own gateway takes the INPUT path and never enters FORWARD. This
is required — the host is their router and their SSH entry point — and is not a
leak.

### 3.4 Names

**REQ** — Names resolve through `/etc/hosts` on the host and both containers.

**REQ — do not stand up an internal DNS server.** Two containers and one host do
not justify one, and it would create a second source of truth for names that
production will not share.

**REQ** — The service FQDN names **the proxy**, which has exactly one address.
Guest hostnames are separate entries.

```
<SERVICE_FQDN>   ->  <proxy service address>
<app hostname>   ->  <app service address>
<proxy hostname> ->  <proxy service address>
```

**PROVEN (F-020)** — This value tracked topology through three states before
settling. The reasoning matters more than the value.

### 3.5 No DHCP

**REQ** — Static addressing. Two containers on a portless bridge is the entire
address space; a DHCP server would add a daemon, a lease database and a failure
mode in exchange for nothing.

### 3.6 Firewall

**ASSUMED** — The Proxmox firewall may remain disabled where the service bridge
is portless and the application has no listener outside it. **REQ** — Production
must revisit this; see §15 gate 5.

---

## 4. Containers

### 4.1 Roles and features

| | Application | Proxy |
|---|---|---|
| Role | application, worker | reverse proxy, TLS |
| Unprivileged | yes | yes |
| Features | `nesting=1,keyctl=1` | `nesting=1` |

**PROVEN (F-003)** — **Every Debian 12 unprivileged container requires
`nesting=1`**, including one running nothing but nginx. Without it,
`systemd-logind`, `systemd-networkd`, `systemd-timedated` and
`systemd-networkd.socket` fail with `226/NAMESPACE`. Revision 4 said the proxy
needed no features.

`keyctl=1` is required only where Docker runs. Tested separately rather than
copied across; it is genuinely unnecessary on the proxy.

### 4.2 Sizing

**INSTANCE.** Sizing is a host capacity decision, not a specification value.

**REQ** — The application container's data volume is a **real mount point** with
`backup=0`. Backup of application data is a separate tier (§10), and including a
large data volume in a container snapshot is how a backup store fills.

**REQ** — Do not over-commit a thin pool. Thin-pool exhaustion is an ugly
failure mode.

**PROVEN (F-026)** — Every container that must survive a host restart carries
`onboot: 1`. This is not the default. It is also invisible to `pct reboot`,
which restarts a guest without exercising host-boot autostart at all — so a
container proven to survive `pct reboot` is **not** thereby proven to survive a
host reboot.

### 4.3 Base OS

**REQ** — Debian 12 bookworm, both containers. It matches YunoHost 12 stable and
ships Python 3.11, which has the most reliable OCP/CadQuery wheel coverage.

**REQ (F-005)** — `apt full-upgrade` immediately after first boot, before
anything else is installed. Templates are not current, and discovering a
52-package backlog midway through provisioning is avoidable.

**REQ (F-004)** — Locale must be **generated**, not merely configured. Install
`locales`, enable the locale, run `locale-gen`, then `update-locale`. Setting
`LANG` alone leaves the system with only `C` and `POSIX`, silently, until
something depends on collation.

**REQ** — Time zone matching the host.

---

## 5. Names and TLS

### 5.1 Three names, never conflated

| Name | Scope |
|---|---|
| Service FQDN | What users type. Differs per instance. |
| Infrastructure token | System user, paths, units, YunoHost app id. **Same everywhere.** |
| Project name | Documents, README, catalog entry |

YunoHost app ids accept lowercase alphanumerics and underscores only, so a
hyphenated FQDN cannot serve as the token.

### 5.2 Non-production instances

**REQ** — An internal service FQDN. **REQ** — No public DNS record and no
publicly-trusted certificate: it consumes rate limit against a name production
needs clean, and puts a development host on the internet.

**DIVERGENCE (DIV-003)** — all three are unmet on `srv-b` as of 2026-09-11.
Public `A` and `AAAA` records exist and a Let's Encrypt certificate terminates on
the hub. The reasoning above is a live claim nobody has rebutted, and half of it
is already visible: that certificate expires 2026-12-10 and **no renewal has
been observed to succeed for this name**.

Whether this instance is still *non-production* is itself unsettled.
`WORK-ORDER-004` §3 records that `dev` abbreviates *Mechanical Compiler
Developers*, that the name is production, and that it appears on printed
material. If that reading holds, §5.2 never applied to it and §5.3 does — which
would make this a misfiled instance rather than a violated requirement. That is
a decision, not a correction.

**PROVEN** — A locally generated CA is sufficient and is the fallback whenever a
site CA has no discoverable issuance path. The point of the TLS step is
exercising termination and header forwarding, not the trust chain. Replacing the
leaf later is two file copies and a reload.

**REQ** — The CA root is installed into the trust store of the host, both
containers, and any client used to browse the instance.

**REQ** — Record the leaf's expiry somewhere that gets read. Nothing renews a
hand-made certificate.

### 5.3 Production

| | Value |
|---|---|
| FQDN | `mechanical-compiler.manufacturing.kane-il.us` |
| Zone | Labels within `kane-il.us`. **Not delegated.** No new DS record. |
| Certificate | Let's Encrypt, **per-name, no wildcard** |
| Challenge | **ASSUMED** HTTP-01. Match existing practice if it is DNS-01; never run both. |

`manufacturing.kane-il.us` is a namespace, not a service. `kane-il.us` stays
reserved for cross-cutting infrastructure and must not acquire project records.

The leaf names the service, not the discipline, because the parent already
carries the discipline and the namespace must hold siblings:

```
mechanical-compiler.manufacturing.kane-il.us    this application
field-metrology.manufacturing.kane-il.us        Utility One, later
stock-processing.manufacturing.kane-il.us       Utility Two, later
```

---

## 6. Reverse proxy

**REQ** — nginx in the proxy container. Terminates TLS, proxies to the
application container's service address.

**REQ** — Debian's `default` site removed. Only the project vhost enabled.

**REQ** — `X-Forwarded-Proto` is mandatory. Getting this wrong is what broke
Hubzilla sessions.

**REQ** — `default_server` declared explicitly on both TLS listeners. With one
vhost the implicit default is correct today; the moment a second is added, which
block catches unmatched requests becomes a function of file ordering. This is
independent hardening and **does not close F-012**.

```nginx
server {
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    server_name <SERVICE_FQDN>;

    ssl_certificate     <cert>;
    ssl_certificate_key <key>;

    location / {
        proxy_pass         http://<APP_SVC_ADDR>:<PORT>;
        proxy_http_version 1.1;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        client_max_body_size 8m;
    }
}

server {
    listen 80;
    listen [::]:80;
    server_name <SERVICE_FQDN>;
    return 301 https://$host$request_uri;
}
```

**REQ** — This vhost differs between instances in exactly two places:
`server_name` and the certificate paths. Any further divergence means the
non-production instance has stopped testing production.

**PREF** — `proxy_read_timeout 300s`. Compile jobs are asynchronous, but a cold
synchronous render can take tens of seconds and the 60s default leaves no
headroom.

---

## 7. Users, directories, permissions

**REQ** — Dedicated system user, no login shell:

```
user:group   mechcomp:mechcomp
shell        /usr/sbin/nologin
home         <install_dir>
```

**REQ (F-016 context)** — The service user's home is the install directory, not
a nonexistent `/home/<user>`. Tooling run as that user writes to `$HOME`;
`ProtectHome=true` makes it moot at runtime but not during provisioning.

**REQ** — Layout, matching what a YunoHost package would provision:

| Path | Owner | Mode | YunoHost equivalent |
|---|---|---|---|
| `/var/www/mechcomp` | `mechcomp:mechcomp` | `0750` | `install_dir` |
| `/var/lib/mechcomp` | `mechcomp:mechcomp` | `0750` | `data_dir` |
| `/var/log/mechcomp` | `mechcomp:mechcomp` | `0750` | — |
| `/etc/mechcomp/mechcomp.env` | `root:mechcomp` | `0640` | `ynh_add_config` |

```
/var/lib/mechcomp/
├── db/           SQLite database
├── artifacts/    generated SVG, STL, STEP, manifests
├── fixtures/     frozen acceptance oracles, read-mostly
└── cache/        safe to delete at any time
```

The `cache/` guarantee matters: anything not reproducible from `db/` plus
`artifacts/` must not live there.

**REQ (F-007)** — **Never `chown -R` a mount point root.** `data_dir` is a
filesystem root containing `lost+found`, owned by `nobody:nogroup` at `0700`,
created by `mkfs` and not ours to manage. Enumerate the application directories
explicitly.

**REQ (F-008)** — All repository operations run as the owning service user. Do
not add a root `safe.directory` exception — it would mask every future instance
of the same mistake.

**REQ** — The admin account exists in both containers with an authorized key.
**REQ (F-014)** — If the admin is placed in the service group, that group must be
created explicitly in the proxy container, where no service user creates it as a
side effect.

---

## 8. Software

### 8.1 Application container

**REQ**

```
python3 python3-venv python3-dev
build-essential pkg-config
git curl ca-certificates
libgeos-dev
sqlite3
```

**REQ (F-015)** — The proxy container needs its own minimal toolset, at least
`curl` and `ca-certificates`. Do not assume packages installed in one container
exist in the other.

**REQ — do not install** `openscad`, `openscad-nightly`, or any Qt or X11
package. The running application never invokes OpenSCAD, and §8.2 confines it.

### 8.2 The pinned reference toolchain

**REQ** — One Docker image with the exact toolchain the fixture oracle was
frozen against, and nothing else:

```dockerfile
FROM debian:12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
        openscad git ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN git clone https://github.com/BelfrySCAD/BOSL2.git /BOSL2 \
    && git -C /BOSL2 checkout 92d697c2856de2fed93a33e858068589cefc2898
```

Tag `mechcomp/reference-toolchain:8.0.0`. Its only job is to run
`make_fixtures.py` and prove the oracle reproduces. The container has no
OpenSCAD, so its version cannot drift.

**Acceptance** — must reproduce exactly:

```
sha256 strap-beam-fixtures-8.0.0.json
  = ddd0f1548379205dd0c652ec07285b0dae331e52ff0a0437005dfc6cddcc2cb2
```

A drifting oracle is worse than no oracle.

### 8.3 Python

**REQ** — A virtualenv inside `install_dir`. Debian 12 enforces PEP 668; do not
use `--break-system-packages`.

**REQ** — `venv/` is in `.gitignore`. It is a legitimate artifact in
`install_dir` and simply should not be tracked.

**REQ** — Pinned, hash-checked dependencies in two files, both installed:

| File | Contents |
|---|---|
| `requirements-base.txt` | shapely, fastapi, uvicorn, pydantic, sqlalchemy, jinja2, pytest, pytest-xdist |
| `requirements-cad.txt` | cadquery / build123d |

**DIVERGENCE (DIV-002)** — `fastapi`, `uvicorn`, `pydantic`, `sqlalchemy` and
`jinja2` are installed on every instance and imported by nothing in the composer.
They describe the architecture §9 specifies and nobody built. The manifest is
not wrong about what it installs; it is a faithful description of an unbuilt
design.

CI runs the suite twice — with both, then with base alone — and the second run
must pass. That is the mechanism keeping §1.1 honest.

---

## 9. Services

**REQ** — Two units, split along the control-plane / execution-plane boundary:

| Unit | Role |
|---|---|
| `mechcomp.service` | FastAPI/uvicorn. Serves the catalogue, accepts jobs, returns cached artifacts. **Never runs geometry.** |
| `mechcomp-worker.service` | Consumes the queue, runs generators, writes artifacts. |

**DIVERGENCE (DIV-002)** — neither unit exists as specified. `mechcomp.service`
runs a standard-library `http.server` and builds geometry synchronously in the
request thread, so the control plane *does* run geometry.
`mechcomp-worker.service` does not exist; `src/mechcomp/worker/` is a 36-byte
stub.

The requirement stands. §1.1 reason 1 calls this separation a requirement
**regardless of distribution**, and reason 2 gives its purpose: a slow import
must never land in the request path for a page that only draws a cross-section.
Geometry itself now does, on a world-reachable service with no authentication.

**REQ** — Both:

```ini
[Service]
User=mechcomp
Group=mechcomp
EnvironmentFile=/etc/mechcomp/mechcomp.env
WorkingDirectory=/var/www/mechcomp
Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mechcomp /var/log/mechcomp
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictSUIDSGID=true

[Install]
WantedBy=multi-user.target
```

**REQ** — Worker only: a `MemoryMax` bound, a `CPUQuota`, `TimeoutStopSec=30`.
A runaway geometry job must become a clean OOM-kill of one worker, not a dead
container.

**REQ** — Logging to journald. No application-managed rotation.

**REQ** — Job queue is SQLite-backed and in-process. No Redis, no Celery, no
RabbitMQ. A table with a status column and a claim query is correct at this
scale and adds no services to either packaging target.

**DIVERGENCE (DIV-002)** — no queue and no database exist. Nothing has ever
written to `MECHCOMP_DATA_DIR`.

**REQ (F-019)** — **Anything a proof depends on must be supervised.** This
includes temporary scaffolding. A placeholder backend used to prove the proxy
chain before the application exists is a systemd unit, obviously named and
obviously temporary — otherwise the proof expires at the next reboot and the
following session diagnoses a proxy fault that does not exist.

**REQ (F-011)** — Do not use `/tmp` for state shared across users.
`fs.protected_regular` makes that fail in ways that look like permission bugs.
Moot under `PrivateTmp=true`.

---

## 10. Backup

**DEFERRED — 2026-08-16, operator decision.** The backup strategy may change.
This section is retained as a design sketch and is **not authoritative**; no
acceptance gate depends on it until a strategy is chosen.

The sketch, for whoever revisits it:

| Tier | What | Retention |
|---|---|---|
| Routine | container snapshot, **rootfs only** | measured, not guessed |
| Application | tar stream of `db/`, `artifacts/`, `fixtures/`, and the env file | short, rolling |
| Gold | routine + application + manifest, on removable encrypted media | indefinite, offline |

Three constraints that survive any strategy change:

1. **Data volumes carry `backup=0`.** A container snapshot store on the root
   filesystem is how a Proxmox host fills up.
2. **Pull, never push.** The container has no access to any backup destination.
   The alternative hands a network-facing container write access to the last
   line of defence, and it avoids idmap ownership problems.
3. **Encrypt removable media.** The backup set includes the env file, which
   includes the secret key. Media that travels is media that gets lost.

**Standing recommendation regardless of strategy:** take one manual snapshot of
both containers before any significant change. It presupposes nothing and yields
the archive size that retention decisions need.

---

## 11. Configuration contract

**REQ** — One env file configures the application:

```bash
MECHCOMP_ENV=                      # staging | production
MECHCOMP_BIND=                     # single address — see below
MECHCOMP_PORT=
MECHCOMP_BASE_URL=
MECHCOMP_MAX_EXPORT_MM=            # bound on the exported sweep length
MECHCOMP_DATA_DIR=/var/lib/mechcomp
MECHCOMP_LOG_LEVEL=info
MECHCOMP_DB_URL=sqlite:////var/lib/mechcomp/db/mechcomp.sqlite3
MECHCOMP_WORKER_CONCURRENCY=
MECHCOMP_CAD_BACKEND=none          # none | cadquery
MECHCOMP_ARTIFACT_RETENTION_DAYS=30
MECHCOMP_SECRET_KEY=               # generated on first provision, never committed
```

**DIVERGENCE (DIV-004)** — the application reads four of these: `MECHCOMP_BIND`,
`MECHCOMP_PORT`, `MECHCOMP_MAX_EXPORT_MM` and `MECHCOMP_BASE_URL`. The other
eight are read by nothing. Most belong to the architecture DIV-002 records as
unbuilt, so this is largely the same divergence seen from the configuration
side.

`MECHCOMP_MAX_EXPORT_MM` was added to this list on 2026-09-13. It had been read
by the code since `cdde394` and declared nowhere — the divergence running the
other way, and the harder one to notice, because a missing key looks like
nothing at all.

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

**REQ** — `MECHCOMP_BIND` is a **single address**. Loopback is not additionally
bound.

Revision 4 said "the service-network address, plus `127.0.0.1`," which a scalar
cannot express. Resolved toward one address: `uvicorn` takes one `--host`, and
two sockets would mean either `0.0.0.0` — defeating the isolation — or
multi-socket setup for no benefit. Local checks inside the container can use the
service address. The scalar also generalises correctly: under YunoHost, where
nginx and the application share a host, the same variable takes `127.0.0.1`.

**REQ** — The application fails loudly at startup if a required variable is
missing, and never falls back to a compiled-in default path.

**REQ** — The secret is generated on first provision and never overwritten by a
re-run. It is never committed and never logged.

Promotion changes `MECHCOMP_ENV`, `MECHCOMP_BIND` and `MECHCOMP_BASE_URL`.
Nothing else.

---

## 12. Mail and monitoring

**REQ** — **SMTP 250 from a relay and an empty local queue prove handoff, not
delivery.** Alerting acceptance requires demonstrated end-to-end receipt, twice,
with full headers captured. This is the whole content of F-023: a message can be
accepted by every hop and still be rejected at the last one.

**REQ** — Diagnose relay problems with **RCPT-only probes, over every address
family, before and after any change**, with no message body sent. A `554`
before and a `250` after proves the change caused the fix rather than
coinciding with it.

**REQ (F-024)** — On a Proxmox host, inspect mail logs with
`journalctl -u postfix@-`. There is no `rsyslog` and no `/var/log/mail.log`.
Automation that greps a logfile path finds nothing silently, which is worse than
failing.

**PROVEN** — Disk monitoring must be configured **explicitly per device** where
the controller does not present members to automatic scanning. An active
`smartmontools.service` monitoring zero devices is not monitoring, and is easy
to mistake for success. Acceptance is a **delivered** test alert, not an active
unit.

Behind an HP Smart Array controller the working pattern is:

```
DEFAULT -a -m root -M exec /usr/share/smartmontools/smartd-runner
/dev/sda -d cciss,0
/dev/sda -d cciss,1
/dev/sda -d cciss,2
/dev/sda -d cciss,3
```

`-M test` proves the alert path — one message per monitored device — and must be
**reverted afterwards**. Left in place it produces an alert storm on every
restart, which trains everyone to ignore disk alerts. That is worse than no
monitoring.

**REQ (F-028)** — Query `smartmontools.service`, not `smartd.service`. The
latter is an alias and owns no journal; `journalctl -u smartd` returns nothing
on a host where monitoring is working perfectly.

**REQ** — Record each member's **serial number** at configuration time. That is
the only thing that maps a future alert to a physical drive in a caddy.

### 12.1 Downstream infrastructure is out of bounds

**REQ** — An instance may configure its own relay client. It may not alter the
mail infrastructure it relays through. Where a downstream change is genuinely
required, it is escalated with evidence, not made locally.

Two standing constraints apply to this estate:

| Host | Constraint |
|---|---|
| The final mailbox host | Runs YunoHost. Its mail configuration must not be altered — which is the reason a separate relay exists. |
| The relay MTA | Uses DANE. Its TLS and certificate configuration must not be broken. Client-trust changes such as `mynetworks` do not interact with DANE; certificate changes do. |

**REQ (F-025)** — Record what a trust change **grants**, not only what it
repairs. `permit_mynetworks` is destination-agnostic: authorising a client to
fix one rejected recipient authorises it for every destination. Where an
instance's containers have no reason to originate mail, block SMTP egress at the
instance boundary rather than relying on downstream policy to refuse it.

## 13. Instance parameters

**INSTANCE** — Every value below is supplied per instance and recorded in that
instance's state file, not here.

```
host                    hostname, storage pools, bridges, template
management network      host address, gateway
service network         network, host address, container addresses
wireguard               interface, address, allowed networks
containers              ids, hostnames, sizing
service FQDN            per instance
TLS                     CA and leaf source
admin                   username, authorized key
mail                    relay endpoint, root alias
```

**REQ** — These live in exactly one file per instance, sourced by every
provisioning step. No literals scattered through scripts. The file is not
committed; an example with empty values is.

---

## 14. Constraints the application code will follow

1. No hardcoded absolute paths. Everything derives from `MECHCOMP_DATA_DIR`.
2. No writes outside `MECHCOMP_DATA_DIR`. Enforced by `ProtectSystem=strict`.
3. No dependency on systemd from application code. Signal handling only.
4. The app listens on one TCP address, never `0.0.0.0`.
5. No OpenSCAD, Qt or X11 dependency in the running application.
6. The 3D backend is reached only through an interface in `src/mechcomp/cad/`.
   No other module imports CadQuery or OCP directly.
7. Schema migrations are explicit and forward-only.
8. Artifacts are addressed by content hash of **inputs** — parameter set plus
   generator revision — never by hash of output bytes. Mesh output is not
   reproducible across toolchain versions; input hashing keeps a qualification
   valid across an upgrade that did not change the geometry.
9. Every generated artifact carries the generator revision that produced it.
10. The test suite passes with `requirements-cad.txt` uninstalled.
11. AGPL-3.0 §13 requires network users be offered the source. The web tier
    carries a visible source link to the repository. A licence obligation.
    **DIVERGENCE (DIV-001) — not met.** The served page carries no such link,
    and the deployment has been public since 2026-09-11. This is the only unmet
    requirement in this document whose consequence falls outside the project,
    and the smallest to correct.

### 14.1 Test validity

**REQ (F-027)** — A test must be able to distinguish failure of the **tool**
from failure of the **thing under test**.

```bash
# WRONG — any failure of the wrapper reads as a pass
run_in_guest "$c" 'connect to X' && echo "reachable — WRONG" || echo "blocked — correct"

# RIGHT — establish that the test could have observed the positive case
if [ "$(guest_state "$c")" != "running" ]; then
    echo "CT $c NOT RUNNING — TEST INVALID"
elif run_in_guest "$c" 'connect to X'; then
    echo "reachable — WRONG"
else
    echo "blocked — correct"
fi
```

This applies to **every negative assertion** — "X is unreachable", "Y is
absent", "Z is refused". A test whose failure mode is indistinguishable from
success is worse than no test, because it manufactures confidence. In WO-003 the
wrong form reported a pass against containers that were not running.

---

## 14a. Conformance

**REQ** — An instance carries an executable **baseline check**: read-only,
runnable at any time, exiting non-zero when any container diverges from the
standard.

**REQ** — **A property not checked by it is not part of the standard.** This is
what makes conformance terminate. Without it, divergence is discovered one
property at a time whenever something behaves oddly, and the process never
finishes because nothing states what "the same" means. A property that must be
uniform belongs in the check, not in an operator's memory.

**REQ (F-031)** — The check must examine **the thing being standardised**. An
assertion derived from a related observation is not a check. Postfix
configuration on the host says what the host does; it says nothing about the
containers, and a standard asserted that way was wrong on two of three.

**REQ** — Each failure names the failure-log entry that established the
requirement, so the reason survives the person who found it.

**REQ (F-032)** — Host-level requirements belong to the host, not to whichever
project discovered them first. Where several projects share a host, the check
is host-level and covers every container regardless of owner. Two projects on
this host independently rediscovered the same two defects before this was done.

### Mail

**REQ** — **Containers do not originate mail.** Only the host does, and only its
own operational alerts. A container with a mail agent installed but SMTP egress
blocked is worse than either alone: it queues indefinitely and delivers nothing,
while appearing configured.

Application mail — participant notification and similar — is a separate design
problem with its own delivery and inbound requirements. It is not solved by
leaving a partially configured agent in a container.

---

## 15. Acceptance gates

**REQ** — Five independent gates. Revision 4 ran them as one list, which meant
an honest infrastructure build appeared to fail because application code did not
exist yet.

### Gate 1 — Infrastructure

Host and both containers `running` with **zero failed units**, asserted **after a
reboot**. Locale generated. Data volume is a real mount. Ownership correct with
`lost+found` untouched. Forbidden packages absent. Container egress works;
**the LAN gateway is unreachable from both containers**; the host remains
reachable from them; the management console remains reachable from the LAN. NAT
and FORWARD rules present live and persisted, in order. Proxy serves the service
FQDN over TLS without an insecure bypass, redirects HTTP, and
**`X-Forwarded-Proto: https` is observed at the backend**. Any supervised
scaffolding survives a reboot.

**PROVEN (F-021)** — the reboot is not optional. Connectivity can be perfect
while boot is degraded.

**PROVEN (F-026)** — it must be a **host** reboot, and every guest must return
automatically and report `running`. A guest reboot does not exercise autostart.

**PROVEN (F-027)** — every negative assertion in this gate must satisfy §14.1
before its result means anything.

### Gate 2 — Operational services

Mail delivered **end to end and received twice**, with full headers captured, an
empty queue and no deferred entries. Disk monitoring reporting a **non-zero
device count** and a delivered test alert. Container SMTP egress blocked where
the containers have no reason to originate mail. Not gated on gate 1.

### Gate 3 — Application runtime

Dependencies installed from committed manifests. Real service and worker units
active. Reference toolchain image reproduces `ddd0f154…`. Scaffolding removed.

**Status 2026-09-13 — the gate does not pass.** Dependencies: met. Toolchain
image: met, present in CT 100 and the oracle reproduced inside it on
2026-08-19. Scaffolding: met, `mechcomp-placeholder.service` retired 2026-09-11
with the unit file left on disk disabled as the rollback path.
**Worker unit: not met (DIV-002).**

### Gate 4 — Backup

Undefined pending a strategy decision.

**REQ** — **Conformance is a precondition, not a companion.** Backup work does
not begin until the baseline check (§14a) exits zero, and the check forms part
of restore verification.

A backup of an unverified configuration does not preserve a system; it
preserves a state of confusion, and a restore returns that state faithfully.
This was not hypothetical: a backup taken before 2026-08-18 would have restored
two containers that queue mail forever (F-031).

### Gate 5 — Production automation

Idempotent scripts derived from a proven manual procedure. Firewall posture
revisited. Publicly-trusted certificate issued and renewing.

---

## 16. Assumptions

| § | Assumption | If wrong |
|---|---|---|
| 3.6 | Firewall may stay disabled on a non-production instance | Enable per-container; production revisits regardless |
| 5.3 | Production uses HTTP-01 | Switch to DNS-01 if that is existing practice; never both |
| 11 | `MECHCOMP_BIND` is a single address | Revisit only if a real requirement for two sockets appears |
| 15 | Five gates are the right split | Merge or split further as evidence warrants |

---

## 17. Provenance disclosure

This project's documents, code and roadmap are LLM-generated under human
direction. Stated plainly here, in the README, and in any catalog submission.

**The YunoHost policy is a quality bar with a disclosure requirement, not a
ban.** The catalog rejects generated packages *that do not follow the
`example_ynh` template*, citing verbose code, hallucinated helpers and
non-standard directory architectures — then explicitly permits AI use where the
maintainer is transparent and can explain every line. The failure mode guarded
against is sprawl, not provenance.

**Package provenance is not upstream provenance.** The policy concerns the
`_ynh` repository — a few hundred lines of shell and one TOML file.

**Disclosure is right; headlining it is a tactical mistake.** If provenance
becomes the pitch, the project is judged on that axis rather than on whether it
makes distributed manufacturing capacity legible. State it in the README; keep
the pitch about manufacturing.

---

## 18. Packaging, when it comes

**DISCOVER** — Unknown territory, documented as it is walked: `manifest.toml` v2
with helpers 2.1, the `scripts/` set, `conf/` templates, `tests.toml`,
`package_check` levels.

The useful comparison for acceptable weight is `paperless-ngx_ynh` or
`fab-manager_ynh`, not a hello-world. The package is drafted against
`example_ynh` and reviewed by CIVICVS as his own work.

---

## 19. First application work item

**Complete 2026-08-20.** `sb-geom` is ported to Shapely and the suite is green
against the 123 frozen cases in `strap-beam-fixtures-8.0.0.json`. The ten
rejected cases are part of the contract: a port that accepts them is wrong, and
this one does not.

Retained rather than deleted because the framing outlived the task — the
rejected cases being part of the contract is the reason the oracle means
anything at all. What comes next is in `ROADMAP.md` §4, not here; an environment
specification should not carry a work queue.