Changeset 6eab7e9 in Klonkt for src/services/guardianship

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@…>

Location:

src/services/guardianship

Files:

• availability.js (added)
• delivery.js (modified) (2 diffs)
• gated.js (modified) (3 diffs)
• handshake.js (modified) (6 diffs)
• index.js (modified) (1 diff)
• notes.js (modified) (1 diff)
• queues.js (modified) (3 diffs)
• relations.js (modified) (1 diff)

src/services/guardianship/delivery.js

@@ -40 +40 @@
 // guardian on any instance receives it as a private mention (the ward
 // call-for-help path).
-export async function deliverDirectNote(site, { recipients, text, language, inReplyTo, attachments, helpRequest, wave }) {
+export async function deliverDirectNote(site, { recipients, text, language, inReplyTo, attachments, helpRequest, wave, awayUntil }) {
   const { actorId, fetchActor, deriveHandle, escHtml, linkUrls, linkHashtags,
           getOutboxRow, buildReplyNote, AP_CONTEXT, getOrCreateKeys, deliver, enqueueDelivery } = deps;
@@ -70 +70 @@
     .map((a) => ({ url: a.url, mediaType: String(a.mediaType), name: String(a.name || '').slice(0, 120) }));
   const id = crypto.randomUUID();
-  db.prepare(`INSERT INTO ap_outbox (id, site_slug, post_id, post_slug, in_reply_to, to_actor, to_handle, content, language, attachments, visibility, to_actors, help_request, wave, created_at)
-              VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,CURRENT_TIMESTAMP)`)
-    .run(id, site.slug, '', null, inReplyTo || null, resolved[0].uri, resolved[0].handle, content, lang, media.length ? JSON.stringify(media) : null, 'direct', JSON.stringify(resolved.map((r) => r.uri)), helpRequest ? 1 : 0, wave ? 1 : 0);
+  db.prepare(`INSERT INTO ap_outbox (id, site_slug, post_id, post_slug, in_reply_to, to_actor, to_handle, content, language, attachments, visibility, to_actors, help_request, wave, away_until, created_at)
+              VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,CURRENT_TIMESTAMP)`)
+    .run(id, site.slug, '', null, inReplyTo || null, resolved[0].uri, resolved[0].handle, content, lang, media.length ? JSON.stringify(media) : null, 'direct', JSON.stringify(resolved.map((r) => r.uri)), helpRequest ? 1 : 0, wave ? 1 : 0, awayUntil || null);
   const row = getOutboxRow(id);
   const note = buildReplyNote(base, site, row);

src/services/guardianship/gated.js

@@ -15 +15 @@
 import db from '../../config/database.js';
 import { listGuardians } from './relations.js';
+import * as availability from './availability.js';
 
 /** The window a gated-setting decision stays open. Reversible, so a day. */
@@ -67 +68 @@
   const column = featureColumn(feature);
   if (!column) return { state: 'expired', error: 'unknown_feature' };
-  const guardians = listGuardians(slug).map((g) => g.other_uri);
-  if (!guardians.includes(guardianUri)) return { state: 'expired', error: 'not_a_guardian' };
+  const all = listGuardians(slug).map((g) => g.other_uri);
+  if (!all.includes(guardianUri)) return { state: 'expired', error: 'not_a_guardian' };
+  // A vote is an answer, whatever it is a vote on (§3.6): the voter is
+  // restored first, so it always counts itself back into the set below.
+  availability.oneAnswer(guardianUri, Date.now());
+  // §3.5: the threshold runs over the AVAILABLE set. Membership is checked
+  // against the full list above: any guardian may answer, and answering is
+  // exactly what brings it back in.
+  const guardians = availability.availableSet(slug, all, Date.now());
 
   // The window opens with the first answer, and a stale decision starts over:
@@ -100 +108 @@
   const votes = db.prepare('SELECT guardian_uri, value FROM ap_gated_votes WHERE slug = ? AND feature = ?')
     .all(slug, feature);
-  const guardians = listGuardians(slug).map((g) => g.other_uri);
+  // Progress over the available set (§3.5), like the tally itself.
+  const guardians = availability.availableSet(slug, listGuardians(slug).map((g) => g.other_uri), Date.now());
   return { votes: votes.length, need: thresholdFor(guardians.length), of: guardians.length };
 }

src/services/guardianship/handshake.js

@@ -20 +20 @@
 import * as relations from './relations.js';
 import * as gated from './gated.js';
+import * as availability from './availability.js';
 
 let deps = null;
@@ -194 +195 @@
   if (!['Offer', 'Accept', 'Reject', 'Undo'].includes(type)) return null;
   const me = deps.selfId(site.slug);
+  // One answer restores everything (§3.6): any C2S activity from this actor
+  // is that answer, for every local ward it guards. Runs before anything is
+  // even looked at, so the target of a running lapse cancels it by doing
+  // anything at all — including trying to vote on it.
+  try { availability.oneAnswer(me, Date.now()); } catch { /* never load-bearing */ }
 
   // ── Undo: a guardian ends its own guardianship (§3.2). Same path as the
@@ -206 +212 @@
   // ── Offer: the local site is the guardian-candidate. ───────────────────
   if (type === 'Offer') {
+    // §3.6.3 over C2S: a guardian here proposes releasing a dormant
+    // co-guardian. A ward we host opens locally; a remote ward gets the
+    // proposal delivered, because the ward's server is the one that tallies
+    // and enforces (the §5.6 line: a guardian next door must not have more
+    // say than one far away).
+    const lp = availability.parseLapse(activity.object);
+    if (lp) {
+      const id = `${me}/lapses/${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`;
+      const wardSlug = deps.localSlug(lp.ward);
+      if (wardSlug) {
+        const r = availability.openLapse({ id, wardSlug, wardUri: lp.ward, target: lp.target, openedBy: me, now: Date.now() });
+        if (r.error) return { status: r.error === 'not_in_available_set' ? 403 : 409, error: r.error };
+        deps.deliverTo(site, lp.target, { id, type: 'Offer', actor: me, to: [lp.target], object: { type: 'shaer:Lapse', 'shaer:ward': lp.ward, object: lp.target } }).catch(() => { /* best-effort */ });
+        notify(wardSlug, { kind: 'lapse_opened', lapse: id, target: lp.target, set: r.set });
+        return { status: 202, id, url: id, 'shaer:set': r.set, 'shaer:threshold': r.threshold };
+      }
+      const offer = { id, type: 'Offer', actor: me, to: [lp.ward], object: { type: 'shaer:Lapse', 'shaer:ward': lp.ward, object: lp.target } };
+      const delivered = await fanout(site, [lp.ward], offer);
+      return { status: 202, id, url: id, delivered };
+    }
     const rel = parseRelationship(activity.object);
     if (!rel) return null;
@@ -231 +257 @@
   const offerId = idOf(activity.object);
   if (!offerId) return { status: 400, error: 'missing_offer' };
+  // A lapse vote over C2S (§3.6.3): the same Accept/Reject wire the offers
+  // and gated follows use, which is exactly why the Shaer clients need no
+  // new verbs for it.
+  if (availability.getLapse(offerId)) {
+    const r = availability.lapseVote(offerId, me, type === 'Accept', Date.now());
+    if (r && r.error) return { status: r.error === 'not_in_set' ? 403 : 409, error: r.error };
+    return { status: 202, id: offerId, url: offerId, 'shaer:outcome': 'open', 'shaer:accepts': r.accepts, 'shaer:threshold': r.threshold };
+  }
   let offer = offers.getOffer(site.slug, offerId);
   if (!offer) return { status: 404, error: 'no_such_offer' };
@@ -273 +307 @@
       const r = gated.recordGatedVote(site.slug, gs.feature, actor, gs.value);
       notify(site.slug, { kind: 'gated_setting', feature: gs.feature, value: gs.value, state: r.state });
+      return true;
+    }
+    // §3.6.3: a co-guardian proposes releasing a dormant guardian of THIS
+    // ward. The ward's server opens, tallies and (after the full window)
+    // executes, exactly as it does for the gated settings above.
+    const lp = availability.parseLapse(activity.object);
+    if (lp) {
+      if (lp.ward !== me) return false;   // not our ward
+      const id = idOf(activity) || `${me}/lapses/${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`;
+      const r = availability.openLapse({ id, wardSlug: site.slug, wardUri: me, target: lp.target, openedBy: actor, now: Date.now() });
+      if (r.error) {
+        notify(site.slug, { kind: 'lapse_refused', reason: r.error, target: lp.target });
+        return true;   // consumed: the refusal is the answer
+      }
+      // The target is notified like any dormancy marking (§3.6.2): in
+      // protocol (a copy of the Offer, so one answer can cancel it) AND the
+      // §6 handle, which for a committed guardian is its inbox — the same
+      // door this delivery knocks on.
+      deps.deliverTo(site, lp.target, activity).catch(() => { /* best-effort */ });
+      notify(site.slug, { kind: 'lapse_opened', lapse: id, target: lp.target, set: r.set });
       return true;
     }
@@ -304 +358 @@
     return true;
   }
