@mmmbuto/nexuscrew 0.9.57 → 0.9.59

package/lib/notify/ask-relay.js

@@ -14,12 +14,62 @@
 // refused locally until verification resolves the attempt.
 
 const crypto = require('node:crypto');
+const { NODE_NAME_RE } = require('../nodes/store.js');
 const { probeReverseSlot } = require('../nodes/reverse-slot-proof.js');
-const IDLE_MS = 15000;
+const { askSlotVerifier, binding } = require('../nodes/ask-slot-verifier.js');
+const RELAY_DEADLINE_MS = 8000;
+const OWNER_REASONS = new Set([
+  'reverse-slot-unverified', 'peer-unknown', 'events-disabled', 'grant-required:ask-action',
+  'peer-visibility', 'origin-visibility', 'federated-origin-required', 'hop-chain',
+  'store-unavailable', 'unknown-peer', 'unknown-trust', 'no-delivering-peer',
+  'no-node-identity', 'bad-visited', 'bad-hop', 'self-hop', 'bad-attested-cell',
+  'origin-mismatch', 'fleet-unavailable', 'cell-not-active', 'answer-rate',
+  'unknown', 'dismissed', 'answering', 'answered', 'store-unreadable',
+  'delivery-unknown-block', 'already-delivered', 'paste-failed', 'bad-request-id',
+  'no-receipts', 'request-conflict', 'receipt-cap', 'federation-peer-unreachable',
+  'federation-peer-timeout', 'federation-body-consumed', 'generation-mismatch', 'invalid-generation', 'unsupported',
+]);
+function safeReason(reason) { return OWNER_REASONS.has(reason) ? reason : undefined; }
 
-function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = () => {}, probeReverseSlotImpl = probeReverseSlot } = {}) {
+function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = () => {}, probeReverseSlotImpl = probeReverseSlot, peers = null, localPort = () => 0, localToken = () => '', nodesPath = null, availabilityBinding = () => null, slotVerifier = askSlotVerifier } = {}) {
   // (ownerId|askId|requestId) -> {state: 'sent'|'committed'|'failed'|'uncertain', requestId}
+  const channelObservations = new Map();
   const attempts = new Map();
+  const answerFlights = new Map();
+
+  const proofScope = nodesPath || loadStore;
+  function deadlineResult(op, args, capability) {
+    if (capability) return { ownerId: args.ownerId, askId: args.askId, canReply: false, status: 'unreachable', reason: 'relay-deadline' };
+    if (op.answer && op.delivered && args.rid) {
+      return { ok: false, code: 200, uncertain: true, requestId: args.rid, reason: 'delivery-unknown', error: 'esito incerto: verifica lo stato prima di rispondere' };
+    }
+    return { ok: false, code: 504, reason: 'relay-deadline', error: 'relay deadline' };
+  }
+  async function operation(args, work, capability = false, answer = false) {
+    const controller = new AbortController();
+    const op = { controller, answer, delivered: false, expired: false, proofKey: null, proofBinding: null };
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => { rejectAbort = () => reject(new Error('relay deadline')); });
+    controller.signal.addEventListener('abort', rejectAbort, { once: true });
+    op.active = () => !controller.signal.aborted;
+    op.check = () => { if (!op.active()) throw new Error('relay deadline'); };
+    op.wait = promise => Promise.race([promise, aborted]);
+    const timer = setTimeout(() => { op.expired = true; controller.abort(); }, RELAY_DEADLINE_MS);
+    try { return await Promise.race([Promise.resolve().then(() => work(op)), aborted]); }
+    catch (_) {
+      slotVerifier.invalidate(op.proofKey);
+      if (op.answer && op.delivered && args.rid) {
+        const entry = attempts.get(attemptKey(args.ownerId, args.askId, args.rid));
+        if (entry) entry.state = 'uncertain';
+      }
+      if (op.expired) return deadlineResult(op, args, capability);
+      return capability
+        ? { ownerId: args.ownerId, askId: args.askId, canReply: false, status: 'unreachable' }
+        : { ok: false, code: 502, error: 'owner unreachable' };
+    } finally {
+      clearTimeout(timer); controller.signal.removeEventListener('abort', rejectAbort); controller.abort();
+    }
+  }
 
   function requestId() { return crypto.randomUUID(); }
 
