Changeset 6eab7e9 in Klonkt for src/services/ActivityPubService.js

Timestamp:

07/28/2026 11:22:07 PM (6 weeks ago)

Author:

Robin Genis <roboburr@…>

Branches:

main

Children:

0202104

Parents:

6c152a5

Message:

Beschikbaarheid van guardians (FEP-633c 3.6): away, dormant, lapse

De Klonkt-kant van het beschikbaarheidsvoorstel, nagemaakt zoals eerst in de
daemon gevalideerd (shaer-8z7): dezelfde toestanden, dezelfde regels, dezelfde
weigeringen. De spiegel-tests dragen dezelfde namen als de daemon-tests, zodat
drift tussen de twee backends opvalt als een falende test met dezelfde woorden.

De kern is guardianship/availability.js: drie toestanden per (ward, guardian),
met als regel boven alles dat een antwoord alles herstelt, tot en met een
lopende lapse. Elke geverifieerde inbox-activiteit en elke C2S-handeling van
een guardian herstelt hem en annuleert een lapse tegen hem, nog voor er naar de
activiteit gekeken wordt. Bewust achter de handtekening-poort: een ongeverifieerde
bewering oma te zijn mag oma niet wakker maken.

Afwezig komt binnen over beide wegen: S2S als directe note met shaer:away en
endTime van een guardian elders (het gewone geval), en C2S als een guardian
hier zich afmeldt; die note draagt de marker mee naar wards elders en wordt
voor wards op deze instance direct toegepast, want een lokale inbox ontvangt
zijn eigen bezorging niet. Zonder (toekomstig) einde faalt het luid met 400,
precies zoals de daemon weigert.

Slapend volgt alleen uit onbeantwoorde direct geadresseerde verzoeken; de
follow-gating registreert die nu als bewijs. De markering notificeert verplicht
via protocol en de 6-handle, eenmalig op de overgang, centraal bedraad zodat
elke plek waar een promotie kan gebeuren hetzelfde notificeert.

De drempel van 3.5 rekent voortaan over de beschikbare set: de follow-quorums
en de gated settings allebei. De test die het waarom draagt: vijf guardians van
wie twee weg zijn gaven een drempel van drie die de twee levenden nooit haalden;
over de beschikbare set beslissen zij weer.

De lapse loopt over dezelfde draden als de gated settings: een Offer van
shaer:Lapse opent op de server van het kind, Accept/Reject stemt, het venster
loopt altijd vol, en de voltooiing verwijdert de relatie met de
nooit-leeg-grens uit 3.4 als tweede slot eronder. De offers-queue draagt de
lopende lapses en de nieuwe owner-only guardians-queue de beschikbaarheid, in
precies de vorm die de daemon serveert, dus de Shaer-apps van gisteren werken
zonder wijziging.

Changed files:
src/config/database.js

• tabellen ap_guardian_attention, ap_attention_requests, ap_lapses
• kolom ap_outbox.away_until

src/services/guardianship/handshake.js

• Offer van shaer:Lapse (S2S en C2S), lapse-stemmen op Accept/Reject, one-answer op elke C2S-handeling

src/services/guardianship/gated.js

• tally en voortgang over de beschikbare set; een stem is een antwoord

src/services/guardianship/notes.js

• awayProps: shaer:away plus endTime op de uitgaande directe note

src/services/guardianship/delivery.js

• away_until door het directe pad heen

src/services/guardianship/queues.js

• guardiansCollection; offersCollection draagt de lapses

src/services/guardianship/index.js

• exports

src/services/ActivityPubService.js

• one-answer achter de handtekening-poort
• away-ingest op het mention-pad en het C2S-directe pad
• dormancy-bewijs op de follow-gating; quorum over de beschikbare set
• de notificatieplicht van 3.6.2, een keer bedraad
• buildReplyNote draagt awayProps

src/routes/activitypub.js

• owner-only route /queues/guardians

src/routes/guardian.js

• dashboard-besluit is een antwoord; quorum over de beschikbare set

src/services/guardianship/relations.js

• guardians-queue aangekondigd in shaer:queues

test/activitypub-as2.test.js

• guardians toegevoegd aan de queue-sleutels

