Merge pull request 'Adopt a mail account the profile already holds instead of adding it twice (issue 345, ADR 0317)' (#323) from feat/345-adopt-existing-accounts into main

03-DESIGN/01-to-be/56-the-mail-client-set-up-by-the-mesh.md

@@ -5,6 +5,7 @@ code: []
 updated: 2026-10-12
 decisions:
   - "ADR 0316"
+  - "ADR 0317"
 ---
 
 # 56 — The mail client, set up by the mesh
@@ -108,6 +109,38 @@ and per key the account, its identity, its incoming server and its outgoing serv
    their order, and removes only its own keys when an account leaves the setting. The mail already fetched
    stays in the profile.
 
+**An account the profile already holds is adopted, not added twice** (ADR 0317, changing ADR 0316 §11 and §12).
+At every apply, an account the module recorded on that node, adopted or created, is kept by its recorded keys,
+and an account under `mesh_` keys is always the module's creation, so a lost record is rebuilt as it was.
+Every other declared account is matched by its address against the default identities of the profile in use:
+
+| the profile holds the address | the module |
+|---|---|
+| once, in an account that is not Owl's | adopts it: takes its existing keys under its ownership, records them per node in its own directory, and places the declared values over them, which changes only those that differ (the apply names each by preference name) |
+| nowhere | creates the account under its own `mesh_<name>` keys, as above |
+| twice or more, or in Owl's account | refuses that account, writes nothing for it, and says the remedy: remove the duplicate in Betterbird, or give the account's optional `key` in that node's layer |
+
+The optional `key` is the one field ADR 0317 adds to an entry of `accounts`: the account key to adopt on that
+node, used only to settle an ambiguous match, and refused unless that key is in the list, has the declared
+address and is not Owl's.
+
+The module's status names each declared account by its place in the setting and its keys, never by an address,
+a host or a name. An adopted account keeps its mail, its folder, filter and cache preferences, and its kept sign-in: the module
+writes only the fields the setting names. When it leaves the setting, its keys are released: dropped from the
+user.js and the record, the account left in the profile as the person's. Only an account the module created is
+removed from the list.
+
+**The value is derived, not retyped.** The tool `betterbird_accounts` reads the accounts of the profile in use
+and, with `propose`, builds the `accounts` value from every account but Owl's, without any credential, and
+proposes it for the operator's Approve (ADR 0277). Its answer to the caller gives counts and kinds only. The ask
+shows the accounts in shape, with ‹address› in place of each address and host, beside the layer's fingerprint;
+the operator reads the whole value at their own desk by the proposal's id and checks the fingerprint before
+approving.
+
+**The order.** The value is derived on a node whose profile already holds the accounts and set for every
+desktop node. A node that holds the same accounts adopts them by address; a fresh node creates them, each
+signing in once. No node applies the setting before it is approved, so no node gets an account twice.
+
 **The work account is not declared.** It goes through Owl: the person creates it in Owl's own setup, which
 signs in through the provider's own login with its second factor, and binds Owl's licence to the address.
 
@@ -154,6 +187,10 @@ module needs.
 - **The module's tests:** writing into `prefs.js` adds and removes only the module's keys, keeps the others and
   their order, and is refused while Betterbird runs; the count of declared accounts without a kept sign-in is
   taken from the login store's server names, which are kept in the clear, without decrypting anything.
+- **The adoption's tests, on profile fixtures:** an address held once is adopted under its existing keys with the
+  list unchanged; an absent one is created; a duplicate or Owl's is refused with the remedy, and a `key` settles a duplicate; a release leaves the
+  profile as it was; `betterbird_accounts` builds a value without Owl's account or a credential and answers counts
+  only.
 - **The builder's tests:** an upstream file whose download does not match its sha256 fails the build.
 - **Live, on each desktop node after its switch:** `betterbird_check` says installed at the pinned version from
   the mesh, the policy placed, Owl at its pin and active, the profile in use the same as before the switch, and
@@ -162,6 +199,6 @@ module needs.
 
 ## References
 
-- ADR 0316, ADR 0180, ADR 0182, ADR 0205, ADR 0208, ADR 0277.
+- ADR 0316, ADR 0317, ADR 0180, ADR 0182, ADR 0205, ADR 0208, ADR 0277.
 - Issue 345 (the reminder window, extended on 2026-10-12), issue 342, issue 339.
 - Thunderbird's enterprise policy templates (ESR 153): `ExtensionSettings`, `DisableAppUpdate`, `Preferences`.

03-DESIGN/01-to-be/README.md

@@ -55,7 +55,7 @@ document is written and this one's status becomes `implemented`.
 | [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content (ADR 0291) | ADR 0275, ADR 0291 |
 | [`54-the-controllers-records-on-the-bus.md`](54-the-controllers-records-on-the-bus.md) | **Designed.** The controller keeps five record mirrors on the bus (nodes, assignments, walks, builds, settings): each a bucket written from its store only when the record changed, with one event per write, and audited against the store every self-check run, a difference raised as `mirror-drifted` before the healer H6 repairs it | ADR 0289 |
 | [`55-the-knowledge-base.md`](55-the-knowledge-base.md) | **Designed.** The mesh keeps its decision records and research efforts whole in one module, `mesh-knowledge`, on the control-node: number, status, topic, typed links both ways, each decision's clauses with their own status, and the reasoning, with every version; a record is proposed, checked at the write, reviewed by the knowledge base's own judgement and accepted there, with the operator's Approve when it needs it; agents ask what holds in one bounded call | ADR 0290 |
-| [`56-the-mail-client-set-up-by-the-mesh.md`](56-the-mail-client-set-up-by-the-mesh.md) | **Designed.** On every node with a display server, the `betterbird` module installs Betterbird from a pinned upstream release mirrored into the artifact store, ships the Owl add-on pinned and installed by Betterbird's enterprise policy, and declares the operator's mail accounts in a trusted setting without credentials; each account signs in once at a person's first use | ADR 0316 |
+| [`56-the-mail-client-set-up-by-the-mesh.md`](56-the-mail-client-set-up-by-the-mesh.md) | **Designed.** On every node with a display server, the `betterbird` module installs Betterbird from a pinned upstream release mirrored into the artifact store, ships the Owl add-on pinned and installed by Betterbird's enterprise policy, and declares the operator's mail accounts in a trusted setting without credentials; each account signs in once at a person's first use, and one the profile already holds is adopted by its address | ADR 0316, ADR 0317 |
 
 ## Not yet written