@@ -28,52 +78,103 @@ function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = ()
   // attivo. Per gli inbound la porta dello slot DEVE essere verificata con la
   // stessa sonda dei terminali (secret del peer + instanceId atteso): nessun
   // fallback sulla localPort senza proof.
-  function candidateOwner(ownerId) {
-    const store = loadStore();
+  async function candidateOwner(ownerId, op) {
+    let store = loadStore();
     if (!store) return null;
+    let routed = null;
+    if (typeof peers === 'function') {
+      let inventory;
+      try { inventory = await op.wait(peers()); } catch (_) { op.check(); return null; }
+      op.check();
+      const matches = (Array.isArray(inventory) ? inventory : [])
+        .filter((p) => p && (p.nodeId === ownerId || p.instanceId === ownerId));
+      if (matches.length !== 1 || matches[0].stale === true) return null;
+      const route = matches[0].route;
+      if (!Array.isArray(route) || !route.length || route.length > 4
+        || route.some((name) => typeof name !== 'string' || !NODE_NAME_RE.test(name))
+        || new Set(route).size !== route.length) return null;
+      routed = [...route];
+    }
+    op.check();
+    store = loadStore();
+    if (!store) return null;
+    slotVerifier.sync(store, proofScope);
     const nodes = store.nodes || [];
-    const out = nodes.find((n) => n && n.direction === 'outbound'
-      && n.nodeId === ownerId && n.token && n.localPort);
-    if (out) return { node: out, forwardPort: out.localPort, forwardToken: out.token, kind: 'outbound' };
+    const direct = nodes.filter((n) => n && n.nodeId === ownerId);
+    if (direct.length > 1) return null;
+    const out = direct.find((n) => n.direction === 'outbound' && n.token && n.localPort);
+    if (out) return { node: out, forwardPort: out.localPort, forwardToken: out.token, kind: 'outbound', route: routed };
+    if (!direct.length && routed) return { node: null, kind: 'routed', route: routed };
     const inbound = nodes.find((n) => n && n.direction === 'inbound'
       && n.shared === true && n.nodeId === ownerId
-      && (n.token || n.acceptToken)
+      && n.token
       && n.askReplyAccess === true && n.eventsAccess === true
       && n.cellVisibility !== 'none');
     if (!inbound) return null;
-    const forwardToken = inbound.token || inbound.acceptToken;
+    const forwardToken = inbound.token;
     const pool = inbound.reversePool;
     const slot = pool && Array.isArray(pool.slots) ? pool.slots[pool.activeSlot] : null;
     if (!slot || !Number.isInteger(slot.port)) {
-      return { node: inbound, forwardPort: null, forwardToken, kind: 'inbound-unverified' };
+      return { node: inbound, forwardPort: null, forwardToken, kind: 'inbound-unverified', route: routed };
     }
-    return { node: inbound, forwardPort: slot.port, forwardToken, kind: 'inbound' };
+    return { node: inbound, forwardPort: slot.port, forwardToken, kind: 'inbound', route: routed };
   }
 
   function ownerUrl(port, path) {
     return `http://127.0.0.1:${port}/federation/route/_/${path.replace(/^\//, '')}`;
   }
 
+  async function forward(candidate, path, { method = 'GET', body, expectedTs, op } = {}) {
+    op.check();
+    const st = loadStore();
+    slotVerifier.sync(st, proofScope);
+    if (candidate.kind === 'inbound' && !candidate.route) {
+      const current = st && (st.nodes || []).find(node => node.name === candidate.node.name);
+      const selected = binding(st, current);
+      if (!selected || selected.fingerprint !== op.proofBinding) {
+        slotVerifier.invalidate(op.proofKey);
+        const error = new Error('reverse slot changed'); error.reason = 'reverse-slot-unverified'; throw error;
+      }
+    }
+    const routed = candidate.route;
+    const url = routed
+      ? `http://127.0.0.1:${localPort()}/api/route/${routed.map(encodeURIComponent).join('/')}/_${path}`
+      : ownerUrl(candidate.forwardPort, path);
+    const headers = routed ? { authorization: `Bearer ${localToken()}` }
+      : { authorization: `Bearer ${candidate.forwardToken}`, 'x-nexuscrew-visited': st && st.nodeId || '' };
+    try {
+      op.check(); op.delivered = true;
+      const r = await op.wait(fetchImpl(url, { method, headers: { ...headers, 'content-type': 'application/json',
+        ...(expectedTs === undefined ? {} : { 'x-nexuscrew-ask-ts': String(expectedTs) }) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: op.controller.signal }));
+      op.check();
+      const payload = await op.wait(r.json().catch(error => {
+        if ([403, 404, 501].includes(r.status)) return {};
+        throw error;
+      }));
+      op.check();
+      if (!r.ok) slotVerifier.invalidate(op.proofKey);
+      return { r, body: { ...payload, reason: safeReason(payload && payload.reason) } };
+    } catch (error) { slotVerifier.invalidate(op.proofKey); throw error; }
+  }
+
   // Preflight del canale reverse per un peer inbound: rifiuto NETTO se lo slot
   // non e' verificato (non e' un esito incerto: il forward non e' mai partito).
-  async function verifyInboundChannel(candidate) {
-    const { node, forwardPort } = candidate;
-    const pool = node.reversePool;
-    const slot = pool && Array.isArray(pool.slots) ? pool.slots[pool.activeSlot] : null;
-    const proof = await probeReverseSlotImpl({
-      port: forwardPort, secret: node.token,
-      expected: {
-        remotePort: forwardPort,
-        generation: pool && Number.isInteger(pool.activeGeneration) ? pool.activeGeneration : undefined,
-        instanceId: node.nodeId,
-      },
-    });
-    if (proof && proof.owned === true) return { ok: true };
-    return {
-      ok: false, code: 404,
-      error: 'canale reverse non verificato: risposta non inoltrata',
-      reason: 'reverse-slot-unverified',
-    };
+  async function verifyInboundChannel(candidate, op) {
+    // REST routes prove the slot at their inbound proxy hop, never twice.
+    if (candidate.route) return { ok: true };
+    op.check();
+    const st = loadStore();
+    const proof = await op.wait(slotVerifier.verify({ store: st, peer: candidate.node, loadStore,
+      scope: proofScope, signal: op.controller.signal, probeImpl: probeReverseSlotImpl }));
+    op.check();
+    if (proof && proof.owned === true) {
+      op.proofKey = proof.key;
+      const selected = binding(st, candidate.node);
+      op.proofBinding = selected && selected.fingerprint;
+      return { ok: true };
+    }
+    return { ok: false, code: 404, error: 'canale reverse non verificato: risposta non inoltrata', reason: 'reverse-slot-unverified' };
   }
 
   function attemptKey(ownerId, askId, rid) { return `${ownerId}|${askId}|${rid}`; }
@@ -99,17 +200,17 @@ function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = ()
     return sent.length ? sent[sent.length - 1].requestId : null;
   }
 
-  async function relayAnswer({ ownerId, askId, text, rid: providedRid } = {}) {
+  async function relayAnswerOnce({ ownerId, askId, text, rid: providedRid } = {}, op) {
     if (!ownerId || !askId || typeof text !== 'string' || !text.trim()) {
       return { ok: false, code: 400, error: 'ownerId, askId e text richiesti' };
     }
-    const candidate = candidateOwner(ownerId);
+    const candidate = await candidateOwner(ownerId, op);
     if (!candidate) return { ok: false, code: 404, error: 'owner non tra i peer autorizzati', reason: 'owner-unknown' };
     if (candidate.kind === 'inbound-unverified') {
       return { ok: false, code: 404, error: 'canale reverse non verificato: risposta non inoltrata', reason: 'reverse-slot-unverified' };
     }
     if (candidate.kind === 'inbound') {
-      const gate = await verifyInboundChannel(candidate);
+      const gate = await verifyInboundChannel(candidate, op);
       if (!gate.ok) return { ok: false, code: gate.code, error: gate.error, reason: gate.reason };
     }
     const peer = candidate.node;
@@ -123,25 +224,22 @@ function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = ()
     const rid = providedRid || requestId();
     const key = attemptKey(ownerId, askId, rid);
     const store = loadStore();
-    attempts.set(key, { requestId: rid, state: 'sent', askId, ownerId });
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), IDLE_MS);
+    attempts.set(key, { requestId: rid, state: 'sent', askId, ownerId, digest: crypto.createHash('sha256').update(text).digest('hex') });
     try {
-      const r = await fetchImpl(ownerUrl(candidate.forwardPort, `/event-feed/asks/${askId}/answer`), {
-        method: 'POST',
-        headers: {
-          authorization: `Bearer ${candidate.forwardToken}`,
-          'content-type': 'application/json',
-          'x-nexuscrew-visited': store.nodeId,
-        },
-        body: JSON.stringify({ text, requestId: rid }),
-        signal: ctrl.signal,
+      const { r, body } = await forward(candidate, `/event-feed/asks/${encodeURIComponent(askId)}/answer`, {
+        method: 'POST', body: { text, requestId: rid }, op,
       });
-      const body = await r.json().catch(() => ({}));
+      op.check();
       if (r.status === 200) {
-        const state = body.status === 'answered' ? 'committed' : body.status || 'committed';
+        const state = body.status === 'answered' ? 'committed' : body.status;
+        if (!['committed', 'failed'].includes(state)) {
+          attempts.get(key).state = 'uncertain';
+          return { ok: false, code: 200, uncertain: true, requestId: rid, reason: 'delivery-unknown' };
+        }
         attempts.get(key).state = body.replay ? (body.state || state) : state;
-        return { ok: true, status: attempts.get(key).state, requestId: rid };
+        return { ok: true, status: attempts.get(key).state, requestId: rid,
+          ...(body.ownerId ? { ownerId: body.ownerId } : {}), ...(body.askId ? { askId: body.askId } : {}),
+          ...(body.actor ? { actor: body.actor } : {}), ...(body.receipt ? { receipt: body.receipt } : {}) };
       }
       const entry = attempts.get(key);
       // 409 request-conflict / answering are definitive; anything else that
@@ -155,7 +253,7 @@ function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = ()
             originalRequestId: originalSentRequestId(ownerId, askId, rid), requestId: rid,
             error: 'esito incerto: bloccato da un invio precedente' };
         }
-        return { ok: false, code: 409, error: body.error || 'conflict', reason: body.reason };
+        return { ok: false, code: 409, error: 'conflict', reason: body.reason };
       }
       if (r.status === 502) {
         if (entry) entry.state = 'uncertain';
@@ -163,75 +261,164 @@ function createAskRelay({ loadStore, now = Date.now, fetchImpl = fetch, log = ()
           error: 'esito incerto: verifica lo stato prima di rispondere' };
       }
       if (entry) entry.state = 'failed';
-      return { ok: false, code: r.status, error: body.error || `HTTP ${r.status}`, reason: body.reason };
-    } catch (_) {
+      return { ok: false, code: r.status, error: `HTTP ${r.status}`, reason: body.reason };
+    } catch (error) {
+      if (!op.active()) return deadlineResult(op, { ownerId, askId, rid }, false);
+      if (!op.delivered) {
+        const entry = attempts.get(key); if (entry) entry.state = 'failed';
+        return { ok: false, code: 404, reason: error.reason || 'reverse-slot-unverified', error: 'risposta non inoltrata' };
+      }
       // The request may or may not have pasted: uncertain, never retried.
       const entry = attempts.get(key);
       if (entry) entry.state = 'uncertain';
       return { ok: false, code: 200, uncertain: true, reason: 'delivery-unknown', requestId: rid,
         error: 'esito incerto: verifica lo stato prima di rispondere' };
-    } finally {
-      clearTimeout(timer);
     }
   }
 
+  async function relayAnswer(args = {}) {
+    const rid = args.rid || requestId();
+    const key = attemptKey(args.ownerId, args.askId, rid);
+    const old = attempts.get(key);
+    const digest = crypto.createHash('sha256').update(String(args.text || '')).digest('hex');
+    if (old && old.digest !== digest) return { ok: false, code: 409, reason: 'request-conflict', error: 'stesso requestId con testo diverso' };
+    const pending = answerFlights.get(key);
+    if (pending && pending.digest !== digest) return { ok: false, code: 409, reason: 'request-conflict', error: 'stesso requestId con testo diverso' };
+    if (pending) return pending.promise;
+    const flight = operation({ ...args, rid }, op => relayAnswerOnce({ ...args, rid }, op), false, true);
+    const slot = { promise: flight, digest };
+    answerFlights.set(key, slot);
+    try { return await flight; } finally { if (answerFlights.get(key) === slot) answerFlights.delete(key); }
+  }
+
   // Remote dismiss: same resolution rules as the answer (DELETE on the owner).
-  async function relayDismiss({ ownerId, askId } = {}) {
-    const candidate = candidateOwner(ownerId);
+  function retryAfterMs(response) {
+    const value = response.headers?.get?.('retry-after');
+    if (typeof value !== 'string') return 0;
+    const seconds = /^\d+(?:\.\d+)?$/.test(value.trim()) ? Number(value) : null;
+    const delay = seconds === null ? Date.parse(value) - now() : seconds * 1000;
+    return Number.isFinite(delay) && delay > 0 ? delay : 0;
+  }
+
+  async function relayDismissOnce({ ownerId, askId, expectedTs } = {}, op) {
+    const candidate = await candidateOwner(ownerId, op);
     if (!candidate) return { ok: false, code: 404, error: 'owner non tra i peer autorizzati', reason: 'owner-unknown' };
     if (candidate.kind === 'inbound-unverified') {
       return { ok: false, code: 404, error: 'canale reverse non verificato: risposta non inoltrata', reason: 'reverse-slot-unverified' };
     }
     if (candidate.kind === 'inbound') {
-      const gate = await verifyInboundChannel(candidate);
+      const gate = await verifyInboundChannel(candidate, op);
       if (!gate.ok) return { ok: false, code: gate.code, error: gate.error, reason: gate.reason };
     }
     const peer = candidate.node;
     const store = loadStore();
     try {
-      const r = await fetchImpl(ownerUrl(candidate.forwardPort, `/event-feed/asks/${askId}`), {
-        method: 'DELETE',
-        headers: { authorization: `Bearer ${candidate.forwardToken}`, 'x-nexuscrew-visited': store ? store.nodeId : '' },
-      });
-      const body = await r.json().catch(() => ({}));
-      if (!r.ok) return { ok: false, code: r.status, error: body.error || `HTTP ${r.status}` };
-      return { ok: true };
-    } catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+      const { r, body } = await forward(candidate, `/event-feed/asks/${encodeURIComponent(askId)}`, { method: 'DELETE', expectedTs, op });
+      if (!r.ok) return { ok: false, code: r.status, error: 'owner refused', reason: body.reason, retryAfterMs: retryAfterMs(r) };
+      return { ok: true, ...(body.outcome ? { outcome: body.outcome } : {}) };
+    } catch (e) { if (!op.active()) return deadlineResult(op, { ownerId, askId }, false); return { ok: false, code: 502, reason: safeReason(e.reason), error: 'owner unreachable' }; }
   }
 
-  async function verifyStatus({ ownerId, askId, requestId: rid }) {
-    const candidate = candidateOwner(ownerId);
+  async function verifyStatusOnce({ ownerId, askId, requestId: rid }, op) {
+    const candidate = await candidateOwner(ownerId, op);
     if (!candidate) return { ok: false, code: 404, error: 'owner non tra i peer autorizzati', reason: 'owner-unknown' };
     if (candidate.kind === 'inbound-unverified') {
       return { ok: false, code: 404, error: 'canale reverse non verificato: risposta non inoltrata', reason: 'reverse-slot-unverified' };
     }
     if (candidate.kind === 'inbound') {
-      const gate = await verifyInboundChannel(candidate);
+      const gate = await verifyInboundChannel(candidate, op);
       if (!gate.ok) return { ok: false, code: gate.code, error: gate.error, reason: gate.reason };
     }
     const peer = candidate.node;
     const store = loadStore();
     try {
-      const r = await fetchImpl(ownerUrl(candidate.forwardPort, `/event-feed/asks/${askId}/requests/${rid}`), {
-        headers: { authorization: `Bearer ${candidate.forwardToken}`, 'x-nexuscrew-visited': store ? store.nodeId : '' },
-      });
-      if (!r.ok) return { ok: false, code: r.status };
-      const body = await r.json();
+      const { r, body } = await forward(candidate,
+        `/event-feed/asks/${encodeURIComponent(askId)}/requests/${encodeURIComponent(rid)}`, { op });
+      if (!r.ok) return { ok: false, code: r.status, reason: body.reason, error: 'owner refused' };
+      op.check();
       const key = attemptKey(ownerId, askId, rid);
       if (attempts.has(key) && (body.state === 'committed' || body.state === 'failed')) {
         attempts.get(key).state = body.state;
       }
-      return { ok: true, state: body.state || 'unknown' };
+      return { ok: true, state: body.state || 'unknown',
+        ...(body.ownerId ? { ownerId: body.ownerId } : {}), ...(body.askId ? { askId: body.askId } : {}),
+        ...(body.actor ? { actor: body.actor } : {}), ...(body.receipt ? { receipt: body.receipt } : {}) };
     } catch (e) {
-      return { ok: false, error: String((e && e.message) || e) };
+      if (!op.active()) return deadlineResult(op, { ownerId, askId }, false);
+      return { ok: false, code: 502, reason: safeReason(e.reason), error: 'owner unreachable' };
+    }
+  }
+
+  async function replyCapabilityOnce({ ownerId, askId } = {}, op) {
+    const denied = (status, reason) => ({ ownerId, askId, canReply: false, status, ...(reason ? { reason } : {}) });
+    const candidate = await candidateOwner(ownerId, op);
+    if (!candidate) return denied('unreachable', 'owner-unknown');
+    if (candidate.kind === 'inbound-unverified') { op.channelUnavailable = true; return denied('unreachable', 'reverse-slot-unverified'); }
+    if (candidate.kind === 'inbound') {
+      const gate = await verifyInboundChannel(candidate, op);
+      if (!gate.ok) { op.channelUnavailable = true; return denied('unreachable', gate.reason); }
+    }
+    try {
+      const { r, body } = await forward(candidate, `/event-feed/asks/${encodeURIComponent(askId)}/capability`, { op });
+      if (['reverse-slot-unverified', 'federation-peer-unreachable', 'federation-peer-timeout'].includes(body.reason)) { op.channelUnavailable = true; return denied('unreachable', body.reason); }
+      if (r.status === 404 || r.status === 501) return denied('unsupported', body.reason);
+      if (r.status === 403) return denied('denied', body.reason);
+      if (!r.ok || body.ownerId !== ownerId || body.askId !== askId || typeof body.canReply !== 'boolean'
+        || !['open', 'denied', 'answered', 'dismissed'].includes(body.status)
+        || (body.canReply && body.status !== 'open')) return denied('unreachable');
+      return { ownerId, askId, canReply: body.canReply, status: body.status };
+    } catch (_) { op.channelUnavailable = true; return denied('unreachable', op.active() ? undefined : 'relay-deadline'); }
+  }
+
+  async function inspectDismissalOnce({ ownerId, askId } = {}, op) {
+    const candidate = await candidateOwner(ownerId, op);
+    if (!candidate) return { ok: false, code: 404, reason: 'owner-unknown' };
+    if (candidate.kind === 'inbound-unverified') return { ok: false, code: 404, reason: 'reverse-slot-unverified' };
+    if (candidate.kind === 'inbound') {
+      const proof = await verifyInboundChannel(candidate, op);
+      if (!proof.ok) return proof;
+    }
+    const { r, body } = await forward(candidate, `/event-feed/asks/${encodeURIComponent(askId)}/capability`, { op });
+    if (!r.ok) return { ok: false, code: r.status, reason: body.reason || 'unknown', retryAfterMs: retryAfterMs(r) };
+    if (body.ownerId !== ownerId || body.askId !== askId || !['open', 'answered', 'dismissed'].includes(body.status)) {
+      return { ok: false, code: 403, reason: 'unknown' };
+    }
+    if (body.generationPrecondition !== true) return { ok: false, code: 501, reason: 'unsupported' };
+    const ask = body.ask;
+    if (!ask || ask.id !== askId || !Number.isSafeInteger(ask.ts) || ask.ts <= 0
+      || typeof ask.question !== 'string' || typeof ask.session !== 'string'
+      || (ask.options !== undefined && (!Array.isArray(ask.options) || ask.options.some(option => typeof option !== 'string')))) {
+      return { ok: false, code: 409, reason: 'generation-mismatch' };
     }
+    return { ok: true, status: body.status, ask, generationPrecondition: true };
+  }
+  function inspectDismissal(args = {}) { return operation(args, op => inspectDismissalOnce(args, op)); }
+
+  function relayDismiss(args = {}) { return operation(args, op => relayDismissOnce(args, op)); }
+  function verifyStatus(args = {}) { return operation(args, op => verifyStatusOnce(args, op)); }
+  function channelBinding(ownerId) {
+    const store = loadStore();
+    // Kept only in process memory; credentials never enter the dismissal store.
+    return crypto.createHash('sha256').update(JSON.stringify([store, availabilityBinding(ownerId)])).digest('hex');
+  }
+  function channelState(ownerId) {
+    const observation = channelObservations.get(ownerId);
+    return { unavailable: !!(observation && now() - observation.at < 30000 && observation.binding === channelBinding(ownerId) && observation.unavailable) };
+  }
+  function replyCapability(args = {}) {
+    const initial = channelBinding(args.ownerId);
+    return operation(args, async op => {
+      const result = await replyCapabilityOnce(args, op);
+      channelObservations.set(args.ownerId, { at: now(), binding: initial, unavailable: op.channelUnavailable === true });
+      return result;
+    }, true);
   }
 
   function state() {
     return [...attempts.entries()].map(([key, a]) => ({ key, ...a }));
   }
 
-  return { relayAnswer, relayDismiss, verifyStatus, state, isUncertain, requestId };
+  return { channelState, inspectDismissal, relayAnswer, relayDismiss, verifyStatus, replyCapability, state, isUncertain, requestId };
 }
 
 module.exports = { createAskRelay };