docs: apply review round 19 to the several-directories plan

plans/2026-10-22-directories-in-operators.md

@@ -10,7 +10,7 @@ Directories become a fifth list in each operator's servers and under Your server
 
 ep's newest direction, a generic MCP-style service layer in which a service fills a role when it offers the role's tools, is answered in section 4.6, against his own draft (docs/protocol/agent-protocols.md, 2026-10-19). Plainly: this design replaces "a role inferred from the tools a service offers" with "the user puts a directory in the Directories list", and then checks the one tool that list needs. Once users can add directories, whatever the apps send becomes the protocol every other directory implements, so from that release the apps speak ep's envelope with MCP to every directory, and SimpleX Directory answers it before the apps ship (pull request 2). A later move to services as the services design plans them then keeps the storage, the search, the consent, the screens' places and the request format; it renames the screens, stores each service's tools and roles, migrates the rows and keeps the old settings key for a release (~1,400 lines, or ~2,750 with the core taking over requests and the `protocols` declaration; section 4.6.3). Telemetry, the next service ep named, needs explicit consent; assuming each operator would receive its own, in this design it is a switch on the operator's screen, and if only the app vendor receives it, a switch in Privacy settings with one built-in address, as badges have; either design needs the same privacy-policy change first, and a simplexmq change so the receiving operator can't tie a report to the device (section 4.6.2).
 
-Decisions asked of ep (open questions 1, 2, 3, 9, 13, 14, 15 and 16): this design or the service layer first; if this design, the core pull request to master right away, ideally before directory search is released; whether directory search ships before several directories (recommended) or waits for them; whether a directory follows its operator's servers switch (recommended: no, its own switch decides, so Flux-only users and self-hosters keep directory search, asked first); which protocol directories speak (recommended: his envelope with an MCP tool `simplex.directory.search`, the contract the services design also proposes, from the release that lets users add directories, with his draft documenting the core's compression of large replies); whether to ship while colluding directories can link one search (recommended: yes); whether an ordinary group two directories list may show twice (recommended: yes, each row naming its directory); and whether a directory the user added may show SimpleX names on its results (recommended: no, only operators' directories). Section 12 compares this design with the services design as both stand.
+Decisions asked of ep (open questions 1, 2, 3, 9, 13, 14, 15 and 16): this design or the service layer first; if this design, the core pull request to master right away, ideally before directory search is released; whether directory search ships before several directories (recommended) or waits for them; whether a directory follows its operator's servers switch (recommended: no, its own switch decides, so Flux-only users and self-hosters keep directory search, asked first); which protocol directories speak (recommended: his envelope with an MCP tool `simplex.directory.search`, the contract the services design also proposes, from the release that lets users add directories, with his draft documenting the core's compression of large replies); whether to ship while colluding directories can link one search (recommended: yes); whether an ordinary group two directories list may show twice (recommended: yes, each row in its directory's place, its long-press menu naming the directory); and whether a directory the user added may show SimpleX names on its results (recommended: no, only operators' directories). Section 12 compares this design with the services design as both stand.
 
 ## 1. Goal and acceptance criteria
 
