@mmmbuto/nexuscrew 0.9.64 → 0.9.66

package/lib/notify/event-feed-notices-routes.js

@@ -0,0 +1,135 @@
+'use strict';
+// lib/notify/event-feed-notices-routes.js — the OWNER's notice dismissal surface.
+//
+//   DELETE /event-feed/notices/:eventId      clear one notice
+//   POST   /event-feed/notices/dismiss-all   clear the visible set (closed body)
+//
+// The owner is the source of truth for its own notices, so this is where a
+// dismissal is registered: the snapshot it serves stops carrying the entry
+// (every other device inherits that at its next read) and a closure frame is
+// published for the peers that already hold the card live.
+//
+// Authorization is the ask-action pattern, reused verbatim: kill switch →
+// proven federated origin → chain ending here (direct or two hops) → visibility
+// ACL of the origin → `eventsAccess` + `askReplyAccess` on EVERY ring. Seeing a
+// notice is not what grants clearing it, and no new grant name is invented.
+//
+// Unknown and out-of-scope ids get the SAME opaque 404: an id that does not
+// exist and an id the peer may not see must be indistinguishable. The budget is
+// its own instance (6/min/peer, 30/min global) and `dismiss-all` counts once:
+// N DELETEs through two hops would die in the per-request budget.
+
+const express = require('express');
+const { createAskActionGate, createAskRateLimiter } = require('./event-feed-asks-routes.js');
+
+// The event id is a crypto.randomUUID() minted by the producer registry: it is
+// validated here BEFORE any use — a path is never built from a request value.
+const EVENT_ID_RE = /^[0-9a-f-]{36}$/;
+// Same cap as SNAPSHOT_MAX_NOTIFY: `dismiss-all` covers what the peer can see,
+// which is what the snapshot it just read held.
+const MAX_VISIBLE = 50;
+
+function createEventFeedNoticesRoutes(deps) {
+  const r = express.Router();
+  const json = express.json({ limit: '8kb' });
+  const gate = createAskActionGate(deps);
+  const rate = createAskRateLimiter({ now: deps.now });
+  const log = typeof deps.log === 'function' ? deps.log : () => {};
+
+  // Resolve the notice for THIS peer: it must be in the history of the owner
+  // AND visible to the ASKING peer under the grants of the owner, by the same
+  // rule the snapshot applies to the envelope it would ship. Visibility is a
+  // decision of the ORIGIN (cross-chain transit is gated earlier in the hop
+  // chain): a relay never gains a visibility of its own.
+  function resolveNoticeForPeer(peer, eventId) {
+    const entry = deps.history.list().find((e) => e && e.eventId === eventId);
+    if (!entry || !entry.envelope) return null;
+    if (!peer.allowsEnvelope(entry.envelope)) return null;
+    return entry;
+  }
+
+  // The closure inherits scope and cell of the original, so the publisher
+  // delivers it to exactly the peers that could see that notice. A failure to
+  // publish never turns a registered dismissal into an error: the entry is
+  // already gone from the snapshot, which is the durable half.
+  async function publishClosures(entries) {
+    for (const entry of entries) {
+      try {
+        await deps.closeNotice({
+          scope: entry.envelope.scope,
+          cellId: entry.envelope.scope === 'cell' ? entry.envelope.cellId : null,
+          eventId: entry.eventId,
+        });
+      } catch (e) {
+        log(`notices: closure not published for ${String(entry.eventId).slice(0, 8)}: ${String((e && e.message) || e)}`);
+      }
+    }
+  }
+
+  r.delete('/:eventId', async (req, res) => {
+    const g = await gate(req, res);
+    if (!g) return;
+    const verdict = rate.check(g.peer.nodeId, g.actor);
+    if (!verdict.allowed) return res.status(429).json({ error: 'dismiss rate', reason: verdict.reason });
+    if (deps.readonly && deps.readonly()) {
+      return res.status(403).json({ error: 'READONLY: mutazione bloccata' });
+    }
+    if (g.peer.grants.askReplyAccess !== true) {
+      return res.status(403).json({ error: 'risorsa non concessa a questo nodo', reason: 'grant-required:ask-action' });
+    }
+    const eventId = String(req.params.eventId || '');
+    if (!EVENT_ID_RE.test(eventId)) {
+      return res.status(400).json({ error: 'eventId non valido' });
+    }
+    const entry = resolveNoticeForPeer(g.peer, eventId);
+    if (!entry) {
+      // Unknown and invisible are the same answer, so the surface cannot be
+      // used to probe the owner's history.
+      return res.status(404).json({ error: 'notify inesistente' });
+    }
+    const already = deps.dismissals.isDismissed(eventId);
+    if (already) return res.json({ dismissed: true, idempotent: true });
+    const written = deps.dismissals.dismiss(eventId);
+    if (!written.ok) {
+      // The store refused to represent the dismissal (declared as a
+      // degradation): answering 200 would claim a truth we do not hold.
+      return res.status(503).json({ error: 'dismissals unavailable', reason: written.reason });
+    }
+    await publishClosures([entry]);
+    return res.json({ dismissed: true, idempotent: false });
+  });
+
+  r.post('/dismiss-all', json, async (req, res) => {
+    const g = await gate(req, res);
+    if (!g) return;
+    const verdict = rate.check(g.peer.nodeId, g.actor);
+    if (!verdict.allowed) return res.status(429).json({ error: 'dismiss rate', reason: verdict.reason });
+    if (deps.readonly && deps.readonly()) {
+      return res.status(403).json({ error: 'READONLY: mutazione bloccata' });
+    }
+    if (g.peer.grants.askReplyAccess !== true) {
+      return res.status(403).json({ error: 'risorsa non concessa a questo nodo', reason: 'grant-required:ask-action' });
+    }
+    // CLOSED body: the set to clear is what the peer can see, never a list the
+    // request brings. A body that tries to choose it is a 400 before anything.
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    for (const key of Object.keys(body)) {
+      return res.status(400).json({ error: `campo non ammesso: "${key}"` });
+    }
+    const visible = deps.history.list()
+      .filter((e) => e && e.envelope && g.peer.allowsEnvelope(e.envelope))
+      .slice(-MAX_VISIBLE);
+    const cleared = [];
+    for (const entry of visible) {
+      if (deps.dismissals.isDismissed(entry.eventId)) continue;
+      const written = deps.dismissals.dismiss(entry.eventId);
+      if (written.ok) cleared.push(entry);
+    }
+    await publishClosures(cleared);
+    return res.json({ dismissed: cleared.length });
+  });
+
+  return r;
+}
+
+module.exports = { createEventFeedNoticesRoutes, EVENT_ID_RE, MAX_VISIBLE };

