@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/matrix/deliver.js

@@ -0,0 +1,788 @@
+/**
+ * The Matrix side-effect lane — sends the in-chat review card when a decision needs a human, and
+ * edits it to "completed" when the fold lands. There is ONE room kind (the collection's review
+ * room: the owner and the reviewers the company granted — `syncCollectionReviewers`; no
+ * channel/assignee routing, no dispute rooms), so the room identity lives here beside the delivery
+ * instead of in its own file.
+ *
+ * Same three properties, for the same reasons as every other side-effect lane in this kit:
+ *  - **Idempotent.** Every function is `check marker → do → record marker`, over two overlapping
+ *    layers: the `matrix_deliveries.dedupeKey` row (durable) and a deterministic Matrix `txnId`
+ *    (Synapse-side, bounded window). Re-entering a lane after a workflow-step retry costs zero HTTP.
+ *  - **Fail-soft.** Matrix must never block or fail a claim's ingest or fold. Nothing here throws
+ *    for a Matrix-side failure: the outcome is recorded on the delivery row and returned.
+ *    `ORACLE_MATRIX_ACCESS_TOKEN` unset ⇒ every lane logs one line and returns `skipped` — what
+ *    local dev and every test run look like.
+ *  - **Self-contained.** Every function reads everything it needs from the DB, so a workflow step
+ *    passes only the claimId — exactly like `deliverChainEvaluation` (lib/ixo/chain-write.ts).
+ *
+ * The review room is keyed on the STABLE pair `(collectionId, ownerDid)` — never one room per
+ * claim, and never `rubricId` (a re-anchored rubric would otherwise mint a new room every time).
+ *
+ * `sendWithRejoin` ports v1's E3 recovery (eval-engine deliver.ts:496-521) uniformly to both
+ * `sendEvent` call sites: a `M_FORBIDDEN` posting into a room this oracle CREATED means membership
+ * itself broke after the fact (an operator removed the bot, a homeserver hiccup), never "we were
+ * never let in" — one `joinRoom`, one re-send; still failing records `oracle_not_in_room`, never
+ * the invite lane's `user_not_on_homeserver` label.
+ */
+import { and, eq, like, sql } from "drizzle-orm";
+import { matrixDeliveries, watchedCollections, } from "../../db/schema.js";
+import { getOracle } from "../../oracle.js";
+import { sendEmail } from "../email/send.js";
+import { renderReviewRequestEmail } from "../email/template.js";
+import { isManifestUnusable } from "../engine/types.js";
+import { cidForBytes, sha256Hex } from "../hash.js";
+import { countCache, readCache } from "../metrics.js";
+import { liveReviewerGrants } from "../review/reviewer-grant.js";
+import { reviewTaskOf } from "../review/tasks.js";
+import { createRoom, inviteUser, joinRoom, kickUser, resolveAlias, sendEvent, whoami, } from "./api.js";
+import { matrixErrcode, matrixErrorText } from "./client.js";
+import { buildEvalContext, buildReviewFold, buildReviewRequest, EVAL_CONTEXT_TYPE, EVAL_REVIEW_REQUEST_TYPE, oracleEntityDid, reviewLink, } from "./events.js";
+import { homeserverDomain, mxidFromDid } from "./mxid.js";
+// --- identity guard (v1's lib/matrix/identity.ts pattern) ----------------------------------------
+/** One hour — ops sees a dead token long before reviews pile up. */
+const WHOAMI_TTL_SEC = 3600;
+let memo = null;
+/**
+ * `whoami()` must answer `ORACLE_MATRIX_USER_ID` — nothing else proves the configured token
+ * belongs to OUR oracle, and the wrong token would post review cards (and own rooms) as somebody
+ * else's account. Cost: one `whoami` per hour, not per delivery, cached both in-isolate and in
+ * `CACHE_KV` (keyed on a token-hash prefix, so the token itself never enters a KV key and a
+ * rotated secret re-checks immediately). Only DETERMINISTIC answers are cached.
+ */
+export async function matrixIdentity(deps) {
+    const { config } = deps;
+    if (!config.ORACLE_MATRIX_ACCESS_TOKEN)
+        return { status: "unconfigured" };
+    const key = `matrix-whoami:${(await sha256Hex(config.ORACLE_MATRIX_ACCESS_TOKEN)).slice(0, 32)}`;
+    countCache("matrix-whoami-l1", memo?.key === key);
+    if (memo?.key === key)
+        return memo.value;
+    const cached = await readCache("matrix-whoami", () => deps.cache.get(key, "json"));
+    if (cached) {
+        memo = { key, value: cached };
+        return cached;
+    }
+    let identity;
+    try {
+        const { user_id } = await whoami(deps);
+        identity =
+            user_id === config.ORACLE_MATRIX_USER_ID
+                ? { status: "ok", userId: user_id }
+                : { status: "mismatch", userId: user_id, expected: config.ORACLE_MATRIX_USER_ID };
+    }
+    catch (err) {
+        // A 401 already logged `matrix.token-invalid` in client.ts; anything else is a homeserver
+        // blip. Never cached — the next call re-checks.
+        return { status: "unreachable", detail: String(err) };
+    }
+    memo = { key, value: identity };
+    await deps.cache
+        .put(key, JSON.stringify(identity), { expirationTtl: WHOAMI_TTL_SEC })
+        .catch(() => { });
+    return identity;
+}
+/**
+ * The gate every fail-soft lane opens with. `false` ⇒ the token belongs to another account:
+ * deliver nothing, log loudly, leave the caller alone. Every other state returns `true` — the
+ * lane's own `skipped`/`failed` recording takes it from there, because Matrix trouble must never
+ * become the caller's problem.
+ */
+export async function matrixLaneReady(deps) {
+    const identity = await matrixIdentity(deps);
+    if (identity.status !== "mismatch")
+        return true;
+    deps.logger.error("matrix.identity-mismatch", {
+        userId: identity.userId,
+        expected: identity.expected,
+    });
+    return false;
+}
+// --- markers --------------------------------------------------------------------------------------
+function marker(deps, dedupeKey) {
+    return deps.runDb((db) => db.query.matrixDeliveries.findFirst({
+        where: (t, { eq: eqOp }) => eqOp(t.dedupeKey, dedupeKey),
+    }));
+}
+/** The one upsert into `matrix_deliveries` — every lane's marker, and its `matrix.<kind>` count. */
+async function record(deps, row) {
+    await deps.runDb((db) => db
+        .insert(matrixDeliveries)
+        .values(row)
+        .onConflictDoUpdate({
+        target: matrixDeliveries.dedupeKey,
+        set: {
+            status: row.status ?? "failed",
+            roomId: row.roomId ?? null,
+            eventId: row.eventId ?? null,
+            resultDigest: row.resultDigest ?? null,
+            attempts: row.attempts ?? 0,
+            lastError: row.lastError ?? null,
+            updatedAt: new Date(),
+        },
+    }));
+    deps.metrics.count(`matrix.${row.kind}`, 1, { status: row.status ?? "failed" });
+}
+/** One log line per outcome, always with the same fields. */
+function skip(deps, kind, reason, fields = {}) {
+    deps.logger.info(`matrix.${kind}.skipped`, { reason, ...fields });
+    deps.metrics.count(`matrix.${kind}`, 1, { status: "skipped" });
+    return "skipped";
+}
+// --- deterministic ids ------------------------------------------------------------------------
+export async function aliasLocalpart(prefix, key) {
+    return `${prefix}-${(await sha256Hex(key)).slice(0, 32)}`;
+}
+/** Synapse dedups repeated PUTs on `(access_token, txnId)` — a cheap first line, not the guarantee. */
+export async function transactionId(dedupeKey) {
+    return `orc-rr-${(await sha256Hex(dedupeKey)).slice(0, 16)}`;
+}
+// --- shared failure reading --------------------------------------------------------------------
+/** Synapse answers `403 M_FORBIDDEN … is already in the room`. That is SUCCESS. */
+function alreadyInRoom(err) {
+    return matrixErrcode(err) === "M_FORBIDDEN" && /already in the room/i.test(matrixErrorText(err));
+}
+function failureReason(err) {
+    const errcode = matrixErrcode(err);
+    // A DID whose owner has never logged into the portal has no Matrix account to invite.
+    if (errcode === "M_FORBIDDEN")
+        return "user_not_on_homeserver";
+    if (errcode === "M_NOT_FOUND")
+        return "unknown_room";
+    return errcode ?? String(err);
+}
+/**
+ * After `sendWithRejoin` has ALREADY tried one join-and-retry, a remaining `M_FORBIDDEN` means the
+ * oracle itself is locked out of a room it owns — a distinct failure from `failureReason`'s
+ * `user_not_on_homeserver` (which is about the OWNER we invited, not us), so callers logging a
+ * send failure use this instead.
+ */
+export function sendFailureReason(err) {
+    if (matrixErrcode(err) === "M_FORBIDDEN" && !alreadyInRoom(err))
+        return "oracle_not_in_room";
+    return failureReason(err);
+}
+/**
+ * E3 (v1 deliver.ts:496-521) — we are not in the room (removed after creation, or a homeserver
+ * hiccup on the very first send). One join, one re-send; a second failure of any kind propagates
+ * to the caller's own failure recording untouched.
+ */
+export async function sendWithRejoin(deps, roomId, eventType, txnId, content) {
+    try {
+        return await sendEvent(deps, roomId, eventType, txnId, content);
+    }
+    catch (err) {
+        if (matrixErrcode(err) !== "M_FORBIDDEN" || alreadyInRoom(err))
+            throw err;
+        await joinRoom(deps, roomId);
+        return sendEvent(deps, roomId, eventType, txnId, content);
+    }
+}
+/** Invites are best-effort: the room stands, and the next lane run retries. */
+export async function inviteBestEffort(deps, roomId, userId, reason) {
+    try {
+        await inviteUser(deps, roomId, userId, reason);
+        return { ok: true };
+    }
+    catch (err) {
+        if (alreadyInRoom(err))
+            return { ok: true };
+        const why = failureReason(err);
+        deps.logger.warn("matrix.invite-failed", { roomId, reason: why });
+        return { ok: false, reason: why };
+    }
+}
+// --- room creation ----------------------------------------------------------------------------
+/**
+ * The create-or-reuse path every engine-owned room shares (this kit has exactly one kind):
+ *
+ *   sent marker ⇒ return roomId (durable reuse, zero HTTP)
+ *   else createRoom(alias, …) → 200 ⇒ record sent
+ *                             → M_ROOM_IN_USE ⇒ resolve the alias to the same room
+ *                             → anything else ⇒ record failed, return null (fail-soft)
+ */
+export async function createOrReuseRoom(deps, input) {
+    const { dedupeKey, collectionId } = input;
+    const kind = "review_room";
+    const existing = await marker(deps, dedupeKey);
+    if (existing?.status === "sent" && existing.roomId)
+        return existing.roomId;
+    const attempts = (existing?.attempts ?? 0) + 1;
+    const base = { dedupeKey, kind, claimId: null, collectionId, attempts };
+    try {
+        const { room_id } = await createRoom(deps, input.payload);
+        await record(deps, { ...base, roomId: room_id, status: "sent" });
+        deps.logger.info("matrix.review_room.created", { collectionId, roomId: room_id });
+        return room_id;
+    }
+    catch (err) {
+        if (matrixErrcode(err) !== "M_ROOM_IN_USE") {
+            await record(deps, { ...base, status: "failed", lastError: String(err) });
+            deps.logger.warn("matrix.review_room.failed", { collectionId, reason: failureReason(err) });
+            return null;
+        }
+    }
+    // Our deterministic alias already exists: the room is ours, resolve it. Never create twice.
+    const alias = `#${input.alias}:${homeserverDomain(deps.config)}`;
+    try {
+        const { room_id } = await resolveAlias(deps, alias);
+        if (input.invitee)
+            await inviteBestEffort(deps, room_id, input.invitee);
+        await record(deps, { ...base, roomId: room_id, status: "sent" });
+        deps.logger.info("matrix.review_room.reused", { collectionId, roomId: room_id });
+        return room_id;
+    }
+    catch (err) {
+        await record(deps, { ...base, status: "failed", lastError: String(err) });
+        deps.logger.warn("matrix.review_room.failed", { collectionId, reason: failureReason(err) });
+        return null;
+    }
+}
+/**
+ * The oracle-owned review room for a collection: created LAZILY at the first claim that needs
+ * review, reused for every later one. Keyed `(collectionId, ownerDid)` — never per claim, never
+ * per rubric (a re-anchored rubric must not orphan and re-mint the room).
+ */
+export async function ensureReviewRoom(deps, collectionId, ownerDid) {
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN) {
+        skip(deps, "review_room", "ORACLE_MATRIX_ACCESS_TOKEN not configured", { collectionId });
+        return null;
+    }
+    const { config } = deps;
+    const oracle = config.ORACLE_MATRIX_USER_ID;
+    const ownerMxid = mxidFromDid(ownerDid, homeserverDomain(config));
+    const alias = await aliasLocalpart("oracle-review", `${collectionId}|${ownerDid}`);
+    return createOrReuseRoom(deps, {
+        dedupeKey: `review_room:${collectionId}:${ownerDid}`,
+        alias,
+        collectionId,
+        invitee: ownerMxid,
+        payload: {
+            name: `Reviews — collection ${collectionId}`,
+            topic: "Claims from this collection that need your review.",
+            preset: "private_chat",
+            visibility: "private",
+            room_alias_name: alias,
+            invite: [ownerMxid],
+            // invite:50 keeps membership an ORACLE decision (the owner is PL 0 and cannot add anyone);
+            // events_default is 0, so they can already answer inline — no power-level work needed.
+            power_level_content_override: { invite: 50, users: { [oracle]: 100 } },
+            initial_state: [
+                {
+                    type: "m.room.encryption",
+                    state_key: "",
+                    content: {
+                        algorithm: "m.megolm.v1.aes-sha2",
+                        rotation_period_ms: 604_800_000,
+                        rotation_period_msgs: 100,
+                    },
+                },
+                { type: "m.room.guest_access", state_key: "", content: { guest_access: "forbidden" } },
+                {
+                    type: "m.room.history_visibility",
+                    state_key: "",
+                    content: { history_visibility: "invited" },
+                },
+                {
+                    type: EVAL_CONTEXT_TYPE,
+                    state_key: "",
+                    content: buildEvalContext(config, {
+                        collectionId,
+                        createdAt: new Date(),
+                    }),
+                },
+            ],
+        },
+    });
+}
+// --- the collection's reviewers (company authority D2) ------------------------------------------
+/** Chain review rooms re-synced per hourly pass. */
+const REVIEW_ROOMS_PER_PASS = 20;
+/**
+ * The review room follows the collection's reviewer grants: every grant that stands now
+ * (`liveReviewerGrants` — unrevoked, in its window, its root still a controller of the entity) is
+ * invited, and whoever was invited and no longer stands is kicked — never the owner, whose seat is
+ * the room's own (`ensureReviewRoom`). One `crvi:<collectionId>:<mxid>` row per person — keyed by
+ * the MXID (`mxidFromDid`, the portal's own derivation), so a reviewer granted again after a revoke
+ * finds their row, never a second invite plus a kick from the old one; a row sent into another
+ * room (a re-register under a new owner made this one) is not an invite here. Who may ANSWER is
+ * the gate's (lib/review/reviewer-grant.ts), re-checked at every answer and fold; the room only
+ * tells. Best-effort: a failed invite is a row the next pass retries, and nothing here ever throws
+ * — Blocksync down skips the whole sync, so nobody is kicked on a blip.
+ */
+export async function syncCollectionReviewers(deps, collection, roomId, now = new Date()) {
+    const { collectionId } = collection;
+    try {
+        const [grants, rows] = await deps.runDb((db) => Promise.all([
+            liveReviewerGrants(deps, db, collectionId, { now }),
+            db.query.matrixDeliveries.findMany({
+                where: and(eq(matrixDeliveries.kind, "review_invite"), eq(matrixDeliveries.collectionId, collectionId), 
+                // The chain lane's rows; an API source's own `rvi:` rows never carry a collection.
+                like(matrixDeliveries.dedupeKey, "crvi:%")),
+            }),
+        ]));
+        const byKey = new Map(rows.map((r) => [r.dedupeKey, r]));
+        const domain = homeserverDomain(deps.config);
+        const ownerMxid = mxidFromDid(collection.ownerDid, domain);
+        const live = new Set();
+        for (const { memberDid } of grants) {
+            const mxid = mxidFromDid(memberDid, domain);
+            const dedupeKey = `crvi:${collectionId}:${mxid}`;
+            if (mxid === ownerMxid || live.has(dedupeKey))
+                continue;
+            live.add(dedupeKey);
+            const row = byKey.get(dedupeKey);
+            if (row?.status === "sent" && row.roomId === roomId)
+                continue;
+            const invited = await inviteBestEffort(deps, roomId, mxid, "You review this collection's claims");
+            await record(deps, {
+                dedupeKey,
+                kind: "review_invite",
+                claimId: null,
+                collectionId,
+                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;
+            if (row.targetUrl === ownerMxid)
+                continue;
+            try {
+                await kickUser(deps, 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", { collectionId, reason: String(err) });
+                    continue;
+                }
+            }
+            await deps.runDb((db) => db
+                .update(matrixDeliveries)
+                .set({ status: "dead", lastError: "access ended", updatedAt: new Date() })
+                .where(eq(matrixDeliveries.dedupeKey, row.dedupeKey)));
+            deps.metrics.count("matrix.review_invite", 1, { status: "dead" });
+        }
+    }
+    catch (err) {
+        deps.logger.warn("matrix.review_invite.failed", { collectionId, reason: String(err) });
+    }
+}
+/**
+ * The collection's review room as it stands — the CURRENT owner's (`review_room:<id>:<ownerDid>`)
+ * — synced to its grants now (a revoke kicks at once), or nothing when no room was ever made.
+ */
+export async function syncCollectionReviewRoom(deps, collectionId) {
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN || !(await matrixLaneReady(deps)))
+        return;
+    const [room] = await deps.runDb((db) => roomsQuery(db).where(and(roomsLive(), eq(watchedCollections.collectionId, collectionId))));
+    if (room?.roomId)
+        await syncCollectionReviewers(deps, room, room.roomId);
+}
+/**
+ * The hourly pass over the chain review rooms: kick whoever's grant expired since, or whose root
+ * is no longer a controller of the entity (a revoke kicked already), and retry a failed invite. `REVIEW_ROOMS_PER_PASS` a pass, least recently synced first
+ * — the room marker's `updatedAt` is the rotation's cursor, touched after each sync (as the API
+ * lane's `syncReviewRooms`).
+ */
+export async function syncChainReviewRooms(deps, now = new Date()) {
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN || !(await matrixLaneReady(deps)))
+        return;
+    const rooms = await deps.runDb((db) => roomsQuery(db)
+        .where(roomsLive())
+        .orderBy(matrixDeliveries.updatedAt)
+        .limit(REVIEW_ROOMS_PER_PASS));
+    for (const room of rooms) {
+        const { roomId, dedupeKey } = room;
+        if (roomId)
+            await syncCollectionReviewers(deps, room, roomId, now);
+        await deps.runDb((db) => db
+            .update(matrixDeliveries)
+            .set({ updatedAt: now })
+            .where(eq(matrixDeliveries.dedupeKey, dedupeKey)));
+    }
+}
+/** A watched collection's review room marker — keyed on its CURRENT `ownerDid` (`ensureReviewRoom`). */
+const roomsQuery = (db) => db
+    .select({
+    collectionId: watchedCollections.collectionId,
+    ownerDid: watchedCollections.ownerDid,
+    roomId: matrixDeliveries.roomId,
+    dedupeKey: matrixDeliveries.dedupeKey,
+})
+    .from(matrixDeliveries)
+    .innerJoin(watchedCollections, eq(matrixDeliveries.dedupeKey, sql `'review_room:' || ${watchedCollections.collectionId} || ':' || ${watchedCollections.ownerDid}`))
+    .$dynamic();
+const roomsLive = () => and(eq(matrixDeliveries.kind, "review_room"), eq(matrixDeliveries.status, "sent"), sql `${matrixDeliveries.roomId} is not null`);
+// --- review tasks -------------------------------------------------------------------------------
+/**
+ * `decision.pendingTasks` ⨯ the manifest's `review.taskDetails` — id/prompt/answer, nothing else.
+ * Falls back to the bare id as its own prompt (and a boolean answer) when the engine has not sent
+ * `taskDetails` yet, or a given pending task has no entry in it (engine T9 is additive) — except
+ * the engine's synthetic `unique:<ruleId>` / `checks:held`, which are always approve/reject
+ * (lib/review/tasks.ts).
+ */
+export function reviewTasks(pendingTaskIds, review) {
+    return pendingTaskIds.map((id) => reviewTaskOf(id, review));
+}
+// --- the review-request send ---------------------------------------------------------------------
+/**
+ * The `notify-review` workflow step's whole body. Self-contained: it reads everything from the
+ * DB, so the workflow passes only the claimId.
+ *
+ * A clean no-op (one log line) when: `ORACLE_MATRIX_ACCESS_TOKEN` is unset; no decision is
+ * recorded for the claim; the decision is not `pending_review`; it has no pending tasks; the
+ * collection is not watched or has no protocol; the engine's rubric manifest is unusable; or a
+ * `sent` marker already exists.
+ *
+ * The `review_request` (Matrix) and `notice_review_email` markers are independent (header), which
+ * matters most on the ONE path where they can end up out of step: Matrix sends fine, the email
+ * throws in the SAME invocation (an `allSettled` rejection below) — and the workflow step that
+ * calls this memoizes its return forever once `review_request` is `sent`, so nothing would ever
+ * call this function's full body again. The `existing?.status === "sent"` branch below is that
+ * function's ONLY remaining production entry point for such a claim, so it doubles as the email's
+ * retry point: absent-or-failed AND a contact email on file → attempt just the email (no Matrix
+ * re-send, no room work) before reporting the now-familiar `skipped`.
+ */
+export async function deliverReviewRequest(deps, engine, claimId) {
+    const { config } = deps;
+    if (!config.ORACLE_MATRIX_ACCESS_TOKEN) {
+        return skip(deps, "review_request", "ORACLE_MATRIX_ACCESS_TOKEN not configured", { claimId });
+    }
+    const decision = await deps.runDb((db) => db.query.decisions.findFirst({ where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId) }));
+    if (!decision)
+        return skip(deps, "review_request", "no decision recorded", { claimId });
+    if (decision.status !== "pending_review") {
+        return skip(deps, "review_request", "decision is not pending review", { claimId });
+    }
+    const pendingTasks = decision.decision?.pendingTasks ?? [];
+    if (pendingTasks.length === 0) {
+        return skip(deps, "review_request", "no pending tasks on the decision", { claimId });
+    }
+    const { collectionId } = decision;
+    // Sent-once, forever: one notification per claim. Checked before any HTTP.
+    const dedupeKey = `review_request:${claimId}`;
+    const existing = await marker(deps, dedupeKey);
+    if (existing?.status === "sent") {
+        // See the header: the email twin gets its one remaining retry chance HERE.
+        await retryReviewRequestEmailOnly(deps, {
+            claimId,
+            collectionId,
+            resultDigest: decision.resultDigest ?? null,
+        });
+        return skip(deps, "review_request", "already sent", { claimId, roomId: existing.roomId });
+    }
+    const attempts = (existing?.attempts ?? 0) + 1;
+    // The PRE-fold digest, captured here for `deliverReviewFold` to read back later — by the time
+    // the fold runs, `decisions.resultDigest` has already been overwritten with the NEW one.
+    const base = {
+        dedupeKey,
+        kind: "review_request",
+        claimId,
+        collectionId,
+        resultDigest: decision.resultDigest ?? null,
+        attempts,
+    };
+    const watched = await deps.runDb((db) => db.query.watchedCollections.findFirst({
+        where: (t, { eq: eqOp }) => eqOp(t.collectionId, collectionId),
+    }));
+    if (!watched?.protocolDid) {
+        return skip(deps, "review_request", "collection is not watched or has no protocol", {
+            claimId,
+        });
+    }
+    const manifest = await engine.getManifest(watched.protocolDid);
+    if (isManifestUnusable(manifest)) {
+        return skip(deps, "review_request", "rubric manifest is unusable", { claimId });
+    }
+    const tasks = reviewTasks(pendingTasks, manifest.review);
+    const roomId = await ensureReviewRoom(deps, collectionId, watched.ownerDid);
+    if (!roomId) {
+        await record(deps, { ...base, status: "failed", lastError: "no review room" });
+        deps.logger.warn("matrix.review_request.failed", { claimId, reason: "no review room" });
+        return "failed";
+    }
+    // The people who answer it (company authority D2): the owner alone no longer reviews.
+    await syncCollectionReviewers(deps, watched, roomId);
+    const content = buildReviewRequest(config, {
+        claimId,
+        collectionId,
+        rubricId: decision.rubricId ?? "",
+        resultDigest: decision.resultDigest ?? "",
+        oracleDid: oracleEntityDid(config),
+        tasks,
+    });
+    const txnId = await transactionId(dedupeKey);
+    // The Matrix card and its email twin are dispatched together under `allSettled` (header): a
+    // rendering bug or a DB blip on the email side must never cost the Matrix send, and vice versa.
+    // Sent-once per (claimId, resultDigest) via its OWN marker — independent of `review_request` so
+    // the two lanes can each retry on their own terms.
+    const emailDedupeKey = `notice_review_email:${claimId}:${decision.resultDigest ?? ""}`;
+    const [matrixSettled, emailSettled] = await Promise.allSettled([
+        (async () => {
+            try {
+                const { event_id } = await sendWithRejoin(deps, roomId, EVAL_REVIEW_REQUEST_TYPE, txnId, content);
+                await record(deps, { ...base, roomId, eventId: event_id, status: "sent" });
+                deps.logger.info("matrix.review_request.sent", { claimId, roomId, eventId: event_id });
+                return "sent";
+            }
+            catch (err) {
+                await record(deps, { ...base, roomId, status: "failed", lastError: String(err) });
+                deps.logger.warn("matrix.review_request.failed", {
+                    claimId,
+                    roomId,
+                    reason: sendFailureReason(err),
+                });
+                return "failed";
+            }
+        })(),
+        sendReviewRequestEmail(deps, {
+            claimId,
+            collectionId,
+            contactEmail: watched.contactEmail,
+            link: content.link,
+            dedupeKey: emailDedupeKey,
+        }),
+    ]);
+    if (emailSettled.status === "rejected") {
+        deps.logger.warn("email.review_request.failed", {
+            claimId,
+            detail: String(emailSettled.reason),
+        });
+    }
+    return matrixSettled.status === "fulfilled" ? matrixSettled.value : "failed";
+}
+/**
+ * The review-request email twin — recipient = the collection's already-loaded `contactEmail`
+ * (never re-fetched), link = the SAME URL `buildReviewRequest` (events.ts) put on the Matrix card
+ * (never re-derived). A clean no-op when there is no contact email, or its own `notice_review_email`
+ * marker is already `sent`. Deliberately does not catch its own errors — the caller dispatches this
+ * under `Promise.allSettled` and logs a rejection, exactly like the Matrix send's own try/catch is
+ * its sibling lane, not a shared one.
+ */
+async function sendReviewRequestEmail(deps, input) {
+    if (!input.contactEmail) {
+        skip(deps, "notice_review_email", "no contact email on the collection", {
+            claimId: input.claimId,
+        });
+        return;
+    }
+    const existing = await marker(deps, input.dedupeKey);
+    if (existing?.status === "sent") {
+        skip(deps, "notice_review_email", "already sent", { claimId: input.claimId });
+        return;
+    }
+    const mail = renderReviewRequestEmail({
+        // The notice is signed with the oracle's own name — this is a package, not one branded service.
+        brand: getOracle().config.name,
+        claimId: input.claimId,
+        collectionId: input.collectionId,
+        link: input.link,
+    });
+    const outcome = await sendEmail(deps, {
+        to: input.contactEmail,
+        subject: mail.subject,
+        html: mail.html,
+        text: mail.text,
+        kind: "review_request",
+    });
+    await record(deps, {
+        dedupeKey: input.dedupeKey,
+        kind: "notice_review_email",
+        claimId: input.claimId,
+        collectionId: input.collectionId,
+        status: outcome,
+        attempts: (existing?.attempts ?? 0) + 1,
+        lastError: outcome === "failed" ? "email send failed" : null,
+    });
+}
+/**
+ * The email's ONE remaining production retry chance (`deliverReviewRequest`'s header comment): once
+ * `review_request` is `sent`, the workflow step that calls this memoizes that outcome forever, so a
+ * same-invocation email failure (an `allSettled` rejection, or a `failed` send) would otherwise
+ * never be tried again. Reads the collection fresh (the main path already loaded it before Matrix
+ * ever ran; this path is only reached AFTER Matrix already succeeded, on a later call) — the extra
+ * read costs nothing next to what it fixes. No Matrix work happens here: no manifest fetch, no
+ * room, no send. `reviewLink` recomputes the SAME url `buildReviewRequest` used the first time
+ * (both are pure functions of `claimId`/`config`), so the reader is taken to the identical claim.
+ *
+ * Never throws — this runs on the `already sent` fast path, not under `allSettled`, so it guards
+ * itself. `sendReviewRequestEmail` already covers "no contact email" and "already sent" as no-ops;
+ * this wrapper adds nothing but the fresh read and the try/catch.
+ */
+async function retryReviewRequestEmailOnly(deps, input) {
+    const dedupeKey = `notice_review_email:${input.claimId}:${input.resultDigest ?? ""}`;
+    try {
+        const existing = await marker(deps, dedupeKey);
+        if (existing?.status === "sent")
+            return; // already told — the common case, one read and done.
+        const watched = await deps.runDb((db) => db.query.watchedCollections.findFirst({
+            where: (t, { eq: eqOp }) => eqOp(t.collectionId, input.collectionId),
+        }));
+        await sendReviewRequestEmail(deps, {
+            claimId: input.claimId,
+            collectionId: input.collectionId,
+            contactEmail: watched?.contactEmail ?? null,
+            link: reviewLink(deps.config, input.claimId),
+            dedupeKey,
+        });
+    }
+    catch (err) {
+        deps.logger.warn("email.review_request.failed", {
+            claimId: input.claimId,
+            detail: String(err),
+        });
+    }
+}
+// --- the fold edit --------------------------------------------------------------------------------
+/**
+ * The `notify-folded` workflow step's whole body — an `m.replace` edit of the SAME event the
+ * review-request sent, flipping `status` to `completed` and stamping `verdict`/`foldedAt`.
+ * Self-contained like `deliverReviewRequest`: reads the folded decision, the answered review's
+ * task ids (`Object.keys(claimReviews.answers)` IS the pre-fold `pendingTasks` set — the route
+ * validates it covers exactly that set, so it survives the fold untouched) and the delivered
+ * request's room/event id off `matrix_deliveries`.
+ *
+ * A clean no-op when: the token is unset; no decision or no completed fold is recorded; no
+ * `review_request` was ever sent for this claim (nothing to edit); the collection/manifest can't
+ * be resolved; or a `review_fold` marker already exists.
+ */
+export async function deliverReviewFold(deps, engine, claimId) {
+    const { config } = deps;
+    if (!config.ORACLE_MATRIX_ACCESS_TOKEN) {
+        return skip(deps, "review_fold", "ORACLE_MATRIX_ACCESS_TOKEN not configured", { claimId });
+    }
+    const [decision, review] = await Promise.all([
+        deps.runDb((db) => db.query.decisions.findFirst({ where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId) })),
+        deps.runDb((db) => db.query.claimReviews.findFirst({ where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId) })),
+    ]);
+    if (!decision || !review?.foldedAt) {
+        return skip(deps, "review_fold", "no folded review recorded", { claimId });
+    }
+    const request = await marker(deps, `review_request:${claimId}`);
+    if (request?.status !== "sent" || !request.roomId || !request.eventId) {
+        return skip(deps, "review_fold", "no review request delivered to fold", { claimId });
+    }
+    // A row from before the resultDigest column existed (or, in principle, one `record()` never
+    // finished writing it) — the fold-edit content requires the PRE-fold digest verbatim (see the
+    // table's header comment), so there is nothing safe to build. Explicit precondition, never an
+    // incidental ZodError from `buildReviewRequest`'s `resultDigest: min(1)` parse.
+    if (!request.resultDigest) {
+        return skip(deps, "review_fold", "review_request predates digest column — fold edit unavailable", {
+            claimId,
+        });
+    }
+    const dedupeKey = `review_fold:${claimId}`;
+    const existing = await marker(deps, dedupeKey);
+    if (existing?.status === "sent") {
+        return skip(deps, "review_fold", "already sent", { claimId, roomId: existing.roomId });
+    }
+    const attempts = (existing?.attempts ?? 0) + 1;
+    const { collectionId } = decision;
+    const base = { dedupeKey, kind: "review_fold", claimId, collectionId, attempts };
+    const watched = await deps.runDb((db) => db.query.watchedCollections.findFirst({
+        where: (t, { eq: eqOp }) => eqOp(t.collectionId, collectionId),
+    }));
+    if (!watched?.protocolDid) {
+        return skip(deps, "review_fold", "collection is not watched or has no protocol", { claimId });
+    }
+    const manifest = await engine.getManifest(watched.protocolDid);
+    if (isManifestUnusable(manifest)) {
+        return skip(deps, "review_fold", "rubric manifest is unusable", { claimId });
+    }
+    const pendingTaskIds = Object.keys(review.answers);
+    const tasks = reviewTasks(pendingTaskIds, manifest.review);
+    const content = buildReviewRequest(config, {
+        claimId,
+        collectionId,
+        rubricId: decision.rubricId ?? "",
+        // The PRE-fold digest the reviewer actually answered against — captured on the
+        // `review_request` row at send time (see its table comment), NEVER `decisions.resultDigest`,
+        // which the fold has already overwritten with the new post-fold digest by now.
+        resultDigest: request.resultDigest ?? "",
+        oracleDid: oracleEntityDid(config),
+        tasks,
+    });
+    // Who signed, addressed by CID — a pure function of the stored bytes, so it is computed here
+    // rather than persisted. Null (both) when the answers were unsigned: see the field's comment in
+    // events.ts — the room is never told a reviewer we cannot prove.
+    const attestationCid = review.attestationJws
+        ? await cidForBytes(new TextEncoder().encode(review.attestationJws))
+        : null;
+    const editContent = buildReviewFold(content, request.eventId, {
+        verdict: decision.verdict,
+        foldedAt: review.foldedAt,
+        reviewerDid: attestationCid ? review.reviewerDid : null,
+        attestationCid,
+    });
+    const txnId = await transactionId(dedupeKey);
+    try {
+        const { event_id } = await sendWithRejoin(deps, request.roomId, EVAL_REVIEW_REQUEST_TYPE, txnId, editContent);
+        await record(deps, { ...base, roomId: request.roomId, eventId: event_id, status: "sent" });
+        deps.logger.info("matrix.review_fold.sent", {
+            claimId,
+            roomId: request.roomId,
+            eventId: event_id,
+        });
+        return "sent";
+    }
+    catch (err) {
+        await record(deps, {
+            ...base,
+            roomId: request.roomId,
+            status: "failed",
+            lastError: String(err),
+        });
+        deps.logger.warn("matrix.review_fold.failed", { claimId, reason: sendFailureReason(err) });
+        return "failed";
+    }
+}
+// --- collection notices (paused / resumed) ----------------------------------------------------------
+/**
+ * A collection notice as a plain `m.room.message` in the collection's review room — the PRIMARY
+ * channel; email is the twin, `workflows/steps.ts`). The room is the
+ * SAME `ensureReviewRoom` the review card uses, so an owner has one room per collection, not one
+ * per lane. `body`/`formattedBody` are the two renders of the ONE `Notice` (lib/email/template.ts
+ * `chatBody`/`noticeHtml`).
+ *
+ * Records NOTHING on `matrix_deliveries`: the caller owns the told-once marker (`notice_paused` /
+ * `notice_resumed`, the alternating pair in steps.ts) and writes this outcome onto it beside the
+ * email's. Never throws — token unset is one `skipped` line, everything else `failed` with the
+ * reason, exactly like the review lanes.
+ */
+export async function sendCollectionNoticeMessage(deps, input) {
+    const { kind, collectionId } = input;
+    if (!deps.config.ORACLE_MATRIX_ACCESS_TOKEN) {
+        const reason = "ORACLE_MATRIX_ACCESS_TOKEN not configured";
+        return { status: skip(deps, kind, reason, { collectionId }), roomId: null, reason };
+    }
+    let roomId = null;
+    try {
+        if (!(await matrixLaneReady(deps))) {
+            return { status: "failed", roomId: null, reason: "identity_mismatch" };
+        }
+        roomId = await ensureReviewRoom(deps, collectionId, input.ownerDid);
+        if (!roomId)
+            return { status: "failed", roomId: null, reason: "no review room" };
+        const txnId = await transactionId(input.dedupeKey);
+        const { event_id } = await sendWithRejoin(deps, roomId, "m.room.message", txnId, {
+            msgtype: "m.text",
+            body: input.body,
+            format: "org.matrix.custom.html",
+            formatted_body: input.formattedBody,
+        });
+        deps.logger.info(`matrix.${kind}.sent`, { collectionId, roomId, eventId: event_id });
+        return { status: "sent", roomId, eventId: event_id };
+    }
+    catch (err) {
+        const reason = sendFailureReason(err);
+        deps.logger.warn(`matrix.${kind}.failed`, { collectionId, roomId, reason });
+        return { status: "failed", roomId, reason };
+    }
+}
+//# sourceMappingURL=deliver.js.map