Changeset 780a7c6 in Klonkt for src/services/guardianship/queues.js

Timestamp:

07/24/2026 07:44:15 PM (7 weeks ago)

Author:

Robin Genis <roboburr@…>

Branches:

main

Children:

b5924eb

Parents:

c26cc18

Message:

Guardianship Fase 0+1: de echte multi-party handshake (FEP-633c §3)

De eerste versie committeerde na één accept. Nu de spec: geen enkele partij
maakt een voogdij alleen, en een nieuwe guardian erbij kan niet zonder
toestemming van de bestaande. Daemon als blauwdruk, zodat Klonkt en de
test-daemon exact hetzelfde gedragen en de Shaer-clients één contract lezen.

Fase 0 (datamodel): ap_guardian_offers (per lokale partij een kopie van de
handshake, PK slug+offer_id) + ap_guardian_offer_accepts (de accept-tally).
ap_guardianships houdt alleen nog de GECOMMITTE relaties.

Fase 1 (state-machine): offers.js is een getrouwe port van de daemon-Handshake
(accepts over ward+candidate+existing; ready = ward && candidate && (geen
existing OF >=1 existing); een Reject voidt). handshake.js orchestreert het
gedistribueerd: de kandidaat adresseert de Offer aan ward + alle bestaande
guardians (§3.1.1); elke Accept wordt aan alle andere partijen gebroadcast, dus
elke instance-kopie convergeert; zodra een kopie compleet is committeert die
lokaal (ward schrijft shaer:guardians, guardian schrijft z'n ward), met de
kandidaat-inbox als handle (§6). Volgorde-onafhankelijk.

Ook: §1 wederzijdse uitsluiting (een ward is nooit ook guardian in het
actor-doc), de queues vullen nu de echte accept-tally (needsMyAccept/
readyToCommit/acceptedBy/existingGuardians), en de PWA + Berichten beantwoorden
via de C2S Accept/Reject-pijplijn per offer-id. De co-guardian ziet een
mede-voogdij-aanvraag met accepteer/weiger in de PWA.

Changed files:
src/config/database.js

• tabellen ap_guardian_offers + ap_guardian_offer_accepts

src/services/guardianship/offers.js (NEW)

• de handshake-state-machine (daemon-port), per-instance in SQLite

src/services/guardianship/relations.js

• alleen commit-writers + actor-props (§1 uitsluiting)

src/services/guardianship/handshake.js

• gedistribueerde multi-party C2S/S2S orchestratie

src/services/guardianship/queues.js

• offers-queue uit de state-machine

src/services/guardianship/index.js

• exports bijgewerkt

src/services/ActivityPubService.js

• wire localSlug + fetchActor; inbound-routing naar alle lokale partijen

src/routes/guardian.js

• dashboard toont offers met tally; POST /guardian/offer (accept/reject)

src/routes/posts.js

• Berichten toont ward-offers uit de state-machine; accept via offer-id

src/views/pages/messages.ejs, src/assets/js/guardian.js, src/assets/css/guardian.css

• offer-kaarten per state (mijn aanvraag / mede-voogdij / wachten)

src/services/i18n.js

• accept/reject/complete/coguard + co-guardian push (nl/en/de)

test/guardianship.test.js

• multi-party: eerste guardian, co-approval bestaande guardian, reject voidt, ward-mag-niet-guarden, vaste initiator

remarks: Fase 2 (follow-gating), 3 (hasGuardians + Not-a-Teapot), 4 (Undo/
emancipatie) volgen. 164 tests groen.

-robo
Co-Authored-By: Claude Opus 4.8 <noreply@…>

File:

• src/services/guardianship/queues.js (modified) (2 diffs)

src/services/guardianship/queues.js

@@ -3 +3 @@
  *
  * Three OrderedCollections on the actor (shaer:queues), same contract as the
- * Shaer test daemon so the iOS/Android guardian dashboards read them as-is:
- *  - offers:  pending guardianship offers where I am a party (§3)
- *  - follows: pending follows for my wards (§5.3) — Klonkt has no gated
- *             follows yet, so this collection is empty for now
- *  - wards:   my wards, for the dashboard's wards list
+ * Shaer test daemon so the iOS/Android dashboards read them as-is:
+ *  - offers:  pending handshake offers where I am a party (§3), with the full
+ *             accept tally so the client shows the right action
+ *  - follows: pending gated follows for my wards (§5.3) — Fase 2, empty for now
+ *  - wards:   my committed wards
  */
-import { GUARDIAN_RELATIONSHIP_COMPACT } from './context.js';
+import * as offers from './offers.js';
 import * as relations from './relations.js';
 
@@ -16 +16 @@
 });
 
-/** Pending offers, reconstructed as Offer activities (either side). Each item
- *  also carries the daemon-contract helper fields (shaer:ward, candidate,
- *  needsMyAccept, iAmCandidate, …): the Shaer clients render their accept
- *  button from those, so the shapes must match the test daemon exactly. */
+/** Pending offers where the local site is a party, each with its accept tally. */
 export function offersCollection(id, slug, me) {
-  const items = relations.listOffers(slug).map((r) => {
-    const ward = r.role === 'guardian' ? r.other_uri : me;
-    const candidate = r.role === 'guardian' ? me : r.other_uri;
-    return {
-      id: r.offer_id || `${me}/offers/pending-${r.id}`,
-      type: 'Offer',
-      actor: candidate,
-      object: {
-        type: 'Relationship',
-        subject: ward,
-        relationship: GUARDIAN_RELATIONSHIP_COMPACT,
-        object: candidate,
-      },
-      'shaer:ward': ward,
-      'shaer:candidate': candidate,
-      'shaer:existingGuardians': relations.listGuardians(slug).map((g) => g.other_uri),
-      'shaer:acceptedBy': [],
-      // Klonkt's flow is single-phase: the ward's Accept commits at once, so
-      // only the ward-side owner has an action here.
-      'shaer:needsMyAccept': r.role === 'ward',
-      'shaer:readyToCommit': false,
-      'shaer:iAmCandidate': r.role === 'guardian',
-      'shaer:handle': r.other_handle || undefined,
-      published: r.created_at,
-    };
-  });
+  const items = offers.listForParty(slug, me).map((o) => offers.queueItem(o, me));
   return collection(id, items);
 }
 
-/** Gated follows awaiting guardian approval — not built in Klonkt yet. */
+/** Gated follows awaiting guardian approval — not built in Klonkt yet (Fase 2). */
 export function followsCollection(id) {
   return collection(id, []);
 }
 
-/** The guardian's wards (accepted), with cached handle for display. */
+/** The guardian's committed wards, with cached handle for display. */
 export function wardsCollection(id, slug) {
   const items = relations.listWards(slug)
-    .filter((r) => r.status === 'accepted')
     .map((r) => ({ id: r.other_uri, 'shaer:handle': r.other_handle || undefined, since: r.created_at }));
   return collection(id, items);