limn-review 0.1.123

package/dist/db/pr-liveness.js

@@ -0,0 +1,240 @@
+// Pending-board liveness — the DATABASE half (target resolution + the narrow write-back).
+//
+// The GitHub half is github/pr-liveness.ts; the route that composes the two is
+// `POST /api/attention/liveness` in api/routes/insights.ts. This module owns two things:
+//
+//   1. RESOLVING a client-supplied list of local PR ids to GitHub node ids, under the account
+//      AND the resolved workspace's membership. That resolve IS the isolation guarantee for a
+//      route whose ids arrive in a request body: an id belonging to another tenant, to another
+//      workspace, or to nothing at all simply does not come back, so it can never reach GitHub
+//      and can never be written to. (scripts/verify-isolation.ts exercises it directly.)
+//   2. APPLYING what GitHub said, one narrow UPDATE per genuinely-moved row.
+//
+// It lives beside queries.ts rather than in it, on the db/repo-activity.ts precedent set earlier
+// in this batch: queries.ts is already 9k lines and carries literal NUL bytes that make `rg`/
+// `grep` under-report against it, so new folds go in a file a search can actually find.
+import { and, eq, inArray } from 'drizzle-orm';
+import { db, schema } from './client.js';
+import { READY_MERGE_STATES } from './triage.js';
+const { pullRequests } = schema;
+/**
+ * Resolve the caller's PR ids to liveness targets, scoped to the account AND the workspace's
+ * repo membership.
+ *
+ * ⚠ BOTH PREDICATES, AND NEITHER IS REDUNDANT. `accountId` is the tenancy boundary; `repoIds` is
+ * the scope the route echoes back, and without it a caller could name their OWN PRs from another
+ * workspace and have this route refresh (and bill GitHub quota for) rows outside the board they
+ * claimed to be looking at. `repoIds` comes from `resolveWorkspaceScope`, so `[]` — an empty
+ * workspace — correctly resolves nothing rather than widening to the account.
+ */
+export async function getPrLivenessTargets(accountId, repoIds, prIds) {
+    if (prIds.length === 0 || repoIds.length === 0)
+        return [];
+    const rows = await db
+        .select({
+        prId: pullRequests.id,
+        repoId: pullRequests.repoId,
+        githubNodeId: pullRequests.githubNodeId,
+        state: pullRequests.state,
+        isDraft: pullRequests.isDraft,
+        mergeable: pullRequests.mergeable,
+        mergeStateStatus: pullRequests.mergeStateStatus,
+        reviewDecision: pullRequests.reviewDecision,
+        inMergeQueue: pullRequests.inMergeQueue,
+        mergeQueueEntryState: pullRequests.mergeQueueEntryState,
+        updatedAt: pullRequests.updatedAt,
+    })
+        .from(pullRequests)
+        .where(and(eq(pullRequests.accountId, accountId), inArray(pullRequests.repoId, repoIds), inArray(pullRequests.id, prIds)))
+        .execute();
+    return rows.map((r) => ({
+        prId: r.prId,
+        repoId: r.repoId,
+        githubNodeId: r.githubNodeId,
+        state: r.state,
+        isDraft: r.isDraft,
+        mergeable: r.mergeable ?? null,
+        mergeStateStatus: r.mergeStateStatus ?? null,
+        reviewDecision: r.reviewDecision ?? null,
+        inMergeQueue: r.inMergeQueue ?? null,
+        mergeQueueEntryState: r.mergeQueueEntryState ?? null,
+        updatedAt: r.updatedAt,
+    }));
+}
+/**
+ * WHICH TARGETS EARN THE EXPENSIVE SECOND PASS, in priority order.
+ *
+ * The mergeability selection costs ~5s for 25 PRs and 502s the gateway at 50 (see the measured
+ * table in PR_LIVENESS_NODES_QUERY), so only a bounded subset can ever have it. The ordering is
+ * the whole design decision:
+ *
+ *   1. PRs whose STORED merge state already puts them on the board as a FORWARD card
+ *      (READY_MERGE_STATES ∪ {'behind'}). These are the rows offering a Merge / Update-branch
+ *      button, and a stale `mergeStateStatus` there is a button that 405s — the most expensive
+ *      kind of wrong this board can be. The board caps forward cards at 15 per kind, so this
+ *      group is at most 30 PRs and usually far fewer.
+ *   2. Everything else still open, most-recently-updated first — the rotation that lets a
+ *      `blocked → clean` flip (somebody else's approval satisfying branch protection) be noticed
+ *      at all. It is best-effort by construction: on a board with more than ~25 PRs the tail of
+ *      this list simply waits for the next adaptive walk, which is exactly what it did before.
+ *
+ * ⚠ `'dirty'` IS DELIBERATELY NOT IN GROUP 1, even though the `conflicts` card kind is built off
+ * exactly this column. Group 1 exists because a stale merge state there is a BUTTON THAT 405s; a
+ * conflicts card carries no button, so a stale one costs the reader a wasted row, not a refused
+ * merge. It rides the group-2 rotation with everything else, and the SPA's own ranking (which
+ * decides which ids reach this function at all) puts conflicts cards first — so the question gets
+ * asked; how often it is answered stays best-effort, by design.
+ *
+ * Already-merged/closed targets are excluded outright: their card is leaving on this very refetch
+ * and GitHub will not be recomputing mergeability for them.
+ */
+export function rankForMergeStatePass(targets, cap) {
+    const forward = (t) => t.mergeStateStatus != null &&
+        (t.mergeStateStatus === 'behind' || READY_MERGE_STATES.has(t.mergeStateStatus));
+    return targets
+        .filter((t) => t.state === 'open')
+        .sort((a, b) => Number(forward(b)) - Number(forward(a)) ||
+        b.updatedAt.getTime() - a.updatedAt.getTime() ||
+        a.prId - b.prId)
+        .slice(0, cap);
+}
+/**
+ * Write back ONE observation, and only the columns GitHub positively spoke about.
+ *
+ * ⚠ A COLUMN MAY BE CLEARED ONLY ON A POSITIVE STATEMENT FROM GITHUB. `graphqlTolerant` returns
+ * partial data with forbidden fields NULLED, so an absent `mergeable` is indistinguishable from
+ * "GitHub says unknown" at the JSON level. `foldLivenessNode` has already collapsed that: it
+ * refuses the whole node unless `state` arrived (proving the fragment landed), and it leaves
+ * `mergeable`/`mergeStateStatus` UNSET rather than null when they were not asked for. So here,
+ * `undefined` means omit the key and anything else is written — including `reviewDecision: null`,
+ * which on this path is GitHub saying "this repo requires no review", the same value the fat sync
+ * walk stores from the same field, and including `inMergeQueue: false`, which is what a landing or
+ * an ejection from the merge queue looks like.
+ *
+ * ⚠ IT DOES NOT TOUCH `mergedById`. That is the maintainer-inference input and it is not in this
+ * selection; inventing one (or clearing it) from a probe that never asked would corrupt a
+ * different feature. The next `persistPr` fills it in.
+ *
+ * Returns null when nothing in the row actually moved — the common case, and what lets the route
+ * report an honest `changed` count instead of inviting a refetch on every tick.
+ */
+export async function applyPrLiveness(accountId, target, obs) {
+    const set = {};
+    // `dirty` = the row needs writing at all. `movedOnBoard` = a card can change because of it.
+    // Two flags, deliberately: see PrLivenessDiff.movedOnBoard.
+    let dirty = false;
+    let movedOnBoard = false;
+    const change = (onBoard) => {
+        dirty = true;
+        if (onBoard)
+            movedOnBoard = true;
+    };
+    if (obs.state !== target.state) {
+        set.state = obs.state;
+        change(true);
+    }
+    if (obs.isDraft != null && obs.isDraft !== target.isDraft) {
+        set.isDraft = obs.isDraft;
+        change(true);
+    }
+    // Timestamps that only ever ARRIVE (GitHub never un-merges), so they carry no comparison and
+    // no movement of their own — they ride along so a card leaving the board leaves with a real
+    // merged/closed clock instead of a null the next walk has to backfill.
+    if (obs.mergedAt != null && target.state !== 'merged') {
+        set.mergedAt = new Date(obs.mergedAt);
+        dirty = true;
+    }
+    if (obs.closedAt != null && target.state === 'open') {
+        set.closedAt = new Date(obs.closedAt);
+        dirty = true;
+    }
+    if (obs.updatedAt != null) {
+        const next = new Date(obs.updatedAt);
+        if (next.getTime() !== target.updatedAt.getTime()) {
+            set.updatedAt = next;
+            change(true);
+        }
+    }
+    // Written whenever it DIFFERS, null included — on this path a null is GitHub saying "this repo
+    // requires no review", the same value persistPr stores from the same field, and it reaches us
+    // only because `state` proved the fragment landed.
+    //
+    // ⚠ BOARD MOVEMENT, since the Pending card renders review standing. It was `change(false)` while
+    // no card showed the decision, on the argument that 92% of open PRs carry a null one restated
+    // every tick. That argument was always about the WRONG branch: the test above is a DIFF, so a
+    // restatement — null → null included — never gets here at all. What actually reaches this line is
+    // the approval that just landed, which is the single most useful thing the board can learn
+    // between walks and the reason someone leaves the tab open.
+    if (obs.reviewDecision !== target.reviewDecision) {
+        set.reviewDecision = obs.reviewDecision;
+        change(true);
+    }
+    // ── Merge queue — membership and entry state, written as ONE fact ─────────────────────────
+    //
+    // `undefined` = GitHub said nothing (see PrLivenessObservation): omit both keys, learn nothing.
+    // An observed value is written whenever it differs, `false` INCLUDED — a false is GitHub saying
+    // the PR is not in the queue, which is what a landing or an EJECTION looks like, and refusing to
+    // write it would leave a card claiming a queue place the PR no longer holds.
+    //
+    // Board movement both ways: the card shows queue membership by default, and `unmergeable` is the
+    // state worth interrupting someone for — GitHub is dropping the PR out of the queue.
+    //
+    // ⚠ THE ENTRY STATE IS WRITTEN WHENEVER MEMBERSHIP WAS OBSERVED, even to null. Not queued ⇒ no
+    // entry; queued in a state this codebase does not model ⇒ also null (see mergeQueueEntryStateFrom
+    // for why an unmodelled state is not stored raw). That is exactly what persistPr does with the
+    // same GitHub answer, and the two writers must agree or one column flip-flops between the walk
+    // and this sweep every minute. The unknown-never-demotes-known guard above does NOT apply here:
+    // it exists because GitHub answers `mergeable` with UNKNOWN while it computes one, and there is
+    // no such in-progress value on the queue fields — they are stored state.
+    if (obs.inMergeQueue !== undefined) {
+        const nextState = obs.mergeQueueEntryState ?? null;
+        if (obs.inMergeQueue !== target.inMergeQueue) {
+            set.inMergeQueue = obs.inMergeQueue;
+            change(true);
+        }
+        if (nextState !== target.mergeQueueEntryState) {
+            set.mergeQueueEntryState = nextState;
+            change(true);
+        }
+    }
+    // ── The two computed fields, and the one rule that keeps this sweep CONVERGENT ────────────
+    //
+    // `undefined` = the cheap pass never asked. Never conflated with GitHub's own 'unknown'.
+    //
+    // ⚠ AN OBSERVED 'unknown' DOES NOT OVERWRITE A KNOWN STORED VALUE, and this is a DELIBERATE
+    // divergence from `persistPr`, which writes it. GitHub does not store mergeability: asking for
+    // it STARTS a background trial merge, and the answer while that runs is UNKNOWN. `persistPr`
+    // runs on the adaptive cadence (2-15 min) so it rarely catches that window; this sweep runs
+    // every 60s and would sit in it — downgrading `clean` to `unknown`, taking the card's Merge
+    // button away, then restoring it a minute later. Every one of those transitions is a `changed`,
+    // so the board would refetch on a fixed timer forever with a GitHub call in front of it, which
+    // is precisely the churn `changed` exists to prevent.
+    //
+    // Cost of the guard: a PR whose merge state genuinely became unknowable (a force-push mid-
+    // computation) keeps its previous state until the next full walk. That is the same staleness
+    // every card had before this route existed, on a narrow slice of PRs, for a couple of minutes.
+    const authoritative = (next, stored, unknown) => next !== undefined && next !== stored && !(next === unknown && stored != null);
+    if (authoritative(obs.mergeStateStatus, target.mergeStateStatus, 'unknown')) {
+        set.mergeStateStatus = obs.mergeStateStatus;
+        change(true);
+    }
+    if (authoritative(obs.mergeable, target.mergeable, 'unknown')) {
+        set.mergeable = obs.mergeable;
+        // The board's merge GATE reads it (`card.mergeable ?? 'unknown'` → mergeVerdict), so a
+        // conflict appearing or clearing really can change a button.
+        change(true);
+    }
+    if (!dirty)
+        return null;
+    await db
+        .update(pullRequests)
+        .set(set)
+        .where(and(eq(pullRequests.id, target.prId), eq(pullRequests.accountId, accountId)))
+        .execute();
+    return {
+        prId: target.prId,
+        movedOnBoard,
+        leftOpenSet: target.state === 'open' && obs.state !== 'open',
+    };
+}
+//# sourceMappingURL=pr-liveness.js.map