+  // §3.6.3: a set member answering a running lapse. Irreversible, so even a
+  // full tally leaves it open until the window closes (§3.5); the completion
+  // happens lazily on reads (queues) once the window has run.
+  if (availability.getLapse(offerId)) {
+    const r = availability.lapseVote(offerId, actor, type === 'Accept', Date.now());
+    notify(site.slug, { kind: 'lapse_vote', lapse: offerId, by: actor, state: r && !r.error ? 'recorded' : (r && r.error) || 'refused' });
+    return true;
+  }
   let offer = offers.getOffer(site.slug, offerId);
   if (!offer) return false;

src/services/guardianship/index.js

@@ -16 +16 @@
  */
 export { SHAER_CONTEXT, GUARDIAN_RELATIONSHIP, GUARDIAN_RELATIONSHIP_COMPACT, isGuardianRelationship } from './context.js';
-export { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed } from './notes.js';
+export { helpRequestProps, isHelpRequest, waveProps, isWave, awayProps, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed } from './notes.js';
 export { wireDelivery, c2sVisibility, deliverDirectNote } from './delivery.js';
 export { wireHandshake, handleOutbox as handleGuardianshipOutbox, handleInbox as handleGuardianshipInbox, parseRelationship, parseUndoRelationship, endGuardianship } from './handshake.js';
