Changeset 780a7c6 in Klonkt for src/services/guardianship/relations.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/relations.js (modified) (5 diffs)

src/services/guardianship/relations.js

@@ -1 +1 @@
 /**
- * Guardianship (FEP-633c) — the ward ↔ guardian relations (ap_guardianships).
- *
- * Every row is one relation seen from a LOCAL site: role 'guardian' means the
- * site guards `other_uri` (a ward, possibly remote); role 'ward' means
- * `other_uri` guards the site. A local ward with a local guardian yields two
- * rows, one per perspective — intentional, each side reads its own.
- *
- * The handshake (spec §3): the guardian-candidate — and only the candidate —
- * Offers a Relationship {subject: ward, relationship: shaer:Guardian,
- * object: candidate}; the ward Accepts (or Rejects). Status walks
- * 'offered' → 'accepted'; a Reject deletes the row.
+ * Guardianship (FEP-633c) — the COMMITTED ward ↔ guardian relations
+ * (ap_guardianships). Pending offers live in offers.js; a row here means the
+ * handshake committed (§3.1.4). Every row is one relation seen from a LOCAL
+ * site: role 'guardian' = the site guards other_uri; role 'ward' = other_uri
+ * guards the site.
  */
 import db from '../../config/database.js';
@@ -18 +12 @@
   if (!_s) {
     _s = {
-      ins: db.prepare(`INSERT OR IGNORE INTO ap_guardianships (slug, role, other_uri, other_handle, status, offer_id, created_at)
-                       VALUES (?,?,?,?,?,?,CURRENT_TIMESTAMP)`),
-      accept: db.prepare(`UPDATE ap_guardianships SET status='accepted' WHERE slug=? AND role=? AND other_uri=?`),
+      commit: db.prepare(`INSERT INTO ap_guardianships (slug, role, other_uri, other_handle, status, offer_id, created_at)
+                          VALUES (?,?,?,?, 'accepted', ?, CURRENT_TIMESTAMP)
+                          ON CONFLICT(slug, role, other_uri) DO UPDATE SET status='accepted', offer_id=excluded.offer_id`),
       del: db.prepare('DELETE FROM ap_guardianships WHERE slug=? AND role=? AND other_uri=?'),
-      bySlugRole: db.prepare('SELECT * FROM ap_guardianships WHERE slug=? AND role=? ORDER BY created_at DESC'),
+      bySlugRole: db.prepare("SELECT * FROM ap_guardianships WHERE slug=? AND role=? AND status='accepted' ORDER BY created_at DESC"),
       one: db.prepare('SELECT * FROM ap_guardianships WHERE slug=? AND role=? AND other_uri=?'),
-      byOffer: db.prepare('SELECT * FROM ap_guardianships WHERE offer_id=?'),
     };
   }
@@ -33 +26 @@
 
 /** Accepted guardian URIs of a local ward (feeds shaer:guardians). */
-export function listGuardians(slug) {
-  return stmts().bySlugRole.all(slug, 'ward').filter((r) => r.status === 'accepted');
+export function listGuardians(slug) { return stmts().bySlugRole.all(slug, 'ward'); }
+
+/** Accepted wards of a local guardian (the wards queue). */
+export function listWards(slug) { return stmts().bySlugRole.all(slug, 'guardian'); }
+
+/** A site is a guardian once it stands in any accepted guardian relation. */
+export function isGuardian(slug) { return listWards(slug).length > 0; }
+
+export function getRelation(slug, role, otherUri) { return stmts().one.get(slug, role, otherUri); }
+
+// ── Writes (only the handshake commit lands here) ────────────────────────
+
+/** The local ward gains a guardian (commit, §3.1.4). */
+export function commitGuardianForWard(wardSlug, guardianUri, { handle = null, offerId = null } = {}) {
+  stmts().commit.run(wardSlug, 'ward', guardianUri, handle, offerId);
+  return stmts().one.get(wardSlug, 'ward', guardianUri);
 }
 
-/** All ward relations of a local guardian (accepted + pending offers). */
-export function listWards(slug) {
-  return stmts().bySlugRole.all(slug, 'guardian');
+/** The local guardian gains a ward (commit, §3.1.4). */
+export function commitWardForGuardian(guardianSlug, wardUri, { handle = null, offerId = null } = {}) {
+  stmts().commit.run(guardianSlug, 'guardian', wardUri, handle, offerId);
+  return stmts().one.get(guardianSlug, 'guardian', wardUri);
 }
 
-/** Pending offers where the local site is a party (either side). */
-export function listOffers(slug) {
-  return [...stmts().bySlugRole.all(slug, 'guardian'), ...stmts().bySlugRole.all(slug, 'ward')]
-    .filter((r) => r.status === 'offered');
-}
-
-/** A site is a guardian once it stands in any guardian-side relation. */
-export function isGuardian(slug) {
-  return stmts().bySlugRole.all(slug, 'guardian').length > 0;
-}
-
-export function getRelation(slug, role, otherUri) { return stmts().one.get(slug, role, otherUri); }
-export function findByOfferId(offerId) { return offerId ? stmts().byOffer.all(offerId) : []; }
-
-// ── Writes (the handshake walks through these) ───────────────────────────
-
-/** Record an outgoing/incoming Offer on the local side with `role`. */
-export function recordOffer(slug, role, otherUri, { handle = null, offerId = null } = {}) {
-  stmts().ins.run(slug, role, otherUri, handle, 'offered', offerId);
-  return stmts().one.get(slug, role, otherUri);
-}
-
-/** The ward said yes (or our own offer was accepted): relation becomes real. */
-export function acceptRelation(slug, role, otherUri) {
-  stmts().accept.run(slug, role, otherUri);
-  return stmts().one.get(slug, role, otherUri);
-}
-
-/** Reject / retract / end a relation: the row disappears. */
+/** End a relation locally (Undo, §3.2 — federation of the Undo is Fase 4). */
 export function removeRelation(slug, role, otherUri) {
   stmts().del.run(slug, role, otherUri);
@@ -79 +59 @@
 
 /**
- * The guardianship properties for a local actor doc. `id` is the actor URI.
- * - shaer:guardians: accepted guardians of this ward (omitted when none)
+ * Guardianship props for a local actor doc. `id` is the actor URI.
+ * - shaer:guardians: accepted guardians of this ward (omitted when none, §2.1)
  * - shaer:isGuardian: true once the site guards anyone
- * - shaer:queues: the owner-only dashboard collections (always advertised,
- *   like `blocked`: clients discover, the routes enforce auth)
+ * - shaer:queues: the owner-only dashboard collections
+ *
+ * §1 mutual exclusion: a ward (has guardians) is never a guardian, so
+ * shaer:isGuardian is suppressed if guardians exist; the offer path already
+ * bars a ward from offering.
  */
 export function actorProps(id, slug) {
@@ -94 +77 @@
   };
   const guardians = listGuardians(slug).map((r) => r.other_uri);
-  if (guardians.length) props['shaer:guardians'] = guardians;
-  if (isGuardian(slug)) props['shaer:isGuardian'] = true;
+  if (guardians.length) {
+    props['shaer:guardians'] = guardians;   // a ward
+  } else if (isGuardian(slug)) {
+    props['shaer:isGuardian'] = true;        // a guardian (never both, §1)
+  }
   return props;
 }
 
 export default {
-  listGuardians, listWards, listOffers, isGuardian, getRelation, findByOfferId,
-  recordOffer, acceptRelation, removeRelation, actorProps,
+  listGuardians, listWards, isGuardian, getRelation,
+  commitGuardianForWard, commitWardForGuardian, removeRelation, actorProps,
 };