New file:
src/services/guardianship/availability.js

• de toestandsmachine, de lapse en de endTime-parser

test/availability.test.js

• veertien spiegel-tests van de daemon, tot en met de volle lapse-flow over de S2S-draad en het vijf-guardians-rekenvoorbeeld

remarks: de PWA toont de beschikbaarheid nog niet (chips in het paneel per
kind en een lapse-kaart komen apart); de echte kruis-implementatie-testbank
blijft open op shaer-6d9. Klonkt heeft geen pinbare klok zoals de daemon; de
tests dateren bewijs terug in plaats van de tijd vooruit te zetten, en dat
staat er als kanttekening bij. Niet uitgerold.

-robo
Co-Authored-By: Claude Fable 5 <noreply@…>

File:

• src/services/ActivityPubService.js (modified) (7 diffs)

src/services/ActivityPubService.js

@@ -288 +288 @@
       ...Guardianship.helpRequestProps(post),
       ...Guardianship.waveProps(post),
+      ...Guardianship.awayProps(post),
       // FEP-633c §2.2: object hint that the author is a ward.
       ...Guardianship.hasGuardiansProps(site.slug),
@@ -1365 +1366 @@
       return 401;
     }
+    // One answer restores everything (FEP-633c 3.6): any VERIFIED activity
+    // from an actor that guards someone here restores it to active for those
+    // wards and cancels any lapse running against it, before the activity is
+    // even looked at. Signature-gated on purpose: an unverified claim of
+    // being gran must not wake gran up.
+    try {
+      const ev = Guardianship.availability.oneAnswer(claimedActor, Date.now());
+      if (ev.restored.length) console.log('[AP] guardian restored (one answer, 3.6):', claimedActor, '→', ev.restored.join(', '));
+      for (const c of ev.cancelledLapses) console.log('[AP] lapse cancelled by an answer from its target:', c.id);
+    } catch { /* availability is never load-bearing for delivery */ }
   }
 
@@ -1454 +1465 @@
       const wardKeys = getOrCreateKeys(slug);
       const followObj = { id: followId, type: 'Follow', actor: who, object: wardActor };