-export { offersCollection, followsCollection, wardsCollection } from './queues.js';
+export { offersCollection, followsCollection, wardsCollection, guardiansCollection } from './queues.js';
+export * as availability from './availability.js';
+export { wireAvailability } from './availability.js';
 export * as follows from './follows.js';
 export { listForParty as listOffersForParty, getOffer, findOfferAnywhere } from './offers.js';

src/services/guardianship/notes.js

@@ -65 +65 @@
 }
 
-export default { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed };
+/** shaer:away (3.6.1): a guardian declaring itself away to its ward, with an
+ *  end. Rides a direct note like the help request, so a ward on a plain
+ *  server reads a human message; endTime is plain AS2. */
+export function awayProps(post) {
+  return (post && post.visibility === 'direct' && post.away_until)
+    ? { 'shaer:away': true, endTime: new Date(post.away_until).toISOString() }
+    : {};
+}
+
+export default { helpRequestProps, isHelpRequest, waveProps, isWave, awayProps, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed };

src/services/guardianship/queues.js

@@ -11 +11 @@
 import * as offers from './offers.js';
 import * as relations from './relations.js';
+import * as availability from './availability.js';
 
 const collection = (id, items) => ({
@@ -16 +17 @@
 });
 
-/** Pending offers where the local site is a party, each with its accept tally. */
+/** Pending offers where the local site is a party, each with its accept
+ *  tally. The same collection carries the running lapses (§3.6.3) this
+ *  account is a party to, exactly as the daemon serves them, so the Shaer
+ *  clients render both without a second fetch. */
 export function offersCollection(id, slug, me) {
   const items = offers.listForParty(slug, me).map((o) => offers.queueItem(o, me));
+  items.push(...availability.lapseQueueItems(slug, me, Date.now()));
   return collection(id, items);
 }
@@ -34 +39 @@
 }
 
-export default { offersCollection, followsCollection, wardsCollection };
+/** The ward's guardians with their availability (§3.6.1: never public,
+ *  owner-only): the real size of the safety net. Same shape as the daemon. */
+export function guardiansCollection(id, slug) {
+  const uris = relations.listGuardians(slug).map((r) => r.other_uri);
+  return collection(id, availability.statusesFor(slug, uris, Date.now()));
+}
+
+export default { offersCollection, followsCollection, wardsCollection, guardiansCollection };

src/services/guardianship/relations.js

@@ -74 +74 @@
       follows: `${id}/queues/follows`,
       wards: `${id}/queues/wards`,
+      guardians: `${id}/queues/guardians`,
     },
   };