@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/api-lane/reviewers.js

@@ -0,0 +1,755 @@
+/**
+ * Telling the people (Go Prod §10.1, §10.4; copy in the member-emails spec §5–§7): when an API
+ * claim goes `pending_review`, every member who can answer it hears about it — by email, and in
+ * the source's review room on Matrix — and the ones nobody answers are reminded at 3 and 14 days.
+ *
+ * Who: an accepted member whose grant is live right now (`liveMembers` — `liveGrant` for a whole
+ * source in one query: unrevoked, unexpired, the source's owner the root) and carries
+ * `claims/review`. Email also needs the grant to reach the claim's protocol (`nb.protocols`), an
+ * address on the row (a member invited by DID has none: Matrix only) and `notifyReviews` on. Every
+ * email — §5, §6 and the reminders — also goes to the source's `contactEmail` (`recipientsOf`): an
+ * org admin has no member row, and would otherwise never hear of a claim until it was 3 days old —
+ * unless a member with that same address is already sent every claim the contact would be. The
+ * room takes every review-capable member: one room per source cannot be narrowed per protocol, so
+ * its notices reach a protocol-narrowed member too — accepted, since a notice carries no answers.
+ *
+ * The 15-minute window (§10.1): `api_members.reviewEmailAt` is when the member was last emailed
+ * about this source (the contact's, with no member row, is its `rvw:<sourceId>` marker's
+ * `updatedAt`). A claim arriving with the window closed claims it (one conditional UPDATE — the
+ * mutex, so two racing notify steps never both send) and goes out at once — as §5, or as §6 with
+ * whatever was still held for the member folded in; one arriving while it is open is HELD — its
+ * `rv:` row written `pending` — and the minute tick sends everything held for the member as ONE
+ * email once the window has run out (§6; a lone held claim reads better as §5). Every send opens
+ * the next window, so it is never more than one email per 15 minutes.
+ *
+ * Membership of the room follows the grants: each person is invited from their own `rvi:` row
+ * (keyed by MXID, so a member removed and re-added is the same row, never kicked by their old one),
+ * and one whose grant is gone (revoked, expired, removed) is kicked on the next notify for that
+ * source AND on the hourly pass — whichever comes first.
+ *
+ * Idempotent and fail-soft like every side-effect lane (lib/matrix/deliver.ts): each email and
+ * notice is a `matrix_deliveries` row keyed by what it is about (schema header). An email's row is
+ * CLAIMED before the send (`claimRows`: inserted `sending`, or a `failed` one taken over), so two
+ * racing callers never both send, and a row once `sent` is never moved off it. A crash between
+ * the send and its mark leaves the row `sending` — never re-sent: at most once, like every notice.
+ * A `failed` email is NOT re-driven by anything but the path that wrote it running again (a
+ * notify-step replay; a reminder claim stays due until one of its sends lands) — at most
+ * `MAX_ATTEMPTS`. Nothing here throws for an email or Matrix failure, and no `EMAIL` binding,
+ * sender, `CONSOLE_URL` (every link) or Matrix token ⇒ skipped with one log line. The timeline
+ * gets `review_notified` with COUNTS only — never an address.
+ *
+ * D1 allows 1000 queries per invocation, so every cron pass is bounded: a flush serves at most
+ * `FLUSH_MEMBERS` members (oldest held first), the room pass `ROOMS_PER_PASS` rooms (least
+ * recently synced first), and a source's reviewer set is one query.
+ */
+import { and, eq, inArray, isNull, lte, ne, or, sql } from "drizzle-orm";
+import { alias } from "drizzle-orm/sqlite-core";
+import { covers } from "../../contracts/capabilities.js";
+import { apiCharges, apiClaims, apiMembers, apiSources, claimReviews, decisions, matrixDeliveries, } from "../../db/schema.js";
+import { getOracle } from "../../oracle.js";
+import { sendEmail } from "../email/send.js";
+import { oracleApiUrl, renderReviewBatchEmail, renderReviewNeededEmail, renderReviewReminderEmail, reviewNeededChat, } from "../email/template.js";
+import { kickUser } from "../matrix/api.js";
+import { matrixErrcode } from "../matrix/client.js";
+import { aliasLocalpart, createOrReuseRoom, inviteBestEffort, matrixLaneReady, sendFailureReason, sendWithRejoin, transactionId, } from "../matrix/deliver.js";
+import { homeserverDomain, mxidFromDid } from "../matrix/mxid.js";
+import { liveMembers, reachesProtocol } from "./members.js";
+import { ANSWER_BY_MARGIN_MS, answerByOf } from "./record.js";
+import { DAY_MS } from "./retention.js";
+import { recordEvents } from "./timeline.js";
+/** §10.1: at most one review email per member per source per window. */
+export const REVIEW_EMAIL_WINDOW_MS = 15 * 60_000;
+/** §10.4: the reminders, oldest first so a claim found late gets the one it is due, not both. */
+const REMINDER_DAYS = [14, 3];
+/** Claims per reminder pass, and held rows read per flush — bounded like the housekeeping sweep. */
+const PASS_LIMIT = 200;
+/** Members emailed per minute tick: each is a few queries, and the tick shares D1's budget. */
+export const FLUSH_MEMBERS = 50;
+/** Review rooms re-synced per hourly pass (one query for its people, one for its invites). */
+export const ROOMS_PER_PASS = 20;
+/** A `failed` email row is taken over (re-sent) at most this many times in all. */
+const MAX_ATTEMPTS = 3;
+/** D1's bound-parameter cap on an `IN (…)`. */
+const IN_CHUNK = 90;
+/** Ledger rows per multi-row INSERT — ~8 bound parameters a row under D1's 100. */
+const ROW_CHUNK = 10;
+/** The `rv:`/`rv3:`/`rv14:` key's recipient part for the source's `contactEmail` (no member row). */
+const CONTACT = "contact";
+/** Who an `rv:{claimId}:{memberId|contact}` row is for: its key past `rv:` + the claim id + `:`. */
+const rvMember = sql `substr(${matrixDeliveries.dedupeKey}, length(${matrixDeliveries.claimId}) + 5)`;
+// --- the notify step -------------------------------------------------------------------------------
+/**
+ * Tell the claim's reviewers it is waiting (the notify step, after `review_required` is on the
+ * timeline). Never throws: a failure here is one log line, never the claim's.
+ */
+export async function notifyReviewers(deps, claimId, now = new Date()) {
+    try {
+        const { db } = deps;
+        const claim = (await awaitingReview(db, [claimId])).get(claimId);
+        // Decided already past its deadline (a late start, an engine outage's retries): it can no
+        // longer be answered, so nobody is asked to — no email, no room notice.
+        if (!claim || closed(claim, now))
+            return;
+        if (!deps.config.CONSOLE_URL) {
+            deps.logger.info("api.review-notify.skipped", { claimId, reason: "CONSOLE_URL not set" });
+            return;
+        }
+        const source = await db.query.apiSources.findFirst({
+            where: eq(apiSources.sourceId, claim.sourceId),
+        });
+        if (!source)
+            return;
+        const people = await reviewers(db, source.sourceId, now);
+        let emails = 0;
+        if (emailLaneOn(deps, "review_needed")) {
+            for (const r of recipientsOf(source, people, [claim])) {
+                if (!r.reaches(claim))
+                    continue;
+                if (await emailOrHold(deps, source, claim, r, now))
+                    emails++;
+            }
+        }
+        const matrix = (await postRoomNotice(deps, source, claim, people)) ? 1 : 0;
+        // Counts only, never who. Keyed on the decision's instant (+1 ms: after `review_required`), so
+        // a replay lands on the same row — and only a run that told someone writes it.
+        if (emails + matrix > 0) {
+            await recordEvents(db, [
+                {
+                    key: `${claimId}:review_notified:`,
+                    at: new Date(claim.waitingSince.getTime() + 1),
+                    sourceId: source.sourceId,
+                    claimId,
+                    type: "review_notified",
+                    data: { emails, matrix },
+                },
+            ]);
+        }
+    }
+    catch (err) {
+        deps.logger.warn("api.review-notify.failed", { claimId, detail: String(err) });
+    }
+}
+/**
+ * One recipient, one claim: claim its `rv:` row, then send now if their window is closed (and open
+ * it) — §5, or §6 with the claims still held for them folded in, so they never get §5 now and §6
+ * for the older ones a window later — else hold it for the batch. True when they are emailed or
+ * queued; false when another caller owns the row (sent, sending, held, or out of attempts).
+ */
+async function emailOrHold(deps, source, claim, r, now) {
+    const { db } = deps;
+    const dedupeKey = `rv:${claim.claimId}:${r.key}`;
+    const row = { dedupeKey, kind: "review_email", claimId: claim.claimId };
+    if (!(await claimRows(db, [{ ...row, sourceId: source.sourceId }])).has(dedupeKey))
+        return false;
+    if (!(await claimWindow(db, source.sourceId, r.key, now))) {
+        await settle(deps, "review_email", [dedupeKey], "pending");
+        return true;
+    }
+    const held = await db
+        .select({ dedupeKey: matrixDeliveries.dedupeKey, claimId: matrixDeliveries.claimId })
+        .from(matrixDeliveries)
+        .where(and(eq(matrixDeliveries.kind, "review_email"), eq(matrixDeliveries.status, "pending"), 
+    // `contact` is every source's: the source keeps one contact's rows from another's.
+    eq(matrixDeliveries.sourceId, source.sourceId), eq(rvMember, r.key)))
+        .limit(PASS_LIMIT);
+    const { due, dropped } = owedTo(r, held, await awaitingReview(db, claimIdsOf(held)), now);
+    if (dropped.length)
+        await settle(deps, "review_email", dropped, "skipped");
+    const outcome = await sendOwed(deps, source, r, [{ dedupeKey, claim }, ...due]);
+    return outcome === "sent";
+}
+/**
+ * Open the recipient's window at `now` iff it is closed — one statement, so exactly one caller
+ * wins. The contact has no member row: its window is the `rvw:<sourceId>` marker's `updatedAt`,
+ * written only when absent or run out.
+ */
+async function claimWindow(db, sourceId, key, now) {
+    const cutoff = new Date(now.getTime() - REVIEW_EMAIL_WINDOW_MS);
+    if (key === CONTACT) {
+        const [won] = await db
+            .insert(matrixDeliveries)
+            .values({
+            dedupeKey: `rvw:${sourceId}`,
+            kind: "review_window",
+            sourceId,
+            status: "sent",
+            attempts: 1,
+            updatedAt: now,
+        })
+            .onConflictDoUpdate({
+            target: matrixDeliveries.dedupeKey,
+            set: { updatedAt: now },
+            setWhere: lte(matrixDeliveries.updatedAt, cutoff),
+        })
+            .returning({ dedupeKey: matrixDeliveries.dedupeKey });
+        return Boolean(won);
+    }
+    const memberId = key;
+    const [won] = await db
+        .update(apiMembers)
+        .set({ reviewEmailAt: now })
+        .where(and(eq(apiMembers.memberId, memberId), or(isNull(apiMembers.reviewEmailAt), lte(apiMembers.reviewEmailAt, cutoff))))
+        .returning({ memberId: apiMembers.memberId });
+    return Boolean(won);
+}
+/** §5 for one claim, §6 for several; every row settled with the outcome. */
+async function sendOwed(deps, source, r, owed) {
+    const input = { ...emailBase(deps, source), audience: r.audience };
+    const claims = owed.map((o) => o.claim);
+    const [only] = claims;
+    const outcome = await send(deps, r.to, claims.length === 1 ? "review_needed" : "review_batch", claims.length === 1 && only
+        ? renderReviewNeededEmail({ ...input, claim: only })
+        : renderReviewBatchEmail({ ...input, claims }));
+    await settle(deps, "review_email", owed.map((o) => o.dedupeKey), outcome);
+    return outcome;
+}
+/**
+ * A recipient's held rows, split: the ones still owed them (the claim still waiting and not past its
+ * `answerBy` — a batch held across the deadline drops it — and, for a member, their grant still
+ * reaching its protocol with an address and the switch on) and the ones to drop.
+ */
+function owedTo(r, rows, claims, now) {
+    const due = [];
+    const dropped = [];
+    for (const row of rows) {
+        const claim = row.claimId ? claims.get(row.claimId) : undefined;
+        if (claim && !closed(claim, now) && r?.reaches(claim)) {
+            due.push({ dedupeKey: row.dedupeKey, claim });
+        }
+        else {
+            dropped.push(row.dedupeKey);
+        }
+    }
+    return { due, dropped };
+}
+const claimIdsOf = (rows) => rows.flatMap((r) => (r.claimId ? [r.claimId] : []));
+// --- the minute tick: held claims, one email per recipient ---------------------------------------
+/**
+ * Send what was held for every recipient whose window has run out: §6 over the claims still waiting
+ * (§5 for a lone one). A claim answered meanwhile, or a member who lost access, opted out, has no
+ * address any more or was removed (a contact whose address was cleared), is dropped (`skipped`).
+ * Only closed-window recipients are read (the joins), oldest held first, at most `FLUSH_MEMBERS` a
+ * tick — a backlog drains over ticks and nobody starves behind recipients whose window is still
+ * open. The count of emails sent.
+ */
+export async function flushReviewBatches(deps, now = new Date()) {
+    const { db } = deps;
+    const cutoff = new Date(now.getTime() - REVIEW_EMAIL_WINDOW_MS);
+    const contactWindow = alias(matrixDeliveries, "contact_window");
+    const held = await db
+        .select({
+        dedupeKey: matrixDeliveries.dedupeKey,
+        claimId: matrixDeliveries.claimId,
+        sourceId: matrixDeliveries.sourceId,
+        recipient: rvMember,
+        member: apiMembers,
+    })
+        .from(matrixDeliveries)
+        .leftJoin(apiMembers, eq(apiMembers.memberId, rvMember))
+        .leftJoin(contactWindow, eq(contactWindow.dedupeKey, sql `'rvw:' || ${matrixDeliveries.sourceId}`))
+        .where(and(eq(matrixDeliveries.kind, "review_email"), eq(matrixDeliveries.status, "pending"), or(and(ne(rvMember, CONTACT), or(isNull(apiMembers.memberId), isNull(apiMembers.reviewEmailAt), lte(apiMembers.reviewEmailAt, cutoff))), and(eq(rvMember, CONTACT), or(isNull(contactWindow.dedupeKey), lte(contactWindow.updatedAt, cutoff))))))
+        .orderBy(matrixDeliveries.createdAt)
+        .limit(PASS_LIMIT);
+    if (held.length === 0)
+        return 0;
+    // A removed member's rows have no member left to email.
+    const isContact = (r) => r.recipient === CONTACT && Boolean(r.sourceId);
+    const orphans = held.filter((r) => !r.member && !isContact(r)).map((r) => r.dedupeKey);
+    if (orphans.length)
+        await settle(deps, "review_email", orphans, "skipped");
+    const byRecipient = new Map();
+    for (const row of held) {
+        const sourceId = row.member?.sourceId ?? (isContact(row) ? row.sourceId : null);
+        if (!sourceId)
+            continue;
+        const key = row.member ? row.member.memberId : `${CONTACT}:${sourceId}`;
+        const entry = byRecipient.get(key);
+        if (entry)
+            entry.rows.push(row);
+        else if (byRecipient.size < FLUSH_MEMBERS) {
+            byRecipient.set(key, { sourceId, member: row.member, rows: [row] });
+        }
+    }
+    if (byRecipient.size === 0)
+        return 0;
+    const laneOn = emailLaneOn(deps, "review_batch");
+    const claims = await awaitingReview(db, [...byRecipient.values()].flatMap((e) => claimIdsOf(e.rows)));
+    const sources = new Map();
+    let sent = 0;
+    for (const { sourceId, member, rows } of byRecipient.values()) {
+        let scope = sources.get(sourceId);
+        if (!scope) {
+            const [source, people] = await Promise.all([
+                db.query.apiSources.findFirst({ where: eq(apiSources.sourceId, sourceId) }),
+                reviewers(db, sourceId, now),
+            ]);
+            scope = { source, people: new Map(people.map((p) => [p.member.memberId, p])) };
+            sources.set(sourceId, scope);
+        }
+        const person = member ? scope.people.get(member.memberId) : undefined;
+        const r = person ? memberRecipient(person) : member ? null : contactOf(scope.source);
+        const { due, dropped } = owedTo(r, rows, claims, now);
+        const undeliverable = !r || !scope.source || !laneOn;
+        const skip = undeliverable ? [...dropped, ...due.map((o) => o.dedupeKey)] : dropped;
+        if (skip.length)
+            await settle(deps, "review_email", skip, "skipped");
+        if (undeliverable || due.length === 0 || !r || !scope.source)
+            continue;
+        if (!(await claimWindow(db, sourceId, r.key, now)))
+            continue;
+        if ((await sendOwed(deps, scope.source, r, due)) === "sent")
+            sent++;
+    }
+    return sent;
+}
+// --- the hourly pass: 3- and 14-day reminders -----------------------------------------------------
+/**
+ * §10.4: every API claim still waiting 3 (and 14) days after it was decided `review` gets its
+ * reminder — batched per recipient and source like §6: one email listing all their due claims.
+ * The recipients are §5's (`recipientsOf`: the members and the source's contact). Each claim is marked done
+ * (`notice_review_reminder:<claimId>:<days>`) once its pass ran, so the pass never reads it again —
+ * except one whose every send this pass failed: it stays due and the next hour retries it (the
+ * `rv3:`/`rv14:` rows' attempts bound that, and keep a re-run from re-sending the ones that landed).
+ * A paid claim's reminder states its `answerBy` (template.ts); one already past it is not sent.
+ */
+export async function remindReviewers(deps, now = new Date()) {
+    if (!deps.config.CONSOLE_URL || !emailLaneOn(deps, "review_reminder"))
+        return 0;
+    const { db } = deps;
+    let sent = 0;
+    for (const days of REMINDER_DAYS) {
+        const due = await dueForReminder(db, days, now);
+        if (due.length === 0)
+            continue;
+        const bySource = new Map();
+        for (const c of due) {
+            // A paid claim past its `answerBy` can no longer be answered (`REVIEW_EXPIRED`): nobody is
+            // reminded of it, and it is marked done below like any other so it never clogs the pass.
+            if (closed(c, now))
+                continue;
+            bySource.set(c.sourceId, [...(bySource.get(c.sourceId) ?? []), c]);
+        }
+        const landed = new Set();
+        const failed = new Set();
+        for (const [sourceId, claims] of bySource) {
+            const source = await db.query.apiSources.findFirst({
+                where: eq(apiSources.sourceId, sourceId),
+            });
+            if (!source)
+                continue;
+            const people = await reviewers(db, sourceId, now);
+            const recipients = recipientsOf(source, people, claims).map((r) => ({
+                ...r,
+                claims: claims.filter(r.reaches),
+            }));
+            for (const r of recipients) {
+                if (r.claims.length === 0)
+                    continue;
+                const keys = new Map(r.claims.map((c) => [c.claimId, `rv${days}:${c.claimId}:${r.key}`]));
+                const owned = await claimRows(db, r.claims.map((c) => ({
+                    dedupeKey: keys.get(c.claimId),
+                    kind: "review_reminder",
+                    claimId: c.claimId,
+                    sourceId,
+                })));
+                const owed = r.claims.filter((c) => owned.has(keys.get(c.claimId)));
+                if (owed.length === 0)
+                    continue;
+                const input = { ...emailBase(deps, source), claims: owed, audience: r.audience };
+                const outcome = await send(deps, r.to, "review_reminder", renderReviewReminderEmail({ ...input, days }));
+                await settle(deps, "review_reminder", owed.map((c) => keys.get(c.claimId)), outcome);
+                for (const c of owed)
+                    (outcome === "failed" ? failed : landed).add(c.claimId);
+                if (outcome === "sent")
+                    sent++;
+            }
+        }
+        const done = due.filter((c) => landed.has(c.claimId) || !failed.has(c.claimId));
+        for (let i = 0; i < done.length; i += ROW_CHUNK) {
+            await db
+                .insert(matrixDeliveries)
+                .values(done.slice(i, i + ROW_CHUNK).map((c) => ({
+                dedupeKey: `notice_review_reminder:${c.claimId}:${days}`,
+                kind: "notice_review_reminder",
+                claimId: c.claimId,
+                sourceId: c.sourceId,
+                status: "sent",
+                attempts: 1,
+            })))
+                .onConflictDoNothing();
+        }
+    }
+    return sent;
+}
+/** Waiting `days` or more (a 3-day one: less than 14), not yet reminded, oldest first. */
+async function dueForReminder(db, days, now) {
+    const cutoff = new Date(now.getTime() - days * DAY_MS);
+    const rows = await awaitingQuery(db)
+        .where(and(awaitingFilter(), lte(decisions.createdAt, cutoff), days === 3 ? sql `${decisions.createdAt} > ${now.getTime() - 14 * DAY_MS}` : undefined, sql `not exists (select 1 from ${matrixDeliveries} where ${matrixDeliveries.dedupeKey} = 'notice_review_reminder:' || ${apiClaims.claimId} || ${`:${days}`})`))
+        .orderBy(decisions.createdAt)
+        .limit(PASS_LIMIT);
+    return rows.map(toAwaiting);
+}
+// --- Matrix: the source's review room ------------------------------------------------------------
+function matrixDeps(deps) {
+    return {
+        config: deps.config,
+        logger: deps.logger,
+        trace: deps.trace,
+        metrics: deps.metrics,
+        cache: deps.cache,
+        runDb: (fn) => fn(deps.db),
+    };
+}
+/** One notice per claim in the source's room (`rvm:`), after bringing its membership up to date. */
+async function postRoomNotice(deps, source, claim, people) {
+    const { claimId } = claim;
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN) {
+        deps.logger.info("matrix.review_notice.skipped", {
+            claimId,
+            reason: "ORACLE_MATRIX_ACCESS_TOKEN not configured",
+        });
+        return false;
+    }
+    const dedupeKey = `rvm:${claimId}`;
+    const existing = await marker(deps.db, dedupeKey);
+    if (existing?.status === "sent")
+        return false;
+    const base = {
+        dedupeKey,
+        kind: "review_notice",
+        claimId,
+        sourceId: source.sourceId,
+        attempts: (existing?.attempts ?? 0) + 1,
+    };
+    const md = matrixDeps(deps);
+    let roomId = null;
+    try {
+        if (!(await matrixLaneReady(md)))
+            return false;
+        roomId = await sourceRoom(md, source);
+        if (!roomId) {
+            await ledger(deps, { ...base, status: "failed", lastError: "no review room" });
+            return false;
+        }
+        await syncRoom(deps, source.sourceId, roomId, people);
+        // A notice, not an answerable card (§10.1): answering needs the reviewer key in the console.
+        const { body, formattedBody } = reviewNeededChat({
+            ...emailBase(deps, source),
+            claim,
+            audience: "reviewer",
+        });
+        const { event_id } = await sendWithRejoin(md, roomId, "m.room.message", await transactionId(dedupeKey), { msgtype: "m.text", body, format: "org.matrix.custom.html", formatted_body: formattedBody });
+        await ledger(deps, { ...base, roomId, eventId: event_id, status: "sent" });
+        return true;
+    }
+    catch (err) {
+        await ledger(deps, { ...base, roomId, status: "failed", lastError: String(err) });
+        deps.logger.warn("matrix.review_notice.failed", { claimId, reason: sendFailureReason(err) });
+        return false;
+    }
+}
+/**
+ * The source's room, keyed `(oracle, sourceId)` (§10.1) — created at the first notice, reused
+ * after (the `review_room:<sourceId>` marker). Unencrypted: the oracle posts in the clear anyway
+ * (lib/matrix/client.ts), and a notice carries nothing a room must hide.
+ */
+async function sourceRoom(md, source) {
+    const alias = await aliasLocalpart("oracle-review", `${md.config.ORACLE_DID}|${source.sourceId}`);
+    const name = [...source.name.replace(/\s+/g, " ").trim()].slice(0, 60).join("");
+    return createOrReuseRoom(md, {
+        dedupeKey: `review_room:${source.sourceId}`,
+        alias,
+        collectionId: source.sourceId,
+        payload: {
+            name: `Reviews — ${name}`,
+            topic: "Claims that are waiting for a reviewer. Answer them in the Decision Console.",
+            preset: "private_chat",
+            visibility: "private",
+            room_alias_name: alias,
+            // Membership is the oracle's alone (invite:50), and follows the grants (`syncRoom`).
+            power_level_content_override: {
+                invite: 50,
+                users: { [md.config.ORACLE_MATRIX_USER_ID]: 100 },
+            },
+            initial_state: [
+                { type: "m.room.guest_access", state_key: "", content: { guest_access: "forbidden" } },
+                {
+                    type: "m.room.history_visibility",
+                    state_key: "",
+                    content: { history_visibility: "invited" },
+                },
+            ],
+        },
+    });
+}
+/**
+ * Invite every review-capable member not yet invited, and kick every one invited whose grant is
+ * gone. The `rvi:` row is keyed by the MXID — a person, not a member row — so a member removed and
+ * re-added (a new `memberId`, the same DID) finds their own row, instead of being invited by a new
+ * one and kicked by the old. Invites and kicks are best-effort: a failure is a row the next pass
+ * retries.
+ */
+async function syncRoom(deps, sourceId, roomId, people) {
+    const md = matrixDeps(deps);
+    const rows = await deps.db.query.matrixDeliveries.findMany({
+        where: and(eq(matrixDeliveries.kind, "review_invite"), eq(matrixDeliveries.sourceId, sourceId)),
+    });
+    const byKey = new Map(rows.map((r) => [r.dedupeKey, r]));
+    const domain = homeserverDomain(deps.config);
+    const live = new Set();
+    for (const { member } of people) {
+        const mxid = mxidFromDid(member.did, domain);
+        const dedupeKey = `rvi:${sourceId}:${mxid}`;
+        if (live.has(dedupeKey))
+            continue;
+        live.add(dedupeKey);
+        const row = byKey.get(dedupeKey);
+        if (row?.status === "sent")
+            continue;
+        const invited = await inviteBestEffort(md, roomId, mxid);
+        await ledger(deps, {
+            dedupeKey,
+            kind: "review_invite",
+            sourceId,
+            roomId,
+            targetUrl: mxid,
+            status: invited.ok ? "sent" : "failed",
+            attempts: (row?.attempts ?? 0) + 1,
+            lastError: invited.reason ?? null,
+        });
+    }
+    for (const row of rows) {
+        if (row.status !== "sent" || live.has(row.dedupeKey) || !row.targetUrl)
+            continue;
+        try {
+            await kickUser(md, row.roomId ?? roomId, row.targetUrl, "Your review access ended");
+        }
+        catch (err) {
+            // M_FORBIDDEN: they already left (or were never let in) — nothing more to take away.
+            if (matrixErrcode(err) !== "M_FORBIDDEN") {
+                deps.logger.warn("matrix.review_kick.failed", { sourceId, reason: String(err) });
+                continue;
+            }
+        }
+        // The one move off `sent` (the ledger's upsert never makes it): the access it recorded is gone.
+        await deps.db
+            .update(matrixDeliveries)
+            .set({ status: "dead", lastError: "access ended" })
+            .where(eq(matrixDeliveries.dedupeKey, row.dedupeKey));
+        deps.metrics.count("matrix.review_invite", 1, { status: "dead" });
+    }
+}
+/**
+ * The hourly pass over the review rooms: kick whoever lost access since (and retry a failed
+ * invite). `ROOMS_PER_PASS` rooms a pass, least recently synced first — the room marker's
+ * `updatedAt` is the rotation's cursor, touched after each sync.
+ */
+export async function syncReviewRooms(deps, now = new Date()) {
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN)
+        return;
+    const md = matrixDeps(deps);
+    if (!(await matrixLaneReady(md)))
+        return;
+    const rooms = await deps.db
+        .select({ dedupeKey: matrixDeliveries.dedupeKey, sourceId: apiSources.sourceId })
+        .from(matrixDeliveries)
+        // An API source's room is `review_room:<sourceId>` (the chain lane's carry an owner too).
+        .innerJoin(apiSources, eq(matrixDeliveries.dedupeKey, sql `'review_room:' || ${apiSources.sourceId}`))
+        .where(and(eq(matrixDeliveries.kind, "review_room"), eq(matrixDeliveries.status, "sent"), sql `${matrixDeliveries.roomId} is not null`))
+        .orderBy(matrixDeliveries.updatedAt)
+        .limit(ROOMS_PER_PASS);
+    for (const { dedupeKey, sourceId } of rooms) {
+        const room = await marker(deps.db, dedupeKey);
+        if (room?.roomId) {
+            await syncRoom(deps, sourceId, room.roomId, await reviewers(deps.db, sourceId, now));
+        }
+        await deps.db
+            .update(matrixDeliveries)
+            .set({ updatedAt: now })
+            .where(eq(matrixDeliveries.dedupeKey, dedupeKey));
+    }
+}
+// --- who, and which claims ---------------------------------------------------------------------
+/** Every accepted member of the source whose live grant carries `claims/review` — the root included. */
+async function reviewers(db, sourceId, now) {
+    return (await liveMembers(db, sourceId, now)).filter((p) => covers(p.grant.capabilities, "claims/review"));
+}
+/**
+ * Who is emailed about `claims` (§5, §6, the reminders): the review-capable members, plus the
+ * source's `contactEmail` — unless a member with that same address is sent EVERY claim the contact
+ * would be (case-insensitive), so one inbox never gets the same email twice.
+ */
+function recipientsOf(source, people, claims) {
+    const members = people.map(memberRecipient);
+    const contact = contactOf(source);
+    const covered = members.some((r) => r.to.toLowerCase() === contact?.to.toLowerCase() && claims.every(r.reaches));
+    return contact && !covered ? [...members, contact] : members;
+}
+function memberRecipient(person) {
+    return {
+        key: person.member.memberId,
+        to: person.member.email ?? "",
+        audience: audienceOf(person.member),
+        reaches: (claim) => canEmail(person, claim.protocolDid),
+    };
+}
+/** The source's contact as a recipient — every claim is theirs — or null without an address. */
+function contactOf(source) {
+    const to = source?.contactEmail?.trim();
+    return to ? { key: CONTACT, to, audience: "contact", reaches: () => true } : null;
+}
+/** The email half's filter: the protocol reached, an address, and the member's own switch on. */
+function canEmail({ member, grant }, protocolDid) {
+    return Boolean(member.email) && member.notifyReviews && reachesProtocol(grant, protocolDid);
+}
+/** A paid claim past its `answerBy`: closed to answers (`REVIEW_EXPIRED`), so owed no notice. */
+const closed = (claim, now) => claim.answerBy != null && claim.answerBy.getTime() <= now.getTime();
+/**
+ * The paid claims whose review closed unanswered (§10: `review_expired`) and are not yet announced
+ * — no `notice_review_expired:` marker — oldest deadline first, bounded like every pass. The SQL
+ * is `answerByOf`'s twin (the extended expiry, else the charge's `createdAt` + 24 h, less the
+ * margin), re-checked with the function itself so the two can never disagree about a claim.
+ */
+export async function expiredReviews(db, now) {
+    const expiry = sql `coalesce(${apiCharges.reservationExpiresAt}, ${apiCharges.createdAt} + ${DAY_MS})`;
+    const rows = await awaitingQuery(db)
+        .where(and(awaitingFilter(), sql `${expiry} <= ${now.getTime() + ANSWER_BY_MARGIN_MS}`, sql `not exists (select 1 from ${matrixDeliveries} where ${matrixDeliveries.dedupeKey} = 'notice_review_expired:' || ${apiClaims.claimId})`))
+        .orderBy(expiry)
+        .limit(PASS_LIMIT);
+    return rows.map(toAwaiting).filter((c) => closed(c, now));
+}
+/** Pending review, unanswered (no `claim_reviews` row yet), body not erased. */
+function awaitingFilter() {
+    return and(eq(decisions.status, "pending_review"), isNull(claimReviews.claimId), isNull(apiClaims.bodyErasedAt));
+}
+function awaitingQuery(db) {
+    return db
+        .select({
+        claimId: apiClaims.claimId,
+        sourceId: apiClaims.sourceId,
+        protocolDid: apiClaims.protocolDid,
+        decidedAt: decisions.createdAt,
+        decision: decisions.decision,
+        // A paid claim's review deadline (the record's `review.answerBy`): no charge ⇒ none.
+        chargedAt: apiCharges.createdAt,
+        reservationExpiresAt: apiCharges.reservationExpiresAt,
+    })
+        .from(apiClaims)
+        .innerJoin(decisions, eq(decisions.claimId, apiClaims.claimId))
+        .leftJoin(claimReviews, eq(claimReviews.claimId, apiClaims.claimId))
+        .leftJoin(apiCharges, eq(apiCharges.claimId, apiClaims.claimId));
+}
+function toAwaiting(row) {
+    return {
+        claimId: row.claimId,
+        sourceId: row.sourceId,
+        protocolDid: row.protocolDid,
+        // No protocol catalogue with names yet (S8's `GET /v1/api/protocols`): the DID stands in.
+        protocol: row.protocolDid,
+        questions: row.decision?.pendingTasks?.length ?? 0,
+        waitingSince: row.decidedAt,
+        answerBy: row.chargedAt
+            ? answerByOf({ createdAt: row.chargedAt, reservationExpiresAt: row.reservationExpiresAt })
+            : null,
+    };
+}
+async function awaitingReview(db, claimIds) {
+    const out = new Map();
+    for (let i = 0; i < claimIds.length; i += IN_CHUNK) {
+        const rows = await awaitingQuery(db).where(and(awaitingFilter(), inArray(apiClaims.claimId, claimIds.slice(i, i + IN_CHUNK))));
+        for (const row of rows)
+            out.set(row.claimId, toAwaiting(row));
+    }
+    return out;
+}
+/** §5's footer: a reviewer is told they are one; an owner or developer that they can review. */
+function audienceOf(member) {
+    return member.role === "reviewer" ? "reviewer" : "member";
+}
+function emailBase(deps, source) {
+    return {
+        brand: getOracle().config.name,
+        consoleUrl: deps.config.CONSOLE_URL,
+        oracleUrl: oracleApiUrl(deps.config),
+        source: { id: source.sourceId, name: source.name },
+    };
+}
+/** The whole email half off, logged once per call — so an oracle without email writes no rows. */
+function emailLaneOn(deps, kind) {
+    if (deps.email && deps.config.EMAIL_FROM_ADDRESS)
+        return true;
+    deps.logger.info(`email.${kind}.skipped`, {
+        reason: "EMAIL or EMAIL_FROM_ADDRESS not configured",
+    });
+    return false;
+}
+function send(deps, to, kind, mail) {
+    return sendEmail(deps, { to, kind, ...mail });
+}
+function failedText(outcome) {
+    return outcome === "failed" ? "email send failed" : null;
+}
+function marker(db, dedupeKey) {
+    return db.query.matrixDeliveries.findFirst({ where: eq(matrixDeliveries.dedupeKey, dedupeKey) });
+}
+/**
+ * Take the email rows this caller will send: new ones inserted `sending`, `failed` ones (under
+ * `MAX_ATTEMPTS`) taken over. The keys owned — a key owned by nobody else, so no two callers ever
+ * send the same email; everything else (sent, sending, held, skipped, out of attempts) is left be.
+ */
+async function claimRows(db, rows) {
+    const owned = new Set();
+    for (let i = 0; i < rows.length; i += ROW_CHUNK) {
+        const chunk = rows.slice(i, i + ROW_CHUNK);
+        const inserted = await db
+            .insert(matrixDeliveries)
+            .values(chunk.map((r) => ({ ...r, status: "sending", attempts: 1 })))
+            .onConflictDoNothing()
+            .returning({ dedupeKey: matrixDeliveries.dedupeKey });
+        for (const r of inserted)
+            owned.add(r.dedupeKey);
+        const rest = chunk.map((r) => r.dedupeKey).filter((k) => !owned.has(k));
+        if (rest.length === 0)
+            continue;
+        const retaken = await db
+            .update(matrixDeliveries)
+            .set({ status: "sending", attempts: sql `${matrixDeliveries.attempts} + 1`, lastError: null })
+            .where(and(inArray(matrixDeliveries.dedupeKey, rest), eq(matrixDeliveries.status, "failed"), sql `${matrixDeliveries.attempts} < ${MAX_ATTEMPTS}`))
+            .returning({ dedupeKey: matrixDeliveries.dedupeKey });
+        for (const r of retaken)
+            owned.add(r.dedupeKey);
+    }
+    return owned;
+}
+/** Mark rows with an outcome — never a row already `sent` (a racing caller's send stands). */
+async function settle(deps, kind, keys, status) {
+    for (let i = 0; i < keys.length; i += IN_CHUNK) {
+        await deps.db
+            .update(matrixDeliveries)
+            .set({ status, lastError: failedText(status) })
+            .where(and(inArray(matrixDeliveries.dedupeKey, keys.slice(i, i + IN_CHUNK)), ne(matrixDeliveries.status, "sent")));
+    }
+    deps.metrics.count(`matrix.${kind}`, keys.length, { status });
+}
+/** One upsert per row — the lane's marker, and its `matrix.<kind>` count. Never moves off `sent`. */
+async function ledger(deps, row) {
+    await deps.db
+        .insert(matrixDeliveries)
+        .values(row)
+        .onConflictDoUpdate({
+        target: matrixDeliveries.dedupeKey,
+        set: {
+            status: row.status ?? "failed",
+            roomId: row.roomId ?? null,
+            eventId: row.eventId ?? null,
+            targetUrl: row.targetUrl ?? null,
+            attempts: row.attempts ?? 0,
+            lastError: row.lastError ?? null,
+            updatedAt: new Date(),
+        },
+        setWhere: ne(matrixDeliveries.status, "sent"),
+    });
+    deps.metrics.count(`matrix.${row.kind}`, 1, { status: row.status ?? "failed" });
+}
+//# sourceMappingURL=reviewers.js.map