Changeset 30d0e2c in Klonkt

Timestamp:

08/03/2026 06:38:16 AM (5 weeks ago)

Author:

Bart <bart@…>

Branches:

main

Children:

3d882bd

Parents:

69bd747

Message:

Een handshake blijft een week open, en faalt daarna onder zijn eigen naam

§4.2 leunt erop dat het uitstel begrensd is: als het venster sluit met de
controle nog onbeslist, faalt de beslissing dicht. Alleen had een
guardianship-offer in Klonkt helemaal geen venster, dus "uitgesteld" was
"voor altijd".

Nu een week. Lang genoeg dat niemand wordt opgejaagd — er moeten een ward, een
kandidaat en alle bestaande guardians antwoorden, en dat zijn mensen — en kort
genoeg dat een vergeten aanbod niet een maand in de wachtrij van een kind staat
alsof het nog een keuze is.

Twee eindtoestanden, want het zijn twee verschillende feiten:
'expired' (niemand heeft geantwoord; zegt niets over de kandidaat) en
'unverified' (iedereen heeft geantwoord, maar de kandidaat was nooit op te
halen). Geen van beide is 'void': de partijen mag niet verteld worden dat de
kandidaat geweigerd is, want dat is niet gebeurd — er heeft alleen nooit iemand
kunnen kijken.

Vervallen gebeurt bij het lezen, zoals een lapse dat ook doet: geen sweeper die
niemand draait. En het lezen van de wachtrij is meteen het moment waarop een
uitgestelde commit opnieuw wordt geprobeerd (§4.2 SHOULD) — nodig, want de
laatste Accept kan al binnen zijn en dan port niemand er ooit nog aan. Niet
awaited: een poll toont wat nu waar is.

Co-Authored-By: Claude Opus 5 <claude@…>

Files:

• src/services/guardianship/handshake.js (modified) (1 diff)
• src/services/guardianship/offers.js (modified) (2 diffs)
• src/services/guardianship/queues.js (modified) (2 diffs)
• test/guardianship.test.js (modified) (1 diff)

src/services/guardianship/handshake.js

@@ -545 +545 @@
 }
 
+/**
+ * §4.2 SHOULD: retry the dereference for handshakes left deferred because the
+ * candidate could not be read.
+ *
+ * Waiting for a further activity from a party is not enough: the commit is
+ * triggered by the LAST `Accept`, so if that one has already arrived nothing
+ * will ever poke it again and the handshake would sit until its window closed.
+ * The ward's dashboard polling its own offers queue is this instance's
+ * schedule, exactly as a read settles a lapse (§3.6.3).
+ *
+ * Deliberately not awaited by the read: a poll should render what is true now,
+ * not block on someone else's slow server. A retry that succeeds shows up in
+ * the next poll, which is the same second or two later.
+ */
+export async function retryDeferred(slug) {
+  for (const o of offers.listDeferred(slug)) {
+    await maybeCommit(slug, o.offer_id).catch(() => { /* next poll tries again */ });
+  }
+}
+
 function notify(slug, ev) {
   try { if (deps && typeof deps.onEvent === 'function') deps.onEvent(slug, ev); } catch { /* best-effort */ }
 }
 
-export default { wireHandshake, handleOutbox, handleInbox, parseRelationship, parseUndoRelationship, endGuardianship };
+export default { wireHandshake, handleOutbox, handleInbox, parseRelationship, parseUndoRelationship, endGuardianship, retryDeferred };

src/services/guardianship/offers.js

@@ -79 +79 @@
 }
 
-/** Pending offers where `me` is a party — the offers queue (daemon shape). */
-export function listForParty(slug, me) {
-  return stmts().listBySlug.get ? stmts().listBySlug.all(slug).filter((o) => isParty(o, me)) : [];
+/**
+ * How long a guardianship handshake stays open (§3.5). Adding a guardian is a
+ * reversible decision, but not a quick one: the ward, the candidate and every
+ * existing guardian have to answer, and they are people, sometimes on holiday.
+ * A week is long enough that nobody is rushed and short enough that a forgotten
+ * offer does not sit in a child's queue for a month looking like a live choice.
+ */
+export const OFFER_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** SQLite writes CURRENT_TIMESTAMP as UTC 'YYYY-MM-DD HH:MM:SS', which
+ *  Date.parse reads as LOCAL time — hours out, and enough to expire an offer
+ *  early or late. Same correction as ActivityPubService.isoStamp. */
+const stampMs = (v) => {
+  const s = String(v || '');
+  return Date.parse(/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}$/.test(s) ? `${s.replace(' ', 'T')}Z` : s);
+};
+
+export const closesAt = (o) => stampMs(o.created_at) + OFFER_WINDOW_MS;
+
+/**
+ * §3.5 fails closed: once the window has run, a handshake that never completed
+ * is over. WHICH failure it was matters (§4.2), so the two get different
+ * terminal states and neither of them is `void`:
+ *
+ *   'expired'     — the parties never all answered. Nothing to say about anyone.
+ *   'unverified'  — everyone answered; the candidate could never be read, so
+ *                   the check never got to run. The parties MUST be told this
+ *                   and MUST NOT be told the candidate was refused. It was not:
+ *                   nobody ever managed to look.
+ */
+export function expireIfDue(slug, offerId, now = Date.now()) {
+  const o = stmts().getOffer.get(slug, offerId);
+  if (!o || o.status !== 'pending') return null;
+  const due = closesAt(o);
+  if (!Number.isFinite(due) || due > now) return null;
+  const status = readyToCommit(o) ? 'unverified' : 'expired';
+  stmts().setStatus.run(status, null, slug, offerId);
+  return { ...o, status };
+}
+
+/** Pending offers where `me` is a party — the offers queue (daemon shape).
+ *  Reads are where lazy completion happens, as with the lapses (§3.6.3): a
+ *  closed window is settled here rather than by a sweeper nobody runs. */
+export function listForParty(slug, me, now = Date.now()) {
+  if (!stmts().listBySlug.get) return [];
+  for (const o of stmts().listBySlug.all(slug)) expireIfDue(slug, o.offer_id, now);
+  return stmts().listBySlug.all(slug).filter((o) => isParty(o, me));
+}
+
+/** Handshakes whose tally is complete but which are not committed: the §4.2
+ *  deferred set, waiting on a candidate nobody could dereference. */
+export function listDeferred(slug) {
+  if (!stmts().listBySlug.get) return [];
+  return stmts().listBySlug.all(slug).filter((o) => readyToCommit(o));
 }
 
