diff --git a/03-DESIGN/01-to-be/60-the-brother-module.md b/03-DESIGN/01-to-be/60-the-brother-module.md index 55dd6411..4c41bd04 100644 --- a/03-DESIGN/01-to-be/60-the-brother-module.md +++ b/03-DESIGN/01-to-be/60-the-brother-module.md @@ -1,7 +1,7 @@ --- layer: to-be -status: proposed -code: [mesh-catalog] +status: in-progress +code: [mesh-catalog, mesh-sdk, mesh-controller] updated: 2026-10-21 decisions: - "ADR 0464" @@ -19,8 +19,8 @@ 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 and ADR 0467 are in force. Proposed, and not in force: ADR 0468 for the device process, the bucket and -the parts; ADR 0475 for the feeder, multi-page and several-document scans and the one-call print; ADR 0474 for +(ADR 0464, ADR 0467 and ADR 0468 are in force; ADR 0468 is being built, milestones F1 to F3 below. Proposed, and +not in force: ADR 0475 for the feeder, multi-page and several-document scans; 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 @@ -99,19 +99,29 @@ is the evidence. ## 3. Printing -A caller prints in one call: `printer.print` takes a kept scan by its key, a document it has uploaded, or a file -under the operator's home folder, which the verb uploads and prints in the same call (the file: ADR 0475, 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). +A caller prints in one call: `printer.print` takes exactly one of a key in the bucket (`object`), a file on any +machine of the mesh (`path` with `node`) or a web link (`url`), with the copies, the sides and the paper (ADR 0468 +§5). A file on a machine is sent into the bucket by that machine's node-files `upload`, which refuses the secret +places a read refuses, and printed by its key (ADR 0468 §9). A web link is fetched by the device process, at most +60 s, 100 MiB and 5 redirects, and never from an address inside the mesh or a private network (ADR 0468 §6). A +document that is neither PDF nor JPEG is turned into a PDF by the seat `document-converter`, which only-office holds +(ADR 0468 §7). The device process then sends the document to the printer in a format the printer itself lists as +accepted, read before the job. + +**No document crosses the bus.** The bus carries a document's key, size, SHA-256 and type; the bytes move over +HTTP between a party and the object store, on a signed link of at most 10 minutes for one object and one method +(ADR 0468 §3). The device process signs links for the module's own steps with its binding's key; every other +party asks `object-store.link`, which minio serves and signs with a key limited to that bucket, for a caller that +brother's `shares` names (ADR 0468 §8). The parts verbs `printer.upload` and `scanner.document` still serve until +issue 1569 removes them. ## 4. The bucket and the events Every scan is kept once in the module's own bucket under its SHA-256, and announced with the event `brother.scan.added` once it is stored: its key, size, page count, size in millimetres, resolution and colour mode, -never the image. The scan folder is one consumer of the stored scans: the tool side fetches the scan and files it -there as the operator. The module deletes nothing from the bucket; the operator removes what they no longer want +never the image. The scan folder is one consumer of the stored scans: once the scan is stored and announced, the tool side +reads it by a link the device process signed and files it there as the operator; the device process never writes +into the operator's home (ADR 0468 §4). The module deletes nothing from the bucket; the operator removes what they no longer want (ADR 0468 §2, §4). The other events are `brother.printer.restarted`, when the device answers again after a restart (ADR 0467 §6), and @@ -179,8 +189,24 @@ missing page and expects the error. ## 7. Still open -- **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. +- **The parts verbs.** `printer.upload` and `scanner.document` carry a document over the bus in parts; issue 1569 + removes them once their callers use links, and revises ADR 0475 to ADR 0468. +- **Several printers.** The `printer` and `scanner` seats take one holder; issue 1602 asks for the decision that lets + a second printer join. - **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 0475, proposed). +- **Not built yet either:** several documents on the glass, a document of several glass scans and the long run's id + (ADR 0475, proposed). The print of a machine's file is ADR 0468's, built in milestone F3. + +## Milestones + +The milestones build ADR 0468, feature `files-through-the-store`. They are cut by release order: the catalogue's +merge check reads manifests with the controller the mesh runs, and the controller vendors the SDK, so a new +manifest field ships SDK first, then the controller, then the catalogue (playbook 07, *a new manifest word*). + +| # | Outcome | Proves | Repository | Issues | +|---|---|---|---|---| +| F1 | A manifest may name who else may read or write its bucket, and every module has one helper that signs and streams a store link. Usable only by F2 and F3. | ADR 0468 §3, §8 (the field) | mesh-sdk | 1591 (`shares` on a requires of s3-bucket), 1592 (link signing and streaming) | +| F2 | The controller accepts `shares` and writes it into the consumer's grant. Usable only by F3. | ADR 0468 §8 | mesh-controller | 1593 (take the SDK); depends on F1 | +| F3 | The operator prints a stored scan, a file on any machine (a .docx on a laptop among them) or a web link in one call, and scans land in the scan folder from the store; no document these verbs move crosses the bus (the parts verbs stay until issue 1569). Depends on F2. | the acceptance above; ADR 0468 §1–§9 | mesh-catalog | minio: 1594 (a signing key per bucket), 1516 (`object-store.link`, retiring the root-signed link); mesh-files: 1597 (upload, download); only-office: 1595 (`document-converter.convert`), 1596 (the converter process); brother: 1598 (print by key or a machine's file), 1599 (print a web link), 1600 (convert before printing), 1601 (the scan folder from the store) | + +Order inside F3: minio, then mesh-files and only-office, then brother; one pull request of `mesh-catalog`.