From 0f984ff8d808af1cd206b9012360e023ad19130b Mon Sep 17 00:00:00 2001 From: Mix Date: Wed, 14 Oct 2026 18:44:19 +0300 Subject: [PATCH] development: code relying on another component cites its source; stage 2c: the heuristics review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner, 2026-10-14: "нам нужно полное ревью кода на предмет всей этой эвристики. Её не должно там, где можно посмотреть код и ответить точно и однозначно", and "в коде таких наших блоков должно быть обоснование со ссылкой на код компонента". - development.md § Code that relies on another component's behaviour: the rule, with the form of the comment (component, the image's version, file, function; or a document's URL and section; or "measured on the stand, date" said as such), and fixtures saying whether they were seen or composed. - Audit stage 2c: the line "what was taken on trust" becomes the heuristics review - an inventory over the whole tree written down as docs/assumptions-2026-10-14.md, then each answered from the source of the version the image runs, the comment added, the code fixed where it contradicts. Plan still 66 lines. Co-Authored-By: Claude Opus 5.5 --- docs/audit-2026-10-12.md | 34 ++++++++++++++++++++-------------- docs/development.md | 24 ++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/audit-2026-10-12.md b/docs/audit-2026-10-12.md index 3a3aa73..04feb3b 100644 --- a/docs/audit-2026-10-12.md +++ b/docs/audit-2026-10-12.md @@ -873,20 +873,26 @@ those after it move up one patch number each. shared files of lines (`from-lines-passed.txt`, `from-lines-other.txt`) are kept: the second one's test becomes "never signed for {other}" rather than "refused". - **Opus** -- [ ] **What was taken on trust, read in Postfix's source** (owner, - 2026-10-14: "запиши себе правило не гадать, как работает код, если можно - посмотреть в его документацию или исходный код"; then "Есть ли ещё у нас - места, где мы угадывали?"). Postfix 3.7.11 - the image's version - read - for: (1) when qmgr expires a message against maximal_queue_lifetime - the - "+ maximal_backoff" margin of queued_over_lifetime is a guess; (2) whether - postlogd goes on writing to the renamed mail.log until the reload - the - rotation window the deferred tailer fix is about; (3) why an smtpd from - before a reload takes one more connection, and for how long - measured - (under 2 s), not understood; (4) the NOQUEUE reject line's fields - two - test fixtures carry a sasl_username= that Postfix does not write, one - of them presented as seen on the stand; they are corrected. What is read - goes into architecture.md with the file it is in; where it contradicts - the code, the code is fixed in this stage. - **Opus** +- [ ] **The heuristics review: every assumption about another component, + answered from its source** (owner, 2026-10-14: "нам нужно полное ревью + кода на предмет всей этой эвристики. Её не должно там, где можно + посмотреть код и ответить точно и однозначно" and "в коде таких наших + блоков должно быть обоснование со ссылкой на код компонента"; the rule is + in development.md § Code that relies on another component's behaviour). + First an inventory, over the whole tree (Go, build scripts, configs, + tests' fixtures, docs' claims): each place SelfPost relies on what + Postfix, OpenDKIM, Cyrus SASL, rspamd, supervisord, logrotate, Docker, + SQLite/modernc, go-milter or a browser does, with what is assumed and + what justifies it today (read, measured, nothing). It is written down as + `docs/assumptions-2026-10-14.md`. Then each is answered from the source + or documentation of the version the image runs, and the code gets the + comment that cites it; a measurement stays a measurement and says so; + where the source contradicts the code, the code is fixed in this stage. + Known before the inventory: qmgr's expiry against the queue lifetime (the + margin of queued_over_lifetime), postlogd after a rename (the rotation + window), the smtpd that outlives a reload (measured, not understood), the + NOQUEUE line's fields (two fixtures carry a sasl_username= Postfix does + not write, one presented as seen on the stand). - **Opus** - [ ] Docs and wording: help topic sender-check and guide § Who an application may send as (mockup first), security.md § Mail path, CHANGELOG. - **Sonnet** diff --git a/docs/development.md b/docs/development.md index 09337ae..6f4416d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -215,6 +215,30 @@ Plex [OFL.txt](../internal/web/view/static/OFL.txt) under `/usr/share/doc/selfpost/`. The panel serves the AGPL text at `/license` and the OFL text at `/static/OFL.txt`. +### Code that relies on another component's behaviour + +The owner's rule (2026-10-14): what another program does is read in its +documentation or its source - never guessed. SelfPost reads Postfix's log +lines and reply codes, feeds OpenDKIM's tables, parses `postqueue`, +`postconf`, `supervisorctl` and `db_dump` output, talks the milter protocol +through go-milter, relies on SQLite's locking, on logrotate's and Docker's +behaviour. Every block of code that does so carries a comment that says +what it relies on and where that is written, for the version the image runs +(the Debian bookworm package, not upstream's head): + +```go +// Postfix 3.7.11, src/smtpd/smtpd_check.c, check_sender_login(): +// the SASL login is compared with the sender map's owners by strcasecmp. +``` + +A document instead of source: its URL and section. Where neither answers the +question, the comment says so and what was measured instead - "measured on +the e2e stand, 2026-10-14: ..." - and a measurement is never written as if +it were read. A test fixture copied from a real log says where and when it +was seen; one composed by hand says that it was composed. The heuristics +review of 2026-10-14 (audit-2026-10-12, stage 2c) brought the code that +existed then up to this rule. + --- ## Building binaries and the image