package/lib/notify/event-feed-producers.js

@@ -94,6 +94,27 @@ const PRODUCERS = {
       ts: typeof p.ts === 'number' ? p.ts : undefined,
     }),
   },
+  // Closure of a notice the OWNER cleared: the frame carries the event id the
+  // receivers already hold, and inherits the scope (and the cell) of that
+  // original — that is what delivers it to exactly the peers that could see it.
+  'notify-closed': {
+    scope: 'cell',
+    requires: ['cellId'],
+    build: (p) => ({
+      type: 'notify-closed',
+      eventId: cleanStr(p.eventId, 64) || '',
+      ts: typeof p.ts === 'number' ? p.ts : undefined,
+    }),
+  },
+  'notify-closed-node': {
+    scope: 'node',
+    requires: [],
+    build: (p) => ({
+      type: 'notify-closed-node',
+      eventId: cleanStr(p.eventId, 64) || '',
+      ts: typeof p.ts === 'number' ? p.ts : undefined,
+    }),
+  },
   // A file notice: name/caption/session only. A file event is an alert — the
   // download is a separate, separately authorized operation.
   'file-notice': {

package/lib/notify/event-feed-routes.js

@@ -14,6 +14,7 @@
 const express = require('express');
 const nodesStore = require('../nodes/store.js');
 const eventFeedAcl = require('./event-feed-acl.js');
+const askCell = require('./ask-cell.js');
 
 const SNAPSHOT_MAX_BYTES = 3 * 1024 * 1024;
 const SNAPSHOT_MAX_ASKS = 100;
@@ -197,6 +198,7 @@ function createEventFeedRoutes(deps) {
   async function buildSnapshot({ peer, self }) {
     // Cursor captured atomically with the snapshot content: the feed engine is
     // synchronous, so one turn later nothing has been inserted in between.
+    const dismissals = deps.noticeDismissals || null;
     const st = deps.eventFeed.status(peer.nodeId);
     const cursor = st ? `${st.viewEpoch}:${st.seq}` : null;
     const viewEpoch = st ? st.viewEpoch : null;
@@ -210,6 +212,12 @@ function createEventFeedRoutes(deps) {
     // alias ancora aperti. Non si spedisce Nessuno snapshot: si rilancia un
     // errore tipizzato che l'handler traduce in 503 {error:"asks-unreadable"}.
     let asks = [];
+    // SOURCE counts, taken BEFORE any slice: the marker means "there was more
+    // than this page holds", and only the source can tell. A page sliced to
+    // exactly the cap from a source no bigger than the cap is the WHOLE set.
+    let askSourceCount = 0;
+    let notifySourceCount = 0;
+    let cellSourceCount = 0;
     try {
       // Health gate PRIMA di list(): un asks.json ESISTENTE ma MALFORMATO
       // (virgola finale, asks non array) produce un list() [] SILENZIOSO — senza
@@ -234,10 +242,15 @@ function createEventFeedRoutes(deps) {
         // guardia e' esplicita sui campi di provenienza, non dedotta dalla
         // visibilita' della cella.
         .filter((a) => !a.originNode && !(a.ownerId && self && a.ownerId !== self))
-        .map((a) => ({ id: a.id, question: a.question, options: a.options, session: a.session, ts: a.ts }))
-        .filter((a) => peer.allows({ scope: 'cell', cellId: cellForSession(a.session) }))
-        .slice(0, SNAPSHOT_MAX_ASKS);
-      asks = visible;
+        // The cell is resolved ONCE, by this owner, through its own definitions, and
+        // it travels with the ask: a session with a custom tmux name does not decode
+        // to a cell on the receiving side, and the receiver must not guess it. Only
+        // a well-formed id is published; an unresolved one is simply absent.
+        .map((a) => ({ id: a.id, question: a.question, options: a.options, session: a.session, ts: a.ts, cell: cellForSession(a.session) }))
+        .filter((a) => peer.allows({ scope: 'cell', cellId: a.cell }))
+        .map(({ cell, ...ask }) => (askCell.isCellId(cell) ? { ...ask, cellId: cell } : ask));
+      askSourceCount = visible.length;
+      asks = visible.slice(0, SNAPSHOT_MAX_ASKS);
     } catch (e) {
       // Una riga, nessun dato sensibile: il messaggio dello store e' gia'
       // limitato a nome file e causa (v. persist.js readJsonSafe).
@@ -248,7 +261,12 @@ function createEventFeedRoutes(deps) {
     }
 
     // Notify history: local-only, ACL-filtered per envelope, capped.
-    const notifications = deps.history.list()
+    const visibleNotifications = deps.history.list()
+      // Cleared notices are gone from the owner's view BEFORE the ACL: the
+      // dismissal is the owner's own statement about its own notice, and every
+      // device that reads this snapshot inherits it (that is what makes the
+      // cleanup true everywhere, not just on the device that asked).
+      .filter((e) => !(dismissals && dismissals.isDismissed(e.eventId)))
       .filter((e) => peer.allows(e.envelope))
       .map((e) => {
         // Node frames can carry cell lists (fleet state): project them with
@@ -258,8 +276,9 @@ function createEventFeedRoutes(deps) {
           return { ...e, envelope: { ...e.envelope, frame: { ...e.envelope.frame, cells } } };
         }
         return e;
-      })
-      .slice(-SNAPSHOT_MAX_NOTIFY);
+      });
+    notifySourceCount = visibleNotifications.length;
+    const notifications = visibleNotifications.slice(-SNAPSHOT_MAX_NOTIFY);
 
     // Fleet state: projected by visibility, hidden cells contribute nothing.
     let fleetState = { available: false, cells: [] };
@@ -267,7 +286,9 @@ function createEventFeedRoutes(deps) {
       const fleet = await deps.fleetP;
       if (fleet && typeof fleet.status === 'function') {
         const stt = await fleet.status();
-        const raw = (stt && Array.isArray(stt.cells) ? stt.cells : [])
+        const sourceCells = (stt && Array.isArray(stt.cells) ? stt.cells : []);
+        cellSourceCount = sourceCells.length;
+        const raw = sourceCells
           .slice(0, SNAPSHOT_MAX_CELLS)
           .map((c) => ({ cell: c && c.cell, active: c && c.active === true }));
         fleetState = { available: stt && stt.available === true, cells: peer.projectCells(raw) };
@@ -289,10 +310,14 @@ function createEventFeedRoutes(deps) {
       nodeState: { nodeId: self },
       historyStatus: deps.history.status(),
     };
-    if (asks.length >= SNAPSHOT_MAX_ASKS
-      || notifications.length >= SNAPSHOT_MAX_NOTIFY
-      || (fleetState.cells || []).length >= SNAPSHOT_MAX_CELLS) {
-      // at a cap: the client must treat this as a floor, not a whole.
+    // The marker means "the source had MORE than this page holds": decided on
+    // the source counts, BEFORE the slice. Marking a page that is exactly at
+    // the cap told the client "incomplete" about complete pages — and made a
+    // full-window owner unimportable forever (a notification history cannot
+    // even exceed its own cap).
+    if (askSourceCount > SNAPSHOT_MAX_ASKS
+      || notifySourceCount > SNAPSHOT_MAX_NOTIFY
+      || cellSourceCount > SNAPSHOT_MAX_CELLS) {
       built.resyncRequired = true;
     }
     return built;

package/lib/notify/notice-dismissal-queue.js

@@ -0,0 +1,336 @@
+'use strict';
+// lib/notify/notice-dismissals-queue.js — durable queue for notice dismissals
+// this node could not hand to the owner yet, plus the drainer that retries them.
+//
+// The local intent is ALREADY honoured when a record lands here (the card is
+// gone from this node's view): what is pending is the owner's copy, so the other
+// devices stop seeing the notice too. Records carry no content — owner, event
+// id, times, sync state — never a title, never a body.
+//
+// Bounds and failure policy mirror the dismissals store and the history: 200
+// records, 64 KiB, retention equal to the notice's own life (15 minutes),
+// atomic tmp+rename 0600, degradation declared in status(). An entry whose
+// notice has expired is not worth carrying: it leaves the queue.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MAX_ENTRIES = 200;
+const MAX_BYTES = 64 * 1024;
+const MAX_MS = 15 * 60 * 1000;
+const SCHEMA = 'nexuscrew-notice-dismissal-queue-v1';
+const OWNER_ID_RE = /^[a-f0-9]{32}$/;
+const STATES = new Set(['pending', 'blocked']);
+
+function createNoticeDismissalQueue({ filePath, now = Date.now, limits = {} }) {
+  const maxEntries = limits.maxEntries || MAX_ENTRIES;
+  const maxBytes = limits.maxBytes || MAX_BYTES;
+  const maxMs = limits.maxMs || MAX_MS;
+
+  let cache = null;
+  let degraded = null;
+  // The last load could not read or understand the file: the in-memory list
+  // is INCOMPLETE until a retry succeeds. While it lasts, the operations the
+  // node accepts go to an ordered journal and nothing is written: a successful
+  // read replays the journal on top of the disk before writing.
+  let loadFailed = false;
+  let journal = [];
+
+  function validateList(raw) {
+    if (!Array.isArray(raw)) return null;
+    const out = [];
+    for (const entry of raw) {
+      if (!entry || typeof entry !== 'object') return null;
+      if (!OWNER_ID_RE.test(String(entry.ownerId || ''))) return null;
+      if (typeof entry.eventId !== 'string' || entry.eventId.length === 0) return null;
+      if (!STATES.has(entry.syncState)) return null;
+      if (typeof entry.at !== 'number' || !Number.isFinite(entry.at)) return null;
+      out.push({
+        ownerId: entry.ownerId, eventId: entry.eventId,
+        at: entry.at, expiresAt: Number.isFinite(entry.expiresAt) ? entry.expiresAt : entry.at + maxMs,
+        syncState: entry.syncState,
+        attempts: Number.isSafeInteger(entry.attempts) && entry.attempts >= 0 ? entry.attempts : 0,
+        nextRetryAt: Number.isFinite(entry.nextRetryAt) ? entry.nextRetryAt : 0,
+        ...(typeof entry.lastReason === 'string' ? { lastReason: entry.lastReason } : {}),
+        ...(typeof entry.retryBinding === 'string' || entry.retryBinding === null ? { retryBinding: entry.retryBinding } : {}),
+      });
+    }
+    return out;
+  }
+
+  function prune(entries, t) {
+    let out = entries.filter((e) => e.expiresAt > t);
+    if (out.length > maxEntries) out = out.slice(out.length - maxEntries);
+    return out;
+  }
+
+  // Pure disk read, no cache: {ok:true, entries} or {ok:false} with the
+  // degradation reason set. ENOENT is a legitimate absence, not a failure.
+  function readFromDisk() {
+    let raw;
+    try { raw = fs.readFileSync(filePath, 'utf8'); }
+    catch (e) {
+      if (!(e && e.code === 'ENOENT')) degraded = 'queue-read-failed';
+      return e && e.code === 'ENOENT' ? { ok: true, entries: [] } : { ok: false };
+    }
+    if (Buffer.byteLength(raw, 'utf8') > maxBytes * 4) { degraded = 'queue-oversize'; return { ok: false }; }
+    let parsed = null;
+    try { parsed = JSON.parse(raw); } catch (_) { degraded = 'queue-schema'; return { ok: false }; }
+    const entries = parsed && parsed.schema === SCHEMA ? validateList(parsed.entries) : null;
+    if (!entries) { degraded = 'queue-schema'; return { ok: false }; }
+    return { ok: true, entries: prune(entries, now()) };
+  }
+
+  function load() {
+    if (cache) return cache;
+    const read = readFromDisk();
+    if (!read.ok) {
+      loadFailed = true;
+      cache = [];
+      return cache;
+    }
+    loadFailed = false;
+    cache = read.entries;
+    return cache;
+  }
+
+  function persist(entries) {
+    let body;
+    try { body = JSON.stringify({ schema: SCHEMA, savedAt: now(), entries }); }
+    catch (_) { degraded = 'queue-write-failed'; return { ok: false, reason: 'write-failed', list: entries }; }
+    if (Buffer.byteLength(body, 'utf8') > maxBytes) { degraded = 'queue-oversize'; return { ok: false, reason: 'oversize', list: entries }; }
+    try {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+      fs.writeFileSync(tmp, body, { mode: 0o600 });
+      fs.renameSync(tmp, filePath);
+    } catch (_) { degraded = 'queue-write-failed'; return { ok: false, reason: 'write-failed', list: entries }; }
+    // A successful write holds everything this queue knows: the degradation is
+    // over and the answers go back to attesting full durability. A past
+    // failure must not stick to every future answer.
+    loadFailed = false;
+    degraded = null;
+    return { ok: true, list: entries };
+  }
+
+  // Recovery from a failed load: the disk is the base and the journal replays
+  // on top of it IN ORDER (the node's current intent wins), then the normal
+  // prune applies — the oldest records leave, a fresh accepted intent never
+  // does. Returns false when the disk is still unreadable: nothing is written
+  // then, the intent stays in memory (journal included) and the answers keep
+  // declaring durable:false with the read degradation reason.
+  function attemptRecovery() {
+    const read = readFromDisk();
+    if (!read.ok) return false;
+    let entries = read.entries;
+    for (const op of journal) {
+      if (op.op === 'enqueue') {
+        if (!entries.some((e) => e.ownerId === op.ownerId && e.eventId === op.eventId)) entries.push(op.record);
+      } else if (op.op === 'update') {
+        const i = entries.findIndex((e) => e.ownerId === op.ownerId && e.eventId === op.eventId);
+        if (i >= 0) entries[i] = { ...entries[i], ...op.patch };
+      } else {
+        entries = entries.filter((e) => !(e.ownerId === op.ownerId && e.eventId === op.eventId));
+      }
+    }
+    const rebuilt = prune(entries, now());
+    cache = rebuilt;
+    const written = persist(rebuilt);
+    if (!written.ok) return false;
+    journal = [];
+    loadFailed = false;
+    degraded = null;
+    return true;
+  }
+
+  function indexOf(entries, ownerId, eventId) {
+    return entries.findIndex((e) => e.ownerId === ownerId && e.eventId === eventId);
+  }
+
+  function get(ownerId, eventId) {
+    const entries = prune(load(), now());
+    const i = indexOf(entries, ownerId, eventId);
+    return i < 0 ? null : { ...entries[i] };
+  }
+
+  function list(ownerId) {
+    const entries = prune(load(), now());
+    return entries.filter((e) => (ownerId ? e.ownerId === ownerId : true)).map((e) => ({ ...e }));
+  }
+
+  function enqueue({ ownerId, eventId } = {}) {
+    if (!OWNER_ID_RE.test(String(ownerId || ''))) return { ok: false, reason: 'bad-owner' };
+    if (typeof eventId !== 'string' || !eventId) return { ok: false, reason: 'bad-event' };
+    const entries = prune(load(), now());
+    const i = indexOf(entries, ownerId, eventId);
+    if (i >= 0) return { ok: true, record: { ...entries[i] }, existed: true };
+    const t = now();
+    const record = { ownerId, eventId, at: t, expiresAt: t + maxMs, syncState: 'pending', attempts: 0, nextRetryAt: 0 };
+    entries.push(record);
+    const kept = prune(entries, t);
+    cache = kept;
+    if (loadFailed) {
+      journal.push({ op: 'enqueue', ownerId, eventId, record });
+      attemptRecovery();
+      return { ok: true, record: { ...record }, existed: false };
+    }
+    const written = persist(kept);
+    if (written.ok) degraded = null;
+    return { ok: true, record: { ...record }, existed: false };
+  }
+
+  function update(ownerId, eventId, patch = {}) {
+    const entries = prune(load(), now());
+    const i = indexOf(entries, ownerId, eventId);
+    if (i < 0) return { ok: false, reason: 'unknown' };
+    entries[i] = { ...entries[i], ...patch, ownerId, eventId };
+    cache = prune(entries, now());
+    if (loadFailed) {
+      journal.push({ op: 'update', ownerId, eventId, patch });
+      attemptRecovery();
+      return { ok: true, record: get(ownerId, eventId) || { ...entries[i] } };
+    }
+    const written = persist(entries);
+    if (written.ok) degraded = null;
+    return { ok: true, record: { ...entries[i] } };
+  }
+
+  // Confirmed: the owner has it, the record leaves the queue. While the load
+  // is failing the removal is journaled even when the record is not in the
+  // incomplete in-memory list: the replay applies it to what the disk holds.
+  function confirm(ownerId, eventId) {
+    const entries = prune(load(), now());
+    const i = indexOf(entries, ownerId, eventId);
+    if (loadFailed) {
+      journal.push({ op: 'confirm', ownerId, eventId });
+      if (i >= 0) entries.splice(i, 1);
+      cache = prune(entries, now());
+      attemptRecovery();
+      return { ok: true, removed: i >= 0 };
+    }
+    if (i < 0) return { ok: true, removed: false };
+    entries.splice(i, 1);
+    cache = entries;
+    const written = persist(entries);
+    if (written.ok) degraded = null;
+    return { ok: true, removed: true };
+  }
+
+  function status() {
+    const entries = prune(load(), now());
+    return {
+      degraded: degraded || null,
+      count: entries.length,
+      pending: entries.filter((e) => e.syncState === 'pending').length,
+      blocked: entries.filter((e) => e.syncState === 'blocked').length,
+    };
+  }
+
+  return { enqueue, get, list, update, confirm, status, MAX_MS };
+}
+
+function deferDelay(attempts, random, retryAfterMs = 0) {
+  const base = Math.min(300000, 1000 * 2 ** Math.min(attempts, 9)) * (0.5 + random() * 0.5);
+  return Math.max(retryAfterMs, base);
+}
+
+// The drainer: one attempt per owner at a time, a global budget and a per-owner
+// one, exponential backoff with jitter, and `blocked` records that stay put
+// until the binding to that owner changes (a re-pair is the only thing that can
+// make a refusal meaningful again).
+function createNoticeDismissalDrainer({
+  queue, relay, now = Date.now, random = Math.random,
+  setTimer = setTimeout, clearTimer = clearTimeout, intervalMs = 15000,
+  globalBudget = 4, ownerBudget = 1, budgetWindowMs = 60000,
+  bindingForOwner = () => null, readonly = () => false, log = () => {},
+} = {}) {
+  const flights = new Set();
+  const globalHits = [];
+  const ownerHits = new Map();
+  let stopped = false;
+  let timer = null;
+  let running = null;
+
+  function defer(record, reason, blocked = false, retryAfterMs = 0) {
+    const attempts = (record.attempts || 0) + 1;
+    return queue.update(record.ownerId, record.eventId, {
+      syncState: blocked ? 'blocked' : 'pending',
+      retryBinding: bindingForOwner(record.ownerId),
+      attempts, lastReason: reason || 'owner-unreachable',
+      nextRetryAt: now() + deferDelay(attempts, random, retryAfterMs),
+    });
+  }
+
+  function rejected(record, result = {}) {
+    const reason = result.reason || 'owner-unreachable';
+    const pending = result.transient === true || (result.code === 429) || (typeof result.code === 'number' && result.code >= 500);
+    return defer(record, reason, !pending, result.retryAfterMs || 0);
+  }
+
+  async function attempt(record) {
+    const key = `${record.ownerId}|${record.eventId}`;
+    if (flights.has(key) || stopped || readonly()) return;
+    flights.add(key);
+    try {
+      const current = queue.get(record.ownerId, record.eventId);
+      if (!current || current.syncState !== 'pending') return;
+      const result = await relay.relayNoticeDismiss({ ownerId: record.ownerId, eventId: record.eventId });
+      if (stopped || readonly()) return;
+      const latest = queue.get(record.ownerId, record.eventId);
+      if (!latest || latest.syncState !== 'pending' || latest.at !== current.at) return;
+      if (result.ok) { queue.confirm(latest.ownerId, latest.eventId); return; }
+      if (result.reason === 'unsupported') { defer(latest, 'unsupported', true); return; }
+      rejected(latest, result);
+    } catch (error) {
+      const current = queue.get(record.ownerId, record.eventId);
+      if (!stopped && current && current.syncState === 'pending') defer(current, 'owner-unreachable');
+      log(`notice dismissal synchronization failed: ${String(error.message || error)}`);
+    } finally { flights.delete(key); }
+  }
+
+  async function run() {
+    if (stopped || readonly()) return;
+    const t = now();
+    const pruneHits = (hits) => { while (hits.length && hits[0] <= t - budgetWindowMs) hits.shift(); };
+    pruneHits(globalHits);
+    for (const [ownerId, hits] of ownerHits) { pruneHits(hits); if (!hits.length) ownerHits.delete(ownerId); }
+    for (let record of queue.list()) {
+      if (globalHits.length >= globalBudget) break;
+      if (record.syncState === 'blocked') {
+        const binding = bindingForOwner(record.ownerId);
+        if (binding === null || binding === record.retryBinding) continue;
+        const resumed = queue.update(record.ownerId, record.eventId, { syncState: 'pending', nextRetryAt: 0, retryBinding: binding });
+        if (resumed.ok) record = resumed.record; else continue;
+      }
+      if (record.syncState !== 'pending' || (record.nextRetryAt || 0) > now()) continue;
+      const hits = ownerHits.get(record.ownerId) || [];
+      if (hits.length >= ownerBudget) continue;
+      hits.push(t); ownerHits.set(record.ownerId, hits); globalHits.push(t);
+      await attempt(record);
+    }
+  }
+
+  function drain() {
+    if (running) return running;
+    const flight = run().finally(() => { if (running === flight) running = null; });
+    running = flight;
+    return flight;
+  }
+
+  function schedule() {
+    if (stopped || timer) return;
+    timer = setTimer(() => { timer = null; void drain().catch(error => log(String(error.message || error))).finally(schedule); }, intervalMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  }
+
+  function start() { schedule(); void drain().catch(error => log(String(error.message || error))); }
+  function stop() { stopped = true; if (timer) clearTimer(timer); timer = null; }
+  function nudge() { if (!stopped) void drain().catch(error => log(String(error.message || error))); }
+
+  return { start, stop, drain, nudge };
+}
+
+module.exports = {
+  createNoticeDismissalQueue, createNoticeDismissalDrainer,
+  MAX_ENTRIES, MAX_BYTES, MAX_MS, SCHEMA,
+};