@@ -109 +160 @@
   start, getOffer, findOfferAnywhere, recordAccept, recordReject, commit,
   readyToCommit, listForParty, queueItem, parties, isParty, acceptsOf,
+  OFFER_WINDOW_MS, closesAt, expireIfDue, listDeferred,
 };

src/services/guardianship/queues.js

@@ -12 +12 @@
 import * as relations from './relations.js';
 import * as availability from './availability.js';
+import * as handshake from './handshake.js';
 
 const collection = (id, items) => ({
@@ -22 +23 @@
  *  clients render both without a second fetch. */
 export function offersCollection(id, slug, me) {
+  // §4.2: a handshake whose candidate could not be dereferenced is deferred,
+  // not decided, and the last Accept may already have landed — so nothing else
+  // would ever retry it. This poll is the schedule. Not awaited: the read
+  // answers with what is true now, and a retry that succeeds surfaces in the
+  // next one. `listForParty` settles closed windows on the way past.
+  handshake.retryDeferred(slug).catch(() => { /* the next read tries again */ });
   const items = offers.listForParty(slug, me).map((o) => offers.queueItem(o, me));
   items.push(...availability.lapseQueueItems(slug, me, Date.now()));

test/guardianship.test.js

@@ -187 +187 @@
   );
   assert.deepEqual(G.listGuardians('zed'), []);
+});
+
+test('an unreadable candidate defers the commit, and the window names that failure (§4.2)', async () => {
+  const offers = await import('../src/services/guardianship/offers.js');
+  const noor = site('s16', 'noor');
+  const NOOR = A('noor');
+  const MARA = 'https://elders.example/users/mara';   // remote; fetchActor returns null here
+  const offerId = `${MARA}/offers/m1`;
+
+  // The Offer arrives and is STORED: unreachable is not malformed, and
+  // refusing on a failed fetch would let any outage block an adoption.
+  const taken = await G.handleGuardianshipInbox(noor, {
+    id: offerId, type: 'Offer', actor: MARA, to: [NOOR],
+    object: { type: 'Relationship', subject: NOOR, relationship: 'shaer:Guardian', object: MARA },
+  });
+  assert.equal(taken, true);
+
+  // Noor accepts. Free ward + candidate's own offer = the tally is complete,
+  // so this WOULD commit — except the candidate cannot be read.
+  const done = await G.handleGuardianshipOutbox(noor, { type: 'Accept', object: offerId });
+  assert.equal(done.committed, false, 'not committed: nobody verified the candidate');
+  assert.ok(!done.refused, 'and not refused either — that would blame a candidate nobody could look at');
+  assert.deepEqual(G.listGuardians('noor'), []);
+  assert.equal(offers.getOffer('noor', offerId).status, 'pending', 'deferred, not decided');
+
+  // A week later the §3.5 window closes and it fails closed — under its own
+  // name. Not 'void': the parties must not be told the candidate was refused.
+  const later = Date.now() + offers.OFFER_WINDOW_MS + 1000;
+  offers.expireIfDue('noor', offerId, later);
+  assert.equal(offers.getOffer('noor', offerId).status, 'unverified');
+
+  const q = G.offersCollection(`${NOOR}/queues/offers`, 'noor', NOOR).orderedItems;
+  assert.deepEqual(q.filter((o) => o.id === offerId), [], 'and it stops looking like a live choice');
+});
+
+test('a handshake nobody finished expires under a different name (§3.5)', async () => {
+  const offers = await import('../src/services/guardianship/offers.js');
+  const finn = site('s17', 'finn');
+  const iris = site('s18', 'iris');
+  const [FINN, IRIS] = [A('finn'), A('iris')];
+
+  const off = await G.handleGuardianshipOutbox(finn, {
+    type: 'Offer', object: { type: 'Relationship', subject: IRIS, relationship: 'shaer:Guardian', object: FINN },
+  });
+  // Iris never answers. Reading the queue after the window settles it.
+  G.offersCollection(`${IRIS}/queues/offers`, 'iris', IRIS);          // still open now
+  assert.equal(offers.getOffer('iris', off.id).status, 'pending');
+  offers.listForParty('iris', IRIS, Date.now() + offers.OFFER_WINDOW_MS + 1000);
+  assert.equal(offers.getOffer('iris', off.id).status, 'expired',
+    'nobody answered — that says nothing about the candidate, so it is not "unverified"');
 });