+      // Dormancy evidence (FEP-633c 3.6.2): this decision directly addresses
+      // every guardian. The ONLY admissible evidence is a request like this
+      // one going unanswered; recordRequest itself skips a declared absence.
+      for (const g of wardGuardians) {
+        try { Guardianship.availability.recordRequest(slug, g, followId, Date.now()); } catch { /* never load-bearing */ }
+      }
       for (const g of wardGuardians) {
         // Local ONLY when the guardian lives on THIS instance: slugFromActorUrl
@@ -1637 +1654 @@
         const wave = Guardianship.isWave(o);
         const hasG = Guardianship.objectHasGuardians(o);   // §2.2 hint, register-only
+        // FEP-633c 3.6.1: a guardian declares itself away to its ward, on the
+        // same direct note the mention below stores (so the kid also reads it
+        // as an ordinary message). Recorded only from an actual guardian of
+        // the addressed ward, and only with an end: an absence without an end
+        // is logged and dropped, never guessed.
+        if (Guardianship.availability.isAway(o)) {
+          const until = Guardianship.availability.parseEndTime(o.endTime);
+          for (const slug of slugs) {
+            const isG = (() => { try { return Guardianship.listGuardians(slug).some((g) => g.other_uri === actorUri); } catch { return false; } })();
+            if (!isG) continue;
+            if (!until || until <= Date.now()) { console.warn('[AP] away without a (future) end ignored (3.6.1):', actorUri, '→', slug); continue; }
+            Guardianship.availability.declareAway(slug, actorUri, until);
+            console.log('[AP] guardian declared away (3.6.1):', actorUri, '→', slug, 'until', new Date(until).toISOString());
+          }
+        }
         for (const slug of slugs) {
           try {
@@ -2213 +2245 @@
             .filter(Boolean);
           const help = object['shaer:helpRequest'] === true || object.helpRequest === true;
-          const r = await deliverDirectNote(site, { recipients, text: plain, language: object.language || null, inReplyTo: typeof object.inReplyTo === 'string' ? object.inReplyTo : null, attachments: atts, helpRequest: help });
+          // FEP-633c 3.6.1: a guardian here declaring itself away to its
+          // wards. An away without a (future) end fails loudly, exactly as
+          // the daemon refuses it: stored quietly it would be a nominal
+          // guardian holding a seat.
+          let awayUntil = null;
+          if (Guardianship.availability.isAway(object)) {
+            awayUntil = Guardianship.availability.parseEndTime(object.endTime);
+            if (!awayUntil || awayUntil <= Date.now()) return { status: 400, error: 'away_needs_an_end' };
+            // A ward we host ourselves never receives its own delivery
+            // (private ranges, loopback): apply locally, the way the
+            // handshake commit does.
+            const meUri = selfActorId(site.slug);
+            for (const uri of recipients) {
+              const wslug = uri.startsWith(`${base}/`) ? slugFromActorUrl(uri) : null;
+              if (wslug && Guardianship.listGuardians(wslug).some((g) => g.other_uri === meUri)) {
+                Guardianship.availability.declareAway(wslug, meUri, awayUntil);
+              }
+            }
+          }
+          const r = await deliverDirectNote(site, { recipients, text: plain, language: object.language || null, inReplyTo: typeof object.inReplyTo === 'string' ? object.inReplyTo : null, attachments: atts, helpRequest: help, awayUntil });
           if (!r || !r.id) return { status: 502, error: 'direct_failed' };
           return { status: 201, id: r.id, url: `${base}/ap/notes/${r.id}` };
@@ -3439 +3490 @@
   const pending = Guardianship.follows.getPending(followId);
   if (!pending) return false;
-  const guardians = Guardianship.listGuardians(pending.ward_slug).map((g) => g.other_uri);
-  if (!guardians.includes(actorUri)) return false;   // only a real guardian of this ward decides
+  const allGuardians = Guardianship.listGuardians(pending.ward_slug).map((g) => g.other_uri);
+  if (!allGuardians.includes(actorUri)) return false;   // only a real guardian of this ward decides
   const decision = type === 'Reject' ? 'reject' : 'approve';
+  // §3.5: the quorum runs over the AVAILABLE set. The voter itself was
+  // restored by the one-answer rule when its activity arrived, so answering
+  // is exactly what counts a guardian back in.
+  const guardians = Guardianship.availability.availableSet(pending.ward_slug, allGuardians, Date.now());
   const r = Guardianship.follows.decide(followId, actorUri, decision, guardians);
   try {
@@ -3784 +3839 @@
 });
 
+// The notification duty of FEP-633c 3.6.2, wired once for every place a
+// dormancy promotion can happen (queue reads, fan-outs, tallies): marking a
+// guardian dormant MUST notify it, in protocol AND over the §6 handle. The
+// one-answer rule is worthless to someone who does not know an answer is
+// wanted. The handle of a committed guardian is its inbox (§6 minimum), which
+// is the same door this delivery knocks on; both attempts are logged.
+Guardianship.wireAvailability({
+  onDormant: (wardSlug, guardianUri) => {
+    const base = (process.env.PUBLIC_BASE_URL || '').replace(/\/+$/, '');
+    const site = db.prepare('SELECT * FROM sites WHERE slug = ?').get(wardSlug);
+    if (!base || !site) return;
+    const me = selfActorId(wardSlug);
+    const note = {
+      id: `${me}/dormant/${Date.now().toString(36)}${rid()}`,
+      type: 'Note', attributedTo: me, to: [guardianUri],
+      'shaer:dormant': true,
+      content: '<p>You have been observed dormant as a guardian. Nothing is wrong and nothing is held against you: one answer restores everything (FEP-633c 3.6.2).</p>',
+    };
+    deliverToActor(site, guardianUri, { id: `${note.id}#create`, type: 'Create', actor: me, to: [guardianUri], object: note })
+      .catch(() => { /* retried by the queue */ });
+    console.log('[AP] guardian observed dormant (3.6.2):', guardianUri, 'ward', wardSlug, '(notified in protocol; the §6 handle is the same inbox)');
+  },
+});
+
 export default {
   AP_CONTEXT, getOrCreateKeys, apWants, sendAP, actorId, noteId,