novox/hq
18
0
Fork 0
Code Issues Pull Requests 2 Releases Wiki Activity

Mark design 60 proposed and tie each brother feature to the record that decides it

Browse Source 
The review found features stated as in force that rest on records still proposed
(ADR 0468, ADR 0474 and the scanning record to be reserved), and rules without
the test that checks them.
This commit is contained in:
jschoubben
2026-10-21 01:47:59 +02:00
parent b6e01318cf
commit 8d3a9011ac
2 changed files with 45 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/60-the-brother-module.md
+44 -24
View File
@@ -1,7 +1,7 @@
---
layer: to-be
status: in-progress
code: [mesh-catalog modules/brother]
status: proposed
code: [mesh-catalog]
updated: 2026-10-21
decisions:
- "ADR 0464"
@@ -18,11 +18,13 @@ document feeder into a PDF, keeps every scan in its own bucket and announces it
one call, reads the device's state and its admin pages, restarts it, and changes the settings on the admin pages
where a mistake cannot lock the operator out or open the device. Only the module's device process ever holds the
device's admin password or the bucket's key.**
(ADR 0464, ADR 0467; ADR 0468 and ADR 0474, both proposed.)
(ADR 0464 and ADR 0467 are in force. Proposed, and not in force: ADR 0468 for the device process, the bucket and
the parts; ADR NNNN for the feeder, multi-page and several-document scans and the one-call print; ADR 0474 for
reading every page, configuring, the refused pages and the restart.)
**Acceptance.** The operator, or an agent through the mesh MCP server, scans a document from the glass and finds it
cropped in the scan folder; scans five sheets from the feeder on both sides and finds one PDF of ten pages; prints
that PDF in one call; reads any admin page; changes a setting on an allowed page and is told the old and the new
that PDF from a file in one call; reads any admin page (ADR 0474, as proposed); changes a setting on an allowed page and is told the old and the new
value; and is refused, with the reason, when asking to change the admin password or the network settings.
## 1. The parts
@@ -60,18 +62,30 @@ the scanner's over eSCL, stay on the tool side.
The admin password is the operator's own, given once at the operator's desk and kept in the vault; the mesh never
generates or rotates it (ADR 0467 §4). The device process speaks HTTPS to the admin pages and trusts only the
certificates whose fingerprints are pinned in the module's config; any other certificate is refused in the
handshake, before a password is sent (ADR 0467 §3).
certificate whose SHA-256 fingerprint is pinned in the module's config; any other certificate is refused in the
handshake, before a password is sent (ADR 0467 §3). The module's pin tests check it: a certificate with another
fingerprint is refused and nothing is sent.
## 2. Scanning
What ADR 0464 decided is the glass, one page, one PDF page. ADR NNNN (proposed) widens it to the feeder, to several
documents on the glass and to documents of several scans; until it is accepted, only ADR 0464 holds.
- **The glass.** One page over the whole glass. The document lies on the lid, which is a white of its own, so the
module measures the lid where no document lies and cuts the document out of it with a small margin. When it finds
no document, or one that fills the glass, it keeps the whole page and says it did not crop (ADR 0464 §3).
- **Several documents.** Each scan is its own call and its own PDF; the operator lays the next document on the glass
and calls again.
- **The feeder.** The feeder scans whole sheets, one side or both, and every page of the job goes into one PDF, in
the order the scanner gave them. A feeder page is never cropped.
- **Several documents on the glass** (ADR NNNN, proposed). Documents lying apart on the glass are each cut out and
filed as a PDF of their own.
- **One document of several glass scans** (ADR NNNN, proposed). A caller starts a document, adds a glass scan to it
as often as it needs, and finishes it, and the pages become one PDF. A document left unfinished is filed whole
after 30 minutes, so no scan is lost.
- **The feeder** (ADR NNNN, proposed). The feeder scans whole sheets, one side or both, and every page of the run
goes into one PDF, in the order the scanner gave them: one object in the bucket and one announcement, with its
page count. A feeder page is never cropped. A run that is cut off before its end is an error, never a short PDF
said as success; a unit test checks it.
- **A long run** (ADR NNNN, proposed). A feeder run may take longer than a call through the mesh MCP server may
wait. Such a call answers that the scan started, with an id, and the caller reads its outcome by that id. A scan
that was announced is always filed.
- **The real resolution.** The module reads the resolution from the image it receives, never from what it asked: a
scanner may answer a request for 300 dpi with 200 dpi (ADR 0464 §2).
@@ -84,8 +98,9 @@ is the evidence.
## 3. Printing
A caller prints in one call: `printer.print` takes a kept scan by its key, or a document it has uploaded, with the
copies, the sides and the paper. The device process fetches the document from the bucket and sends it to the printer
A caller prints in one call: `printer.print` takes a kept scan by its key, a document it has uploaded, or a file
on the machine the tool runs on, which the verb uploads and prints in the same call (the file: ADR NNNN, proposed);
with the copies, the sides and the paper. The device process fetches the document from the bucket and sends it to the printer
in a format the printer itself lists as accepted, read before the job; a document in another format is refused with
the printer's list (ADR 0468 §5). A document larger than one bus message travels in parts, each under the bus's
limit, and a caller joins or sends the parts and checks the whole by its SHA-256 (ADR 0468 §3).
@@ -106,9 +121,10 @@ The other events are `brother.printer.restarted`, when the device answers again
**Reading.** `printer.settings` reads one admin page: the device process logs in, reads the page and logs out. It
answers the page's forms with each field's current value (a radio group's checked button, a checkbox's state, a
select's chosen option) and the values each field allows; the page's links and its hidden fields only on ask. A
password field's value is never given. Every page may be read, and the menu page's links are the map of the rest.
password field's value is never given. ADR 0467 §5 decides the read for the pages of the scan and restriction
settings; ADR 0474 (proposed) widens it to every page, and the menu page's links are the map of the rest.
**Configuring.** `printer.configure` takes one page and the fields to set on it, by name. The device process logs in
**Configuring** (ADR 0474, proposed). `printer.configure` takes one page and the fields to set on it, by name. The device process logs in
and reads the page as the printer serves it, with a fresh form token. It checks each named field: the field exists
in one form of the page, and its value is allowed for its type (one of a radio group's or a select's values, on or
off for a checkbox, a text within its maximum length). A password, hidden or file field cannot be set. When any
@@ -127,38 +143,42 @@ caller ──configure {page, set}──▶ tool side ──ask──▶ device
told to the operator: page, fields, who asked
```
**What may not be changed.** Some pages are refused, because a mistake on them locks the operator out or opens the
**What may not be changed** (ADR 0474, proposed). Some pages are refused, because a mistake on them locks the operator out or opens the
device to the network: the login password, the user restriction and setting lock, the reset menu, the firmware
update and its setup, the security settings, every wired, wireless and Wi-Fi Direct network page, the protocol and
interface pages, and every security page (certificates, TLS, IPsec, the IP and MAC filters). The list is in the
module's code and its tests, not in a config value, so no call can widen it; it is checked against the page asked
and against the address the form posts to. The operator changes such a page in a browser at the device itself.
and against the address the form posts to; a unit test refuses each listed page. The operator changes such a page in a browser at the device itself.
**Who asked, and who is told.** Every change names who asked, the caller the bus proved for the call; a call with no
**Who asked, and who is told** (ADR 0474, proposed). Every change names who asked, the caller the bus proved for the call; a call with no
proven caller is refused. Each changed field is announced as `brother.printer.configured` with the page, the field,
the old and the new value, who asked and when, and the operator is told through the operator channel, once per call.
No password is ever in an answer, an event or a message.
No password is ever in an answer, an event, a message or a log; a unit test reads each of them for it.
**Restarting.** `printer.restart` restarts the device through its reboot page, which configure refuses. It is
**Restarting.** `printer.restart` is decided by ADR 0467 §5; that it goes through the device's reboot page, posting
that page's own form, is ADR 0474's, proposed. It is the one call that posts to the reboot page, which configure refuses. It is
refused while the device holds a print or scan job, and waits at most five minutes for the printer to answer again
(ADR 0467 §5).
**The module's own defaults stay config.** The scan resolution, colour mode and cropping are the module's config
values, held by the config module and changed through a proposal on the operator's Approve; configure changes the
device's pages and never the module's config.
values, held by the config module and changed through its `config` verb (ADR 0348); they are not trusted values.
Configure changes the device's pages and never the module's config (ADR 0474, proposed), which a unit test checks.
## 6. Health
The tool side's health is whether the scanner answers; the device process's is its unit. A certificate the device
serves that is not pinned is refused, and the refusal names the served and the pinned fingerprints. A device serves
serves that is not pinned is refused, and the refusal names the served and the pinned fingerprint. A device serves
a new certificate after a reset, a firmware update or a certificate's renewal, so a refusal is either that or
another machine answering in its place; only the operator can tell which, and pins the new fingerprint as a config
value. A firmware that moves an admin page is said as a page not found, never as success.
value. A firmware that moves an admin page is said as a page not found, never as success: a unit test replays a
missing page and expects the error.
## 7. Still open
- **A certificate change said before a call fails.** Today a changed certificate shows only when a verb is refused;
the module should raise it as its condition, naming both fingerprints. No decision holds it yet.
- **Files off the bus.** Documents cross the bus in parts today (ADR 0468 §3). ADR 0468 is to be revised so that a
- **Files off the bus.** Documents cross the bus in parts, as proposed (ADR 0468 §3). ADR 0468 is to be revised so that a
document travels through a signed link to the bucket instead, and only its key crosses the bus.
- **Restart is not built yet.** `printer.restart` is decided (ADR 0467 §5) and follows `printer.configure`.
- **Not built yet either:** several documents on the glass, a document of several glass scans, the long run's id
and the print of a file (ADR NNNN, proposed).
03-DESIGN/01-to-be/README.md
+1 -1
View File
@@ -59,7 +59,7 @@ document is written and this one's status becomes `implemented`.
| [`57-building-config-and-provisioning.md`](57-building-config-and-provisioning.md) | **Designed.** The work of ADR 0348 and ADR 0349 as 37 packages, each an issue with its proof: foundations, template files, config in its own module, the provisioner and its client, secrets in the vault, bindings from providers, collections, a module's runtime readers, and removing the old forms; at most five worked at once | ADR 0348, ADR 0349 |
| [`58-agent-work-as-the-meshs-own.md`](58-agent-work-as-the-meshs-own.md) | **Designed.** Agent work as the mesh's own: a thread seat keeps every thread whole on the bus; a thread handler runs the harness headless in a sandbox per session, the workspace on the thread's own forge branch; a workspace toolkit and named tools, no general command runner; one identity seat for persons, agents and modules, roles of grants, every tool an effect, signed bus logins, and the switch to them one identity at a time | ADR 0383, ADR 0384, ADR 0385, ADR 0386, ADR 0387, ADR 0388, ADR 0389, ADR 0390 |
| [`59-the-mail-web-client.md`](59-the-mail-web-client.md) | **In progress.** The operator's mail, every account, in a browser on the mesh's own machines: a module of its own, `mesh-mail-web`, holds `mail-webclient`, renders pages on the server and reads and sends only through `mail-store`'s verbs under a caller granted per account; its route reaches the private network only, the operator signs in with Keycloak, and a mail goes out only on the operator's Approve; then Betterbird is removed | ADR 0440, ADR 0378, ADR 0379 |
| [`60-the-brother-module.md`](60-the-brother-module.md) | **In progress.** One module, `brother`, holds the `scanner` and `printer` seats for the Brother multifunction device: scans from the glass (cropped) or the feeder (one PDF), keeps each scan in its bucket and announces it, prints in one call, reads the admin pages and changes settings on those where a mistake cannot lock the operator out, each change recorded and told; only its device process holds the credentials | ADR 0467, ADR 0464, ADR 0468, ADR 0474 |
| [`60-the-brother-module.md`](60-the-brother-module.md) | **Proposed.** One module, `brother`, holds the `scanner` and `printer` seats for the Brother multifunction device: scans from the glass (cropped) or the feeder (one PDF), keeps each scan in its bucket and announces it, prints in one call, reads the admin pages and changes settings on those where a mistake cannot lock the operator out, each change recorded and told; only its device process holds the credentials | ADR 0467, ADR 0464, ADR 0468, ADR 0474 |
## Not yet written