diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index e68358d..ad9de33 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,7 +6,7 @@ It is the only handoff you need to read. Dated handoffs in `docs/archive/` are historical and are not required reading — do not diff them against this to work out what is true. If something here is wrong, correct it here. -Last updated 2026-09-12, after the authorship field landed. +Last updated 2026-09-12, after the identity contract and the gate register landed. This line used to carry the commit hash of its own rewrite. It cannot: the hash is not known until the commit is made, so the value was always the @@ -28,6 +28,18 @@ This document is not the first thing to read, despite being the handoff. 4. This document — where the code stands. 5. `docs/ACCEPTANCE.md`, `docs/STOCK.md`, `docs/PRECISION.md` — the specifications the code is held to. +6. **`docs/IDENTITY-CONTRACT.md`** — how a visitor's identity arrives, and the + boundary that keeps membership out of this application. The only document + here written to be read by someone who does not work on this repository. +7. `docs/CONSUMER_INTERFACE_GATES.md` — cross-project concerns that are open, + with owners. Non-normative. **Read it before proposing any integration with + a membership or geography system**; several tempting ones are recorded there + as things to specifically not build yet. + +`deploy/` holds the systemd unit and the nginx vhost as they actually run, +imported verbatim on 12 SEP and checksum-proven equal to CT 100 and CT 101. The +repository is the single source of truth: read a container when you suspect it +has drifted, then fix the drift here rather than on the host. When documents disagree, `STAGING-STATE.md` wins on facts about the host and `FAILURES.md` wins on what was actually observed. This one is corrected. @@ -58,6 +70,18 @@ into the repository. `.cache/`, `.local/` and `.ssh/` are in `.gitignore` for that reason (F-029). Git identity is set `--local` for the same reason — `--global` would write into the tree. +**`pct exec` runs no shell.** A glob, a redirect, a pipe or an `&&` in a `pct +exec` command is expanded by the *host* shell, against the host's filesystem, +and whatever literal survives is handed to the container as an argument. Wrap +anything that needs a shell: + + pct exec 101 -- sh -c 'grep -n listen /etc/nginx/sites-enabled/*' + +Unwrapped, that glob expands on `srv-b` — where the path does not exist — so the +container receives a literal `*` and reports "No such file or directory", which +reads as a broken container and is not. Third of the same kind after F-035 and +F-036: the tool was invoked wrongly and the error described the wrong subject. + **`verify.sh` is mode `100644`.** Invoke it as `bash tools/reference-toolchain/verify.sh`, never `./tools/...`. @@ -169,7 +193,7 @@ terminate rather than recur. ### The port — COMPLETE -Gitea `main` at `48d5665` before this commit. CT 100 clean and matching. +Gitea `main` at `ee3fedf` before this commit. CT 100 clean and matching. **Suite: 547 passed, 0 failed.** The 30 expected failures are gone, resolved rather than suppressed, by the tolerance model in `docs/ACCEPTANCE.md`. A red @@ -261,12 +285,32 @@ so a successor can disagree with the argument rather than only the sequence. 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. + of saved designs. It is **no longer** the prerequisite for access control, + which has left this roadmap entirely — but it should be built knowing that a + saved design belongs to a person whose identity arrives from outside this + application (`IDENTITY-CONTRACT.md` §3). + + The filesystem is the first store, not a database. Design records are already + plain text, already content-addressed by `input_id`, and already readable by + someone with none of this software installed. A directory of them is a store + with perfect provenance and no schema to migrate. SQL earns its way in when + there is a query that walking files cannot answer — "every design by this + author since March" is that query, and it arrives with membership, not + before. +5. ~~**ACL.**~~ **Deleted, not deferred.** Authorisation lives upstream, at the + last proxy hop before this application, decided against a membership system + this repository knows nothing about. The compiler will not have a user table, + a login form, a session, or a group name in any form — including as a + configuration value, which is how that leak arrives by the side door. See + `IDENTITY-CONTRACT.md` §9. An item left the roadmap rather than moving down + it. + + The service is world-reachable and unauthenticated today, and `/m/` is not + yet gated, so STL export will ship open. An earlier version of this item + called that "acceptable for a development name". **It is not.** The name is + production, `dev` abbreviates *Mechanical Compiler Developers*, and it + appears on printed material. The posture is unchanged; the excuse is + withdrawn. Carried openly as open question 10 instead of justified. **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. diff --git a/docs/PROCESS.md b/docs/PROCESS.md index eff6669..0570305 100644 --- a/docs/PROCESS.md +++ b/docs/PROCESS.md @@ -351,6 +351,14 @@ it and delete the exception. ## 9. Instructions the operator can actually run +**REQ** — `pct exec` runs no shell. A glob, redirect, pipe or `&&` in a `pct +exec` command is expanded by the host shell against the host's filesystem, and +the container receives whatever literal survives. Wrap them: `pct exec 101 -- +sh -c '...'`. An unwrapped glob produces an error that describes the container +rather than the invocation, which is the same misdirection as F-035 and F-036 — +three instances now, all of them the tool being invoked wrongly and the message +naming the wrong subject. + This section exists because it has already gone wrong. **REQ** — One command group per message. Wait for output. diff --git a/docs/STAGING-STATE.md b/docs/STAGING-STATE.md index 8917edc..e823bb6 100644 --- a/docs/STAGING-STATE.md +++ b/docs/STAGING-STATE.md @@ -547,6 +547,13 @@ provisioning: - [x] ~~Dependency install from committed manifests~~ — done 2026-08-18 - [x] ~~`mechcomp.service`~~ — done 2026-09-11, `deploy/mechcomp.service` +- [x] ~~Deployment configuration under version control~~ — done + 2026-09-12. `deploy/mechcomp.service` and + `deploy/nginx/mechanical-compiler.conf`, imported verbatim and + checksum-proven equal to CT 100 and CT 101 at import. The unit had + been recorded as delivered at that path on 11 SEP while existing + only on the host. `mechcomp.env` is deliberately **not** committed — + 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` diff --git a/docs/WORK-ORDER-004-public-ingress.md b/docs/WORK-ORDER-004-public-ingress.md index 5e54235..a1986c5 100644 --- a/docs/WORK-ORDER-004-public-ingress.md +++ b/docs/WORK-ORDER-004-public-ingress.md @@ -113,8 +113,12 @@ precedes both masquerades. - **No acceptance criteria exist for the composer itself**, only for the path to it. A `200` says the chain works, not that the page is right. - **The service has no authentication.** It is world-reachable and computes - geometry for anyone who asks. Acceptable for a development name; it should be a - conscious decision before anything else is published this way. + geometry for anyone who asks. An earlier version of this bullet called that + acceptable for a development name. **It is not**: `dev` abbreviates + *Mechanical Compiler Developers*, the name is production, and it appears on + printed material. Corrected 12 SEP — the posture is unchanged and the + justification is withdrawn. `docs/IDENTITY-CONTRACT.md` specifies how it will + be gated and by whom. ---