package/dist/db/pr-mentions.js

@@ -0,0 +1,279 @@
+// Query layer for "@you was mentioned on this PR" (CORE, free, no AI, no GitHub quota).
+//
+// WHAT THIS ANSWERS. My Turn's `mention` type (S6 of the ball rule, `getMyTurn`): a PERSON typed
+// your login on an open PR, and you have not acted on that PR since. A mention is a summons EVEN
+// IN A REPO YOU ONLY READ — that is the whole point of it, and why it is its own card type rather
+// than a property of the repo. The card clears when you act AFTER the mention, so each row carries
+// the moment of the NEWEST qualifying mention (`mentioned_at`) and who made it.
+//
+// TWO JOBS, and nothing else:
+//   1. MATCH   — the pure `@login` word-boundary predicate (exported and unit-pinned)
+//   2. DERIVE  — the full "which of this account's PRs mention the viewer, newest when and by whom"
+//                set (the scanner's worklist; see sync/mention-scan.ts), and the diff that makes
+//                the stored rows equal it. The READ is a join inside `getMyTurn`.
+//
+// WHO CAN SUMMON YOU. A mention by the viewer themself is not a summons, and neither is one by
+// automation — the GLOBAL automation set (`globalAutomationUserIds`), the SAME set the ball rule
+// resolves bot-ness with, so a mention this scanner stamps is always one `getMyTurn` would honour.
+//
+// WHY THE DERIVE IS A FULL RE-SCAN AND NOT AN INCREMENTAL CURSOR. A cursor over the three comment
+// tables would have to be right about four different ways the corpus changes, and each wrong
+// answer is silent: a 90-day BACKFILL inserts rows whose `created_at` predates any time-based
+// watermark; a body EDIT changes neither a row's id nor its created_at; a deleted comment must
+// REMOVE a mention; and Postgres hands out sequence values out of commit order, so an id-based
+// watermark can skip a row permanently. Re-deriving the whole set and diffing it against what is
+// stored is correct under all four with no state to keep, and it is affordable because the
+// expensive half is bounded by the MATCHES, not by the corpus: on this repo's own dev database
+// (65k comment/review bodies, 8.5k PRs) the three scans below run in ~0.19s and return 12 rows.
+// The cost that does scale is the LIKE scan itself, which is why this is a background worker on a
+// multi-minute cron and NEVER a per-request read — `getWorkspaceInsights` runs on every Feed
+// landing.
+import { and, desc, eq, inArray, isNotNull, sql } from 'drizzle-orm';
+import { db, schema } from './client.js';
+import { globalAutomationUserIds } from './automation-ids.js';
+const { prMentions, prComments, pullRequests, reviewComments, reviews, users } = schema;
+// A cap on how many MATCHING rows one account's scan will look at, per source table. Not a
+// correctness bound — it is a guard against a pathological corpus (a bot that @-mentions the
+// account owner on every PR) turning one tick into an unbounded allocation. Each scan orders
+// NEWEST FIRST before the cap, so if it ever bites it drops the OLDEST matches — the ones least
+// likely to be a PR's newest mention, which is the only one a row keeps.
+const MENTION_SCAN_CAP = 20_000;
+// Chunk size for the `IN (…)` lookups. SQLite's default bound-variable limit is 999.
+const ID_CHUNK = 500;
+/**
+ * THE MATCH RULE. `@login` as a whole word, case-insensitive.
+ *
+ * The two failure directions this exists to prevent, both silent:
+ *   • `@alex` must NOT match "@alexwakeman" and `@alexwakeman` must not match "@alex" — the
+ *     trailing class rejects a login that merely STARTS with ours (GitHub logins are
+ *     `[A-Za-z0-9-]`; `_` is in the class as well because a reader cannot tell "@alex_wakeman"
+ *     apart from a login we do not know, and under-notifying is the safe direction here).
+ *   • "bob@alexwakeman.com" and "docs/@alexwakeman/notes.md" must not count — the leading class
+ *     rejects an `@` glued to a word character, a path separator or a dot, which is what an
+ *     email local part and a path segment look like.
+ *
+ * Everything else — start of string, whitespace, `(`, `[`, `>`, a backtick — is a real mention
+ * position and matches. (`deriveMentionedPrs` drops QUOTED lines before it asks: see
+ * `withoutQuotedLines`.)
+ *
+ * Deliberately NOT a `\b` boundary: `\b` is symmetric about word characters and `@` is not a word
+ * character, so `\b@login\b` would happily match the email case above.
+ */
+export function mentionPattern(login) {
+    // The login is DATA (it comes from `accounts.github_login`, ultimately from GitHub). Escaping
+    // it keeps a hyphen or a dot from being read as regex syntax.
+    const escaped = login.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![A-Za-z0-9_@./-])@${escaped}(?![A-Za-z0-9_-])`, 'i');
+}
+/** The body without its markdown blockquote lines — what its author TYPED. A quote-reply repeats
+ *  somebody else's words: "> @you can you look?" is not the quoter summoning you, and counting it
+ *  would move the mention clock past an action you already took and credit the wrong person. */
+export function withoutQuotedLines(body) {
+    return body.replace(/^[ \t]*>.*$/gm, '');
+}
+/** True when `text` @-mentions `login` as a whole word. Empty login never matches. */
+export function mentionsLogin(text, login) {
+    if (!text || !login)
+        return false;
+    return mentionPattern(login).test(text);
+}
+// A `%@login%` LIKE pattern with the LIKE metacharacters escaped, paired with `ESCAPE '\'` below
+// (the db/search.ts idiom). This is a PREFILTER ONLY — it is substring, not word-boundary, so
+// `mentionsLogin` above is the authority on every row it returns.
+function likePattern(login) {
+    return `%@${login.toLowerCase().replace(/([\\%_])/g, '\\$1')}%`;
+}
+function likeCol(col, pattern) {
+    return sql `lower(${col}) like ${pattern} escape '\\'`;
+}
+/**
+ * THE FULL DERIVATION: every PR of this account on which a PERSON other than the viewer
+ * @-mentions `login`, with that PR's NEWEST such mention.
+ *
+ * All three body-bearing tables, because a mention is a mention wherever it was typed: an
+ * issue-level PR comment, a review body, an inline review-thread comment. PR TITLES AND
+ * DESCRIPTIONS ARE DELIBERATELY OUT — descriptions are not persisted under lean storage
+ * (docs/BACKEND.md), so including them would make the answer depend on whether PERSIST_BODIES
+ * happened to be on, which is the one thing a derived fact must never do. Comment and review
+ * bodies are ALWAYS persisted, so this needs no GitHub fetch and no hydration.
+ *
+ * ⚠ A SKIPPED ROW IS SKIPPED BEFORE "NEWEST" IS DECIDED. A bot that echoes your login after a
+ * colleague's mention must not become the PR's mention (its time would move the card's clock, and
+ * the next bot echo would re-summon you after you acted); the colleague's mention stays the newest.
+ */
+export async function deriveMentionedPrs(accountId, login) {
+    if (!login)
+        return [];
+    const pat = likePattern(login);
+    // Resolved once per scan: who "you" are (a self-mention is not a summons) and who is automation.
+    const [viewerRows, bots] = await Promise.all([
+        db
+            .select({ id: users.id })
+            .from(users)
+            .where(sql `lower(${users.githubLogin}) = ${login.toLowerCase()}`)
+            .limit(1)
+            .execute(),
+        globalAutomationUserIds(),
+    ]);
+    const viewerUserId = viewerRows[0]?.id ?? null;
+    // Three near-identical queries rather than one parameterised helper: drizzle's column types are
+    // per-table, and the generic version only type-checks by widening the columns to `any` — which
+    // is exactly the seam that would let a wrong `prId` through unnoticed.
+    const [pc, rc, rv] = await Promise.all([
+        db
+            .select({
+            prId: prComments.prId,
+            repoId: pullRequests.repoId,
+            body: prComments.body,
+            authorId: prComments.authorId,
+            at: prComments.createdAt,
+        })
+            .from(prComments)
+            .innerJoin(pullRequests, eq(pullRequests.id, prComments.prId))
+            .where(and(eq(pullRequests.accountId, accountId), isNotNull(prComments.body), likeCol(prComments.body, pat)))
+            .orderBy(desc(prComments.createdAt))
+            .limit(MENTION_SCAN_CAP)
+            .execute(),
+        db
+            .select({
+            prId: reviewComments.prId,
+            repoId: pullRequests.repoId,
+            body: reviewComments.body,
+            authorId: reviewComments.authorId,
+            at: reviewComments.createdAt,
+        })
+            .from(reviewComments)
+            .innerJoin(pullRequests, eq(pullRequests.id, reviewComments.prId))
+            .where(and(eq(pullRequests.accountId, accountId), isNotNull(reviewComments.body), likeCol(reviewComments.body, pat)))
+            .orderBy(desc(reviewComments.createdAt))
+            .limit(MENTION_SCAN_CAP)
+            .execute(),
+        db
+            .select({
+            prId: reviews.prId,
+            repoId: pullRequests.repoId,
+            body: reviews.body,
+            authorId: reviews.authorId,
+            at: reviews.submittedAt,
+        })
+            .from(reviews)
+            .innerJoin(pullRequests, eq(pullRequests.id, reviews.prId))
+            .where(and(eq(pullRequests.accountId, accountId), isNotNull(reviews.body), likeCol(reviews.body, pat)))
+            .orderBy(desc(reviews.submittedAt))
+            .limit(MENTION_SCAN_CAP)
+            .execute(),
+    ]);
+    const out = new Map();
+    for (const rows of [pc, rc, rv]) {
+        for (const r of rows) {
+            // Nobody we can name (a deleted account), yourself, or automation: not a summons.
+            if (r.authorId == null || r.authorId === viewerUserId || bots.has(r.authorId))
+                continue;
+            // ⚠ THE SQL IS A PREFILTER, THE REGEX IS THE ANSWER. `lower(body) LIKE '%@alex%'` matches
+            // "@alexwakeman" and "bob@alex.com" too; dropping this line is how "@alex" starts claiming
+            // every PR that mentions a colleague with a longer login. And only TYPED lines count — a
+            // quoted mention skipped here, before "newest" is decided, cannot restamp the clock.
+            if (r.body == null || !mentionsLogin(withoutQuotedLines(r.body), login))
+                continue;
+            const prev = out.get(r.prId);
+            if (prev != null && prev.mentionedAt.getTime() >= r.at.getTime())
+                continue;
+            out.set(r.prId, {
+                prId: r.prId,
+                repoId: r.repoId,
+                mentionedAt: r.at,
+                mentionedById: r.authorId,
+            });
+        }
+    }
+    return [...out.values()];
+}
+/** What is currently stored for this account: each PR, the login it was derived under, and the
+ *  mention clock last stamped on it (NULL until the first scan after migration 0068). */
+export async function listStoredMentions(accountId) {
+    return db
+        .select({
+        id: prMentions.id,
+        prId: prMentions.prId,
+        login: prMentions.login,
+        mentionedAt: prMentions.mentionedAt,
+        mentionedByUserId: prMentions.mentionedByUserId,
+    })
+        .from(prMentions)
+        .where(eq(prMentions.accountId, accountId))
+        .execute();
+}
+/**
+ * Make the stored set EQUAL the derived set for one account — the scanner's only writer.
+ *
+ * A diff rather than an upsert sweep, because the delete half is load-bearing: a mention edited
+ * out of a comment, a deleted comment, a PR that lost its mention when a review was dismissed,
+ * and every row derived under a login this account no longer has must all STOP summoning you.
+ * An insert-only writer would make the mention card a ratchet that only ever widens.
+ *
+ * ⚠ AND THE KEPT HALF IS RESTAMPED. A row is "unchanged" only when its login, its mention time and
+ * its author all match what was derived; a NEWER mention on the same PR must move `mentioned_at`,
+ * or you would act, the card would clear, and the colleague's second "@you?" would never return
+ * it.
+ *
+ * `login` is stored lowercased so the reader's equality test does not depend on how GitHub
+ * spelled the login on the day the row was written.
+ */
+export async function syncAccountMentions(accountId, login, derived) {
+    const canonical = login.toLowerCase();
+    const stored = await listStoredMentions(accountId);
+    const storedByPr = new Map(stored.map((r) => [r.prId, r]));
+    const wanted = new Map(derived.map((d) => [d.prId, d]));
+    // Stale = no longer derived, OR derived under a different login (an account rename). Both are
+    // "this row no longer states a true fact", so both leave by the same path.
+    const staleIds = stored
+        .filter((r) => !wanted.has(r.prId) || r.login !== canonical)
+        .map((r) => r.id);
+    for (let i = 0; i < staleIds.length; i += ID_CHUNK) {
+        await db
+            .delete(prMentions)
+            .where(inArray(prMentions.id, staleIds.slice(i, i + ID_CHUNK)))
+            .execute();
+    }
+    let added = 0;
+    let updated = 0;
+    for (const d of derived) {
+        const existing = storedByPr.get(d.prId);
+        const kept = existing != null && existing.login === canonical;
+        if (kept &&
+            existing.mentionedAt?.getTime() === d.mentionedAt.getTime() &&
+            existing.mentionedByUserId === d.mentionedById) {
+            continue;
+        }
+        // An UPSERT on the table's one unique, `(account_id, pr_id)` — the `prm_account_pr` target
+        // every writer of this table uses — so a concurrent (or retried) tick cannot turn a duplicate
+        // into a thrown scan, and a kept row is restamped in the same statement.
+        const res = await db
+            .insert(prMentions)
+            .values({
+            accountId,
+            repoId: d.repoId,
+            prId: d.prId,
+            login: canonical,
+            mentionedAt: d.mentionedAt,
+            mentionedByUserId: d.mentionedById,
+        })
+            .onConflictDoUpdate({
+            target: [prMentions.accountId, prMentions.prId],
+            set: {
+                login: canonical,
+                repoId: d.repoId,
+                mentionedAt: d.mentionedAt,
+                mentionedByUserId: d.mentionedById,
+            },
+        })
+            .returning({ id: prMentions.id })
+            .execute();
+        if (kept)
+            updated += res.length;
+        else
+            added += res.length;
+    }
+    return { added, updated, removed: staleIds.length };
+}
+//# sourceMappingURL=pr-mentions.js.map