@@ -41,7 +41,7 @@ Apps (pull requests 3 and 4; not compiled in the container, checked on the runne
 - AC13: CI no longer edits app sources and never reaches the live SimpleX Directory: a scripted step meets the SimpleX Directory preset turned on only to press Cancel in an alert that names it; whenever a test backend runs, every Claude session starts with the preset off and the test directories added; and every prompt, those used without a backend included, forbids Enable or Search in an alert that names SimpleX Directory. It checks on the runners, in two steps:
   - With the consent and fan-out slice (8a): the test backends start two directories, "CI Directory A" and "CI Directory B", B listing a few of A's entries (a shared channel, a shared ordinary group, two entries with large images that come one per page, so B has a second page for the turn-off check, and what the Claude cases need), each logging the service requests it receives. First, with the preset still on and nothing sent: turn the switch on in Privacy settings, search, and check that the second alert names only SimpleX Directory and that Cancel leaves no spinner and no rows. Then turn the preset off, turn the switch off in Privacy settings and add A in Settings ("Test directory" passes); today's one-directory checks run with A alone, their texts unchanged ("Search failed, tap to retry", "Load more · N left"). Then add B, turn the switch off again, and check: the first alert names both "(added by you)"; results from both arrive. Then that a directory turned off receives nothing, by A's request count, which first must rise: by one after "Test directory" for A and by one after each search with A on, or the check fails (so a missing log line or a wrong count fails, not passes). Search a text both list over more than one page (A's count rises), turn A off in Settings, tap Load more (B's next page comes; A's count unchanged); turn A on, stop A, search (a retry row shows: the generic one until 8b, A's own after), start A and wait until A's log shows the request queued while it was stopped, failing after 60 s, read A's count, turn A off, tap the retry row (it goes; A's count unchanged); search again (no row and no alert names A; A's count unchanged); turn A back on.
   - With the submenu slice (9): the shared channel's `group_profiles.short_descr` changed in B's database (sqlite3, while B is stopped, checked to survive B's restart), since a directory sends a channel's own short description; with A and B on: one list with the shared channel once, with A's description; the shared ordinary group twice, A's row first, each submenu naming its own directory; "about N left"; with B stopped, B's own retry row and A's results kept, then B started again; the submenu of the shared channel listing both; footer rows in both list layouts.
-  - On a device or by hand (each needs agreeing to the live SimpleX Directory, which a runner must not reach): the one-time upgrade step, and forgetting on switch-off and on turning a preset off. Before slice 8a, on a device with today's app and the live SimpleX Directory: join an ordinary group it lists through the owner's own group link, then search for it and tap Open on its row (open question 15's inference, which this case already has with one directory); the result goes to the report and to ep's answer to open question 15.
+  - On a device or by hand (each needs agreeing to the live SimpleX Directory, which a runner must not reach): the one-time upgrade step, and forgetting on switch-off and on turning a preset off. Before slice 8a, on a device with today's app and the live SimpleX Directory: join an ordinary group it lists through the owner's own group link, then search for it (in the app if the live directory already answers in-app searches, or in SimpleX Directory's chat, whose reply carries the group link the directory created, Service.hs:1319-1334 at 4afce4931) and open that link (open question 15's inference, which this case already has with one directory); the result goes to the report and to ep's answer to open question 15.
 
 ## 2. Non-goals
 
@@ -451,7 +451,7 @@ Verified on the desktop-linux and android-emu workflows.
 12. **A directory a later version no longer presets, and when that rule ships.** Recommended: keep it, turned off, under Your servers (section 4.2, rule 2), shipped with the first version that drops a preset (slice 3c), not now: until then it would do nothing and only start its cost (a binary with the rule that presets fewer directories turns the others off silently). The adopt rule ships now: it costs nothing and guards a start-up failure in the first version that presets an address a user may have added. If deleting is preferred: a store delete outside the preset guard at start-up, which the app's remembered addresses don't see, so a later re-preset turns it back on and it can receive searches without a question. If retire ships now: written and tested once, and its cost starts with the first release.
 13. **Which protocol directories speak** (ep). Once users can add directories, what the apps send is the protocol every other directory implements. Recommended (a): your envelope with an MCP `tools/call` of `simplex.directory.search`, from the release that lets users add directories; "Test directory" checks that `tools/list` includes it; SimpleX Directory answers it and today's request (pull request 2, ~600 lines with the bot helper, before the apps; ~80 more lines per app than today's request). The tool's contract keeps today's fields and is the one the services design proposes: a namespaced name, so a bot with its own `search` tool never passes "Test directory" or, later, fills the directory role, and the directory's work carries over to that design (which also needs its profile to declare `protocols.mcp`). Costs: the apps depend on your draft, so a change to the envelope or the binding before that release changes the directory and both apps; after it, changes must stay compatible or be versioned; SimpleX Directory must be redeployed before the apps ship; before pull request 2 merges, you confirm the tool's contract, and the draft gains the compression paragraph of section 5.1. A variant of (a): directory search's own release already sends this form (slice 6's change, ~80 lines per app, made in pull request #7588, and pull request 2 deployed before that release); then no app ever sends a SimpleX-only request and SimpleX Directory never answers two forms, at the cost of tying directory search, already reviewed, to your draft and to the directory's redeployment. (b) Today's request with a version field: no dependency on the draft; but every directory anyone builds speaks a SimpleX-only request, and a later move keeps both forms in both apps for as long as any added directory speaks only the old one (~150 lines per platform, no end date). (c) Only preset directories until the envelope is final: no commitment; but adding a directory (boards 11–12) waits, and with SimpleX Directory the only preset, several directories change nothing until another operator presets one.
 14. **Shipping while searches can be linked** (ep). Recommended: ship. The alerts promise only "each search separately and without your profile", which holds; colluding directories can link one search by its text and time, and a self-hosting user's searches can be linked by their reply server, as with one directory today. With default servers every reply queue is on a SimpleX Chat server, so SimpleX Chat, which runs SimpleX Directory, can already link each search to the device's session there, with one directory as with several (section 5.4). The simplexmq fix (reply queues on their own transport session; the services plan sketches a related "strict" request that avoids a named operator's proxy and servers) is proposed and unplanned; it would stop SimpleX Chat tying searches to a device's session, but not colluding directories matching one search by its text and time, which nothing in either design can stop. If not: several directories wait for that fix, which still leaves the directories' matching, or search stays with one directory.
-15. **An ordinary group listed by two directories** (ep). Each directory lists an ordinary group with the group link it created itself, so the apps see two links and nothing that says they are one group; channels and public groups publish one link in their profile, so they merge. Recommended: show both rows, each in its directory's place and naming its directory in the long-press submenu; the user sees both descriptions and chooses. Merging by name, image or description is rejected: a look-alike would hide the real group, or the real one the look-alike. A key that every directory would send for one ordinary group doesn't exist (the group profile carries an identity, `publicGroupId`, only for public groups, Types.hs:906-911); adding one is a change to the chat protocol's group profile, outside this design. Cost of two rows: a member who joined through one directory's link sees the other directory's row with Open, since the core finds a group link's plan by that link's own hash (Commands.hs:4790-4796 at 4afce4931), and Open would likely join again as a second member (an inference, checked on a device before slice 8a, AC13); this happens today for a group joined through a link the directory didn't create, and becomes common with several directories. Merging by name would avoid it, at the look-alike cost above.
+15. **An ordinary group listed by two directories** (ep). Each directory lists an ordinary group with the group link it created itself, so the apps see two links and nothing that says they are one group; channels and public groups publish one link in their profile, so they merge. Recommended: show both rows, each in its directory's place and naming its directory in the long-press submenu (the rows themselves don't name it); the user sees both descriptions and chooses. Merging by name, image or description is rejected: a look-alike would hide the real group, or the real one the look-alike. A key that every directory would send for one ordinary group doesn't exist (the group profile carries an identity, `publicGroupId`, only for public groups, Types.hs:906-911); adding one is a change to the chat protocol's group profile, outside this design. Cost of two rows: a member who joined through one directory's link sees the other directory's row with Open, since the core finds a group link's plan by that link's own hash (Commands.hs:4790-4796 at 4afce4931), and Open would likely join again as a second member (an inference, checked on a device before slice 8a, AC13); this happens today for a group joined through a link the directory didn't create, and becomes common with several directories. Merging by name would avoid it, at the look-alike cost above.
 16. **SimpleX names from directories you added** (ep). Recommended: a result shows its SimpleX name only from an operator's directory; SimpleX Directory sends a name only after verifying the group's domain, a directory the user added can send any, and the row would show it the same way. If you'd rather show them all: a look-alike channel can carry a known channel's name. If the apps should check each name: one names-server lookup per shown result, which tells the names server what each search found.
 
 ## 10. Out of scope (noticed, not doing)