docs(adr): shared spaces, decided further for step 4

ADR 0044's D20 to D26, the developer's choices on 11 Nov 2026, each the
agent's recommendation: a shared space's rows trusted when any member
pinned signed them (D20); a shared space always sealed (D21); rolling
its key seals new writes alone (D22); a shared studyset at the top level
for every member (D23); writes reaching a shared space through the sync
engine, our fork routing them (D24); tags staying each member's own
(D25); and personal rows naming shared content by a plain ID, as the
engine links no row of one space to another's (D26). Step 3 is marked
built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
This commit is contained in:
Tizian 「ティツィアーン」 2026-11-11 12:27:15 +01:00
commit 6b1e9a0226
Signed by: raisondetredev
GPG key ID: 07F6FCF405488B64

View file

@ -3,8 +3,8 @@
- **Status:** decided 10 Nov 2026 by the developer: D8 is their own request, D9 and D10
their choices over the agent's recommendations (all ticked at first; agents editing
directly), D1 to D7 the agent's recommendations, which they chose; D11 to D13 the
agent's recommendations, which they chose on 11 Nov 2026, D14 too. Not built yet;
the steps below.
agent's recommendations, which they chose on 11 Nov 2026, D14 too, and D15 to D26.
Steps 1 to 3 built; the rest below.
- **Builds on:** ADR 0005 (publishing, reports and suggestions), ADR 0014 (the module),
ADR 0016 (one account across an instance), ADR 0017 (key pairs), ADR 0019 (private
studysets), ADR 0021 (operators and assistants).
@ -105,6 +105,43 @@ member reads everything in the space.
- **D19.** **Step 3 builds the module's wrapped keys and halkyon_app's device side**
(decided 11 Nov 2026, the agent's recommendation), each tested; Learn takes them into
its `Privacy` with the copy in step 4.
- **D20.** **A row in a shared space is trusted when any member this device pinned
signed it** (decided 11 Nov 2026, the agent's recommendation): current or former,
never by the author column a row names, which the instance could alter; a few
signature checks a row, for a group of a few people.
- **D21.** **A shared space is always sealed** with its key (decided 11 Nov 2026, the
agent's recommendation): sharing needs keys, so someone without a password sets one
first, and what goes public goes through *Share with the community*. ADR 0019's
readable records stay out of shared spaces.
- **D22.** **Rolling the key seals new writes alone** (decided 11 Nov 2026, the agent's
recommendation, reading D3): new and changed rows take the new key, earlier ones stay
under the key they had, which the members keep, since whoever went had read them
already. The instance marks a space whose member went, and the next writer's device
makes the new key and seals it to the members.
- **D23.** **A shared studyset is at the top level for every member** (decided 11 Nov
2026, the agent's recommendation): sharing takes it with its subtree out of its
parent, marked as shared; placing it in one's own tree may come later. Invited by
@handle, it appears in the invitee's list, which they may leave; the Inbox is step 5.
- **D24.** **Writes reach a shared space through the engine** (decided 11 Nov 2026, the
agent's recommendation): found 11 Nov 2026, every gateway writes in the personal space
and an update of a shared row finds none. Our sync fork updates and deletes a row in
its own space, checked against the person's role there, and asks the host which space
a new row goes in, which Learn answers in one place (a card by its studyset, a
revision by its card), so no gateway changes and none is missed; wrapping each write
in `transactionForUser` was the other way.
- **D25.** **Tags stay each member's own** (decided 11 Nov 2026, the agent's
recommendation): in their personal space under their personal key, as reviews (D2).
- **D26.** **Personal rows name shared content by a plain ID** (decided 11 Nov 2026, the
agent's recommendation): found 11 Nov 2026 by experiment, the engine blanks a
reference from one space to another (its rule, *foreign keys stay within a space*),
and reviews, tags (cards', notes', paths'), PDF readings and path answers are
personal (D2, D25) but name cards, notes, paths, steps and PDFs. Those six tables
keep their columns without the database relation; Learn deletes what names an item
as it deletes the item, and upkeep prunes rows naming one gone. Putting them in the
shared space would show members each other's reviews; teaching the engine to link
across spaces goes against its design.
## Steps
@ -121,7 +158,7 @@ member reads everything in the space.
endpoint, a Viewer sealing none, a member's keys going with their membership);
halkyon_app seals and opens them (`SharedKeys`), pinning each member's public keys
on first sight (`KeyPins`), with the safety code of halkyon_keys (`safetyCode`).
4. **Learn shares a studyset** (D14): the copy, *Manage collaborators* (invite by
4. **Learn shares a studyset** (D14, D20 to D26): the copy, *Manage collaborators* (invite by
@handle, the members, their roles, leaving), each member's own reviews.
5. **Invitations by email and by link** (D4, D5), the Inbox.
6. **Agents** (D6, D7, D10, D12).