package/dist/db/pr-merge-queue-stamp.js

@@ -0,0 +1,91 @@
+// A pull request's GitHub MERGE-QUEUE membership, stamped from a live observation.
+//
+// ⚠ NOT `db/merge-queue.ts`. That module is Limn's OWN per-repo landing order for armed intents
+// (`queued_local`); this one is GitHub's native merge queue, as synced onto `pull_requests`
+// (`in_merge_queue` + `merge_queue_entry_state`). Two queues, two files, never one name.
+//
+// WHY A STAMP AT ALL. A GitHub write is not done when GitHub 200s: the SPA re-reads from the local
+// DB, so an enqueue nobody stamped is invisible until the next adaptive walk — up to fifteen
+// minutes on a cold repo — and the Pending board is forbidden from fetching to find out. So EVERY
+// path that holds a positive answer about membership writes it here:
+//
+//   - POST / DELETE /api/prs/:id/merge-queue (the two verbs, and the DELETE's own probe)
+//   - GET /api/prs/:id/merge-options, when its queue probe answered
+//   - the arm route's AlreadyQueued 409 (it just proved the PR is queued)
+//   - the disarm route's dequeue of a watcher-made entry
+//   - the auto-merge runner's enqueue, and its per-tick live probe
+//
+// ⚠ POSITIVE ANSWERS ONLY — the partial-response rule ("a column may be CLEARED only on a positive
+// statement from GitHub"). Callers pass a NON-NULL `fetchMergeQueueState` result (non-tolerant
+// GraphQL with `isInMergeQueue: Boolean!`, so a result is a statement) or the outcome of a mutation
+// GitHub accepted. Never the `.catch(() => null)` null of a best-effort probe: that is "we never
+// received it", and writing `false` from it would tell the board a queued PR is not queued.
+//
+// ⚠ THE SYNC'S OWN THREE-STATE FOLD (sync/upsert.ts) DOES NOT COME THROUGH HERE, and must not: a
+// walk that did not carry the selection OMITS the keys, and an unconditional setter cannot say
+// "omit". This helper is correct precisely because every caller holds an answer.
+//
+// ⚠ A STAMP THAT CHANGES THE STORED VALUE RAISES THE CHANGE SIGNAL (`notePrChanged`). The board's
+// liveness sweep compares GitHub against the ROW, so once a route has written the new value the
+// sweep sees no difference and never repaints the card; without the signal a stamp made by the
+// runner or by a GET would silence the one mechanism that used to catch it. A write that changed
+// nothing raises nothing — a signal costs the SPA a cascade of refetches.
+import { and, eq } from 'drizzle-orm';
+import { db, schema } from './client.js';
+import { mergeQueueEntryStateFrom } from '../sync/upsert.js';
+import { notePrChanged } from '../sync/pr-change-signal.js';
+/**
+ * Write what GitHub just said about this PR's merge-queue membership. Account-scoped (a foreign
+ * id matches no row and writes nothing). Returns true when the stored value CHANGED.
+ *
+ * `rawEntryState` is GitHub's `MergeQueueEntryState` as it arrived (`QUEUED`, `AWAITING_CHECKS`,
+ * …), normalised by the ONE normaliser the sync uses. Out of the queue means no entry — a stale
+ * `queued` is never carried past a dequeue. In the queue with no modelled state stores "queued,
+ * state unknown", never "not queued".
+ */
+export async function stampPrMergeQueueState(prId, accountId, inQueue, rawEntryState) {
+    const { pullRequests } = schema;
+    const next = {
+        inMergeQueue: inQueue,
+        mergeQueueEntryState: inQueue ? mergeQueueEntryStateFrom(rawEntryState) : null,
+    };
+    const owned = and(eq(pullRequests.id, prId), eq(pullRequests.accountId, accountId));
+    const rows = await db
+        .select({
+        repoId: pullRequests.repoId,
+        inMergeQueue: pullRequests.inMergeQueue,
+        mergeQueueEntryState: pullRequests.mergeQueueEntryState,
+    })
+        .from(pullRequests)
+        .where(owned)
+        .execute();
+    const row = rows[0];
+    if (row == null)
+        return false;
+    if (row.inMergeQueue === next.inMergeQueue &&
+        (row.mergeQueueEntryState ?? null) === next.mergeQueueEntryState) {
+        return false;
+    }
+    await db.update(pullRequests).set(next).where(owned).execute();
+    notePrChanged(accountId, row.repoId);
+    return true;
+}
+/**
+ * The same write, NEVER FATAL — what every ROUTE calls.
+ *
+ * ⚠ A STAMP IS A LOCAL COPY OF SOMETHING GITHUB ALREADY SAID, so failing to write it is a stale
+ * screen, never a failed request. Most call sites sit inside a try whose catch answers
+ * `502 GitHubError`: a DB hiccup there would make GET merge-options read "Couldn't load merge
+ * status", refuse an arm, or — after GitHub has ACCEPTED an enqueue or a dequeue — tell the reader
+ * the write failed when it landed (and invite a retry). "Once GitHub has 201'd the route may not
+ * fail." So the failure is logged and swallowed here, once, rather than at each call site.
+ */
+export async function stampPrMergeQueueStateNonFatal(prId, accountId, inQueue, rawEntryState, log) {
+    try {
+        await stampPrMergeQueueState(prId, accountId, inQueue, rawEntryState);
+    }
+    catch (err) {
+        log.warn({ err, prId }, 'merge queue: could not record the queue state on the PR row');
+    }
+}
+//# sourceMappingURL=pr-merge-queue-stamp.js.map