heyquilt 0.3.120 → 0.3.122

package/src/quilts/accounts.js

@@ -0,0 +1,136 @@
+// Seam's own accounts: a person signs in on seam.heyquilt.com with Supabase Auth in Seam's own
+// project, and Seam's API checks the access token itself (no other service is asked): the
+// signature against the project's published keys (JWKS, ES256/RS256) or its shared secret
+// (HS256), the issuer, the audience and the expiry. The first call makes the account's row
+// (store.accountFor), whose member_id is who the person is in every quilt.
+import crypto from 'node:crypto'
+import { QuiltError } from './errors.js'
+import { isSeamKey } from './keys.js'
+import { isOAuthToken } from './oauth.js'
+
+const b64 = (s) => Buffer.from(String(s), 'base64url')
+const ALGS = { ES256: 'sha256', RS256: 'sha256', HS256: 'sha256' }
+export const isJwt = (s) => /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(String(s || ''))
+
+/**
+ * verify(token) → the token's claims when Seam's Supabase Auth signed it and it is current, else
+ * null. `authUrl` is the project's address (https://<ref>.supabase.co); `jwtSecret` the legacy
+ * shared secret, when the project still signs with one.
+ */
+export function supabaseVerifier ({ authUrl, jwtSecret = null, fetch = globalThis.fetch, now = Date.now, keysTtlMs = 10 * 60_000, timeoutMs = 5000 }) {
+  if (!authUrl) throw new Error('supabaseVerifier needs the auth project address (SEAM_AUTH_URL)')
+  const base = String(authUrl).replace(/\/+$/, '')
+  const issuer = `${base}/auth/v1`
+  let keys = null // { at, byKid: Map }
+  let lastMiss = 0
+
+  async function loadKeys () {
+    let res
+    try { res = await fetch(`${issuer}/.well-known/jwks.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) }) } catch { throw new QuiltError(503, 'identity_unavailable', 'Seam could not reach its sign-in keys; try again') }
+    const data = await res.json().catch(() => null)
+    if (!res.ok || !data || !Array.isArray(data.keys)) throw new QuiltError(503, 'identity_unavailable', 'Seam could not read its sign-in keys; try again')
+    const byKid = new Map()
+    for (const jwk of data.keys) {
+      try { byKid.set(jwk.kid || '', { alg: jwk.alg, key: crypto.createPublicKey({ key: jwk, format: 'jwk' }) }) } catch {}
+    }
+    keys = { at: now(), byKid }
+    return keys
+  }
+
+  async function keyFor (kid) {
+    if (!keys || now() - keys.at > keysTtlMs) await loadKeys()
+    let k = keys.byKid.get(kid || '')
+    // A key rotated in since the last fetch: fetch again, at most once a minute.
+    if (!k && now() - lastMiss > 60_000) { lastMiss = now(); await loadKeys(); k = keys.byKid.get(kid || '') }
+    return k || null
+  }
+
+  return async function verify (token) {
+    if (!isJwt(token)) return null
+    const [h, p, s] = String(token).split('.')
+    let header, claims
+    try { header = JSON.parse(b64(h).toString('utf8')); claims = JSON.parse(b64(p).toString('utf8')) } catch { return null }
+    if (!header || !claims || !ALGS[header.alg]) return null
+    const data = Buffer.from(`${h}.${p}`)
+    const sig = b64(s)
+    let ok = false
+    if (header.alg === 'HS256') {
+      if (!jwtSecret) return null
+      const want = crypto.createHmac('sha256', jwtSecret).update(data).digest()
+      ok = want.length === sig.length && crypto.timingSafeEqual(want, sig)
+    } else {
+      const k = await keyFor(header.kid)
+      if (!k) return null
+      try { ok = crypto.verify('sha256', data, header.alg === 'ES256' ? { key: k.key, dsaEncoding: 'ieee-p1363' } : k.key, sig) } catch { ok = false }
+    }
+    if (!ok) return null
+    const t = Math.floor(now() / 1000)
+    if (typeof claims.exp !== 'number' || claims.exp <= t) return null
+    if (claims.iss !== issuer) return null
+    const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud]
+    if (!aud.includes('authenticated') || claims.role !== 'authenticated') return null
+    if (typeof claims.sub !== 'string' || !/^[0-9a-f-]{36}$/i.test(claims.sub) || !claims.email) return null
+    return claims
+  }
+}
+
+const nameOf = (claims) => {
+  const m = claims.user_metadata || {}
+  const n = String(m.name || m.full_name || String(claims.email).split('@')[0] || 'person').trim()
+  return n.slice(0, 200) || 'person'
+}
+
+export function accountOps (svc) {
+  const { store, now } = svc.internals
+
+  /** The member a verified sign-in stands for (its account row made on the first call). */
+  async function accountCaller (claims) {
+    const a = await store.accountFor({ id: claims.sub, email: String(claims.email).toLowerCase(), name: nameOf(claims), at: now() })
+    return { member_id: a.member_id, kind: 'person', name: a.name, account: a.id }
+  }
+
+  /** GET /v1/me: who the caller is to Seam. */
+  async function whoami (me) {
+    const out = { member_id: me.member_id, kind: me.kind, name: me.name }
+    if (me.tool) out.tool = me.tool
+    if (me.on_behalf_of) out.on_behalf_of = me.on_behalf_of
+    if (me.account) {
+      const a = await store.getAccount(me.account)
+      if (a) out.account = { id: a.id, email: a.email, created_at: a.created_at }
+    }
+    return out
+  }
+
+  return { accountCaller, whoami }
+}
+
+/**
+ * identify(req) for Seam's own server: a Seam sign-in (verified here) is the caller; anything
+ * else goes to `fallback` (an identity service over HTTP, server.js remoteIdentity) when one is
+ * set, and is refused otherwise.
+ */
+export function seamIdentity ({ quilts, verify = null, fallback = null }) {
+  if (!verify && !fallback && !quilts?.keyCaller) throw new Error('seamIdentity needs Seam\'s own sign-in (SEAM_AUTH_URL) or an identity service (SEAM_IDENTITY_URL)')
+  return async function identify (req) {
+    const h = String(req.headers?.authorization || '')
+    if (!h) throw new QuiltError(401, 'not_signed_in', 'sign in: send "Authorization: Bearer <token>"')
+    const token = h.startsWith('Bearer ') ? h.slice(7).trim() : ''
+    if (isSeamKey(token)) {
+      const k = await quilts.keyCaller(token)
+      if (!k) throw new QuiltError(401, 'bad_key', 'this Seam key is unknown, expired or revoked: run seam login (or ask for a new agent key)')
+      return k
+    }
+    if (isOAuthToken(token)) {
+      const o = await quilts.oauthCaller(token)
+      if (!o) throw new QuiltError(401, 'invalid_token', 'this access token is unknown, expired or revoked: refresh it')
+      return o
+    }
+    if (verify && isJwt(token)) {
+      const claims = await verify(token)
+      if (claims) return quilts.accountCaller(claims)
+      if (!fallback) throw new QuiltError(401, 'not_signed_in', 'this sign-in is unknown or expired; sign in again')
+    }
+    if (fallback) return fallback(req)
+    throw new QuiltError(401, 'not_signed_in', 'this sign-in is unknown or expired; sign in again')
+  }
+}

package/src/quilts/affected.js

@@ -0,0 +1,132 @@
+// Test targeting (plans/quilt-source-control/13 "Test impact from the derived dependency graph").
+// Which of a line's tests (its policy's `tests` globs) a change reaches: a test is affected when
+// the files it imports, followed to depth 8, include a changed path. Grammars: JS/TS (import,
+// export … from, dynamic import, require) and Python (import, from … import, relative or from a
+// root). Bare package names are not followed: a dependency change shows in a lockfile or build
+// file, and those make the answer `confidence: 'all'`, as do a ci-config path, a changed file in a
+// language without a grammar, and a graph above the bounds. The runner runs everything for 'all';
+// the post-merge tier always gets 'all', so a wrong answer here is caught by the next batch.
+import { globMatcher } from './claims.js'
+
+export const MAX_DEPTH = 8
+export const MAX_FILES = 5000
+const MAX_TESTS = 500
+const MAX_READ = 512 * 1024
+
+const LOCKFILE = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|go\.sum|poetry\.lock|Pipfile\.lock|uv\.lock|Gemfile\.lock|composer\.lock)$/
+const BUILD = /(^|\/)(package\.json|pnpm-workspace\.yaml|go\.mod|Cargo\.toml|pyproject\.toml|setup\.py|setup\.cfg|Pipfile|requirements[^/]*\.txt|Gemfile|tsconfig[^/]*\.json)$/
+export const DEFAULT_CI_CONFIG = ['.github/workflows/**', '.gitlab-ci.yml', '.circleci/**', '.buildkite/**', 'Jenkinsfile']
+const JS = /\.(js|mjs|cjs|jsx|ts|mts|cts|tsx)$/
+const PY = /\.py$/
+// Files a grammar can import or that no code runs: reachable through imports, or reaching nothing.
+const DATA = /\.(json|ya?ml|toml|css|scss|sass|less|html?|svg|png|jpe?g|gif|webp|ico|woff2?|md|mdx|txt|rst|csv|lock)$|(^|\/)(LICENSE|README|CHANGELOG|\.gitignore|\.gitattributes|\.editorconfig|\.npmignore)[^/]*$/i
+const JS_EXT = ['', '.js', '.ts', '.tsx', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.json']
+
+const dirOf = (p) => p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : ''
+function join (dir, rel) {
+  const out = dir ? dir.split('/') : []
+  for (const part of rel.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') { if (!out.length) return null; out.pop() } else out.push(part)
+  }
+  return out.join('/')
+}
+
+/** The module names a file imports, as written (relative JS specifiers, Python dotted names). */
+export function importsOf (path, text) {
+  const out = []
+  if (JS.test(path)) {
+    const rx = /(?:^|[^\w$.])(?:import|export)\s[^'"`;]*?\bfrom\s*['"]([^'"]+)['"]|(?:^|[^\w$.])import\s*\(?\s*['"]([^'"]+)['"]|(?:^|[^\w$.])require\s*\(\s*['"]([^'"]+)['"]/g
+    for (const m of text.matchAll(rx)) out.push(m[1] || m[2] || m[3])
+  } else if (PY.test(path)) {
+    for (const line of text.split('\n')) {
+      let m = /^\s*from\s+(\.*[\w.]*)\s+import\s+(.+)/.exec(line)
+      if (m) {
+        if (/^\.+$/.test(m[1])) for (const name of m[2].replace(/[()]/g, '').split(',')) { const n = name.trim().split(/\s+/)[0]; if (/^\w+$/.test(n)) out.push(m[1] + n) } else out.push(m[1])
+        continue
+      }
+      m = /^\s*import\s+(.+)/.exec(line)
+      if (m) for (const name of m[1].split(',')) { const n = name.trim().split(/\s+/)[0]; if (/^[\w.]+$/.test(n)) out.push(n) }
+    }
+  }
+  return out
+}
+
+/** The paths a module name can be, in order (the first that exists is the import). */
+function candidates (from, spec, roots) {
+  if (JS.test(from)) {
+    if (!spec.startsWith('.')) return []
+    const base = join(dirOf(from), spec)
+    if (base == null) return []
+    const out = JS_EXT.map((e) => base + e).concat(JS_EXT.slice(1).map((e) => base + '/index' + e))
+    if (/\.(m|c)?js$/.test(base)) out.push(...['.ts', '.tsx', '.mts', '.cts'].map((e) => base.replace(/\.(m|c)?js$/, e)))
+    return out
+  }
+  const dots = /^\.*/.exec(spec)[0].length
+  const rest = spec.slice(dots).split('.').filter(Boolean).join('/')
+  let bases
+  if (dots) {
+    let dir = dirOf(from)
+    for (let i = 1; i < dots; i++) dir = dirOf(dir)
+    bases = [dir ? (rest ? dir + '/' + rest : dir) : rest]
+  } else bases = [...roots.map((r) => (r ? r + '/' : '') + rest), (dirOf(from) ? dirOf(from) + '/' : '') + rest]
+  return bases.filter(Boolean).flatMap((b) => [b + '.py', b + '/__init__.py'])
+}
+
+/**
+ * { confidence: 'paths', tests: [...] } or { confidence: 'all', why }.
+ * changed: the changed paths (deleted ones too); files: every path at the new snapshot;
+ * read(path) → text; tests / ci_config: globs; roots: where absolute Python imports start.
+ */
+export async function affectedTests ({ changed, files, read, tests = [], ci_config: ciConfig = [], roots = ['', 'src', 'lib'], maxFiles = MAX_FILES, maxDepth = MAX_DEPTH }) {
+  const all = (why) => ({ confidence: 'all', why })
+  if (!tests.length) return all('the line names no tests')
+  const ci = [...DEFAULT_CI_CONFIG, ...ciConfig].map(globMatcher)
+  for (const p of changed) {
+    if (LOCKFILE.test(p)) return all(`${p} is a lockfile`)
+    if (BUILD.test(p)) return all(`${p} declares dependencies`)
+    if (ci.some((m) => m(p))) return all(`${p} is ci config`)
+    if (!JS.test(p) && !PY.test(p) && !DATA.test(p)) return all(`${p} is in a language Seam has no import grammar for`)
+  }
+  if (files.length > maxFiles) return all(`more than ${maxFiles} files`)
+  const isTest = tests.map(globMatcher)
+  const present = new Set(files)
+  const exists = new Set([...files, ...changed])
+  const hit = new Set(changed)
+  const edges = new Map()
+  let reads = 0
+  const importsFrom = async (p) => {
+    if (edges.has(p)) return edges.get(p)
+    let out = []
+    if ((JS.test(p) || PY.test(p)) && present.has(p)) {
+      if (++reads > maxFiles) throw Object.assign(new Error('bound'), { bound: true })
+      const text = String(await read(p)).slice(0, MAX_READ)
+      for (const spec of importsOf(p, text)) {
+        const to = candidates(p, spec, roots).find((c) => exists.has(c))
+        if (to && to !== p) out.push(to)
+      }
+    }
+    edges.set(p, out)
+    return out
+  }
+  const reaches = async (start) => {
+    let frontier = [start]
+    const seen = new Set(frontier)
+    for (let depth = 0; frontier.length && depth <= maxDepth; depth++) {
+      if (frontier.some((p) => hit.has(p))) return true
+      const next = []
+      for (const p of frontier) for (const q of await importsFrom(p)) if (!seen.has(q)) { seen.add(q); next.push(q) }
+      frontier = next
+    }
+    return false
+  }
+  const out = []
+  try {
+    for (const p of [...present].sort()) if (isTest.some((m) => m(p)) && await reaches(p)) out.push(p)
+  } catch (err) {
+    if (err.bound) return all(`more than ${maxFiles} files to read`)
+    throw err
+  }
+  if (out.length > MAX_TESTS) return all(`more than ${MAX_TESTS} tests`)
+  return { confidence: 'paths', tests: out }
+}

package/src/quilts/checks.js

@@ -0,0 +1,308 @@
+// Check runs (plans/quilt-source-control/13 "Checks"). Seam never runs a check: a line's policy
+// names each check's `runners` (members), and Seam asks them to run it with a check.requested
+// event and a run record keyed by `run_key`:
+//   - pre_merge, on a square's new head, for each check its line requires (requested_by 'policy');
+//   - pre_merge, when a square asks to merge and a required check has no run on its head ('holder');
+//   - post_merge, on the line's new tip after a merge, for every check with runners ('policy').
+// Runners get the event by webhook (events.js) or poll GET /checks?state=queued, run the check and
+// report with POST /squares/:s/checks or /lines/:l/checks (optionally naming the run_key). A
+// verdict from a member who is not one of the check's runners is advisory: kept on a run of its
+// own, it gates nothing.
+import { QuiltError, squareShort } from './service.js'
+import { uuidv7 } from './ids.js'
+import { affectedTests } from './affected.js'
+
+export const TIERS = ['pre_merge', 'post_merge']
+export const RUN_STATES = ['queued', 'running', 'done', 'cancelled']
+export const MAX_RUNNERS = 20
+const MAX_PATHS = 200
+
+const POST_ALL = { confidence: 'all', why: 'post_merge runs everything' }
+const OPEN = new Set(['queued', 'running'])
+
+export const runKey = ({ tier, name, commit }) => `${tier}:${name}:${commit}`
+
+/** The runners a line's rule names for a check ([] when none: anyone with write may report). */
+export const runnersOf = (rule, name) => (rule?.runners && Array.isArray(rule.runners[name]) ? rule.runners[name] : [])
+
+/**
+ * The tiers a check runs in. A policy's `tiers` names them per check; without it a required check
+ * runs pre_merge (on the square) and a check with runners runs post_merge (on the line).
+ */
+export function tiersOf (rule, name) {
+  if (rule?.tiers && Array.isArray(rule.tiers[name])) return rule.tiers[name]
+  return [...(rule?.checks?.includes(name) ? ['pre_merge'] : []), ...(runnersOf(rule, name).length ? ['post_merge'] : [])]
+}
+
+/** Checks `tiers` from a policy body: { check: ['pre_merge' | 'post_merge', …] }. */
+export function cleanTiers (tiers, nameOk) {
+  if (tiers === null) return {}
+  if (typeof tiers !== 'object' || Array.isArray(tiers)) throw new QuiltError(400, 'bad_request', `tiers: { "<check>": [${TIERS.map((t) => `"${t}"`).join(', ')}] }`)
+  const out = {}
+  for (const [name, list] of Object.entries(tiers)) {
+    if (!nameOk(name)) throw new QuiltError(400, 'bad_request', `${name || '(empty)'} is not a check name`)
+    if (!Array.isArray(list) || list.some((t) => !TIERS.includes(t))) throw new QuiltError(400, 'bad_request', `tiers.${name}: a list of ${TIERS.join(', ')}`)
+    out[name] = TIERS.filter((t) => list.includes(t))
+  }
+  if (Object.keys(out).length > 100) throw new QuiltError(400, 'bad_request', 'tiers: up to 100 checks')
+  return out
+}
+
+/** Checks a list of path globs (`tests`, `ci_config`). */
+export function cleanGlobs (globs, what) {
+  if (globs === null) return []
+  if (!Array.isArray(globs) || globs.length > 50 || globs.some((g) => typeof g !== 'string' || !g.trim() || g.length > 300 || g.split('/').includes('..'))) {
+    throw new QuiltError(400, 'bad_request', `${what}: a list of up to 50 path globs (*, **, ?), e.g. ["test/**", "**/*.test.js"]`)
+  }
+  return [...new Set(globs.map((g) => g.trim().replace(/^\.\//, '')))]
+}
+
+/** Checks `runners` from a policy body: { check: [member id, …] }. */
+export function cleanRunners (runners, nameOk) {
+  if (runners === null) return {}
+  if (typeof runners !== 'object' || Array.isArray(runners)) throw new QuiltError(400, 'bad_request', 'runners: { "<check>": ["<member id>", …] }')
+  const out = {}
+  for (const [name, list] of Object.entries(runners)) {
+    if (!nameOk(name)) throw new QuiltError(400, 'bad_request', `${name || '(empty)'} is not a check name`)
+    if (!Array.isArray(list) || list.length > MAX_RUNNERS || list.some((m) => typeof m !== 'string' || !m || m.length > 200)) throw new QuiltError(400, 'bad_request', `runners.${name}: a list of up to ${MAX_RUNNERS} member ids`)
+    if (list.length) out[name] = [...new Set(list)]
+  }
+  if (Object.keys(out).length > 100) throw new QuiltError(400, 'bad_request', 'runners: up to 100 checks')
+  return out
+}
+
+/** A verdict's log link: an http(s) or file address up to 2,000 characters. */
+export function cleanUrl (url) {
+  if (url == null || url === '') return null
+  if (typeof url !== 'string' || url.length > 2000 || !/^(https?|file):\/\/\S+$/.test(url)) throw new QuiltError(400, 'bad_request', 'url: the log\'s http(s) or file:// address')
+  return url
+}
+
+/** Every check a rule mentions (required, with runners or with tiers), in order. */
+const checkNames = (rule) => [...new Set([...(rule.checks || []), ...Object.keys(rule.runners || {}), ...Object.keys(rule.tiers || {})])]
+
+const view = (r) => ({
+  id: r.id, run_key: r.run_key, name: r.name, tier: r.tier, state: r.state,
+  commit: r.commit, ...(r.square_id ? { square: squareShort(r.square_id), square_id: r.square_id } : {}), line: r.line,
+  ...(r.patch_no != null ? { patch_no: r.patch_no } : {}),
+  requested_by: r.requested_by, runners: r.runners || [],
+  ...(r.affected ? { affected: r.affected } : {}), ...(r.url ? { url: r.url } : {}), ...(r.verdict ? { verdict: r.verdict } : {}), ...(r.by ? { by: r.by } : {}), ...(r.advisory ? { advisory: true } : {}),
+  at: r.at, ...(r.finished_at ? { finished_at: r.finished_at } : {})
+})
+
+export function checkOps (svc) {
+  const { store, now, quiltFor, squareByRef, reader, snapshot, getCommit } = svc.internals
+
+  const ruleOf = async (qid, line) => {
+    const r = (await store.lineRules(qid)).find((x) => x.line === line) || { line, approvals: 0, checks: [], runners: {} }
+    return { ...r, ...(r.targeting || {}) }
+  }
+
+  /** Which tests the change from..to reaches (affected.js), for a pre-merge run. */
+  async function affectedFor (qid, rule, from, to, changed) {
+    if (!rule.tests?.length) return { confidence: 'all', why: 'the line names no tests' }
+    const r = reader(qid)
+    const entries = await r.list(await snapshot(qid, to), [''])
+    const byPath = new Map(entries.map((e) => [e.path, e]))
+    return affectedTests({
+      changed, files: entries.map((e) => e.path), tests: rule.tests, ci_config: rule.ci_config || [],
+      read: async (p) => (await svc.internals.readBlob(qid, byPath.get(p).blob)).toString('utf8')
+    })
+  }
+
+  async function changedPaths (qid, from, to) {
+    if (!to) return []
+    return (await reader(qid).diff(await snapshot(qid, from || null), await snapshot(qid, to))).map((e) => e.path)
+  }
+
+  /** A run and its check.requested event (the event carries the run so the events job stores it). */
+  function request ({ qid, name, tier, commit, square, line, patch_no, runners, requested_by, at, cause_seq, paths, affected, run_key: key }) {
+    const run = { id: uuidv7(at), run_key: key || runKey({ tier, name, commit }), name, tier, commit, square_id: square || null, line, patch_no: patch_no ?? null, runners, requested_by, state: 'queued', at, affected }
+    return {
+      kind: 'check.requested', at, cause_seq, square: square || null, line, paths: paths.slice(0, MAX_PATHS),
+      payload: { check: name, tier, commit, run_key: run.run_key, requested_by, affected, ...(patch_no != null ? { patch_no } : {}) },
+      recipients: runners, run
+    }
+  }
+
+  /** The check.requested events one log row causes (events.js calls this from derive). */
+  async function requestedBy (qid, row) {
+    const out = []
+    // A row written before the line's policy last changed asks nobody (the events job reads the
+    // log after the fact; the policy of that moment is the one that counts).
+    const before = (rule) => rule.since_seq != null && Number(row.seq) <= Number(rule.since_seq)
+    if (row.kind === 'commit' && row.square) {
+      const sq = await store.getSquare(row.square)
+      if (!sq || sq.import || !['open', 'merging'].includes(sq.state)) return out
+      const rule = await ruleOf(qid, sq.line)
+      if (before(rule)) return out
+      const names = checkNames(rule).filter((n) => runnersOf(rule, n).length && tiersOf(rule, n).includes('pre_merge'))
+      if (!names.length) return out
+      const paths = await changedPaths(qid, sq.base, row.commit)
+      const affected = await affectedFor(qid, rule, sq.base, row.commit, paths)
+      for (const name of names) out.push(request({ qid, name, tier: 'pre_merge', commit: row.commit, square: sq.id, line: sq.line, runners: runnersOf(rule, name), requested_by: 'policy', at: row.at, cause_seq: row.seq, paths, affected }))
+    } else if (row.kind === 'square' && row.payload?.op === 'checks_requested') {
+      const sq = await store.getSquare(row.square)
+      if (!sq) return out
+      const rule = await ruleOf(qid, sq.line)
+      const paths = await changedPaths(qid, sq.base, row.payload.head)
+      let affected = null
+      for (const name of row.payload.checks || []) {
+        const runners = runnersOf(rule, name)
+        if (!runners.length) continue
+        affected = affected || await affectedFor(qid, rule, sq.base, row.payload.head, paths)
+        out.push(request({ qid, name, tier: 'pre_merge', commit: row.payload.head, square: sq.id, line: sq.line, runners, requested_by: 'holder', at: row.at, cause_seq: row.seq, paths, affected }))
+      }
+    } else if (row.kind === 'policy' && row.payload?.op === 'check_rerun') {
+      const p = row.payload
+      const rule = await ruleOf(qid, row.line)
+      const runners = runnersOf(rule, p.check)
+      if (!runners.length) return out
+      const sq = p.tier === 'pre_merge' && row.square ? await store.getSquare(row.square) : null
+      const paths = sq ? await changedPaths(qid, sq.base, p.commit) : (await getCommit(qid, p.commit)).changes.map((ch) => ch.path)
+      const affected = sq ? await affectedFor(qid, rule, sq.base, p.commit, paths) : POST_ALL
+      out.push(request({ qid, name: p.check, tier: p.tier, commit: p.commit, square: sq?.id, line: row.line, runners, requested_by: 'rerun', at: row.at, cause_seq: row.seq, paths, affected, run_key: p.run_key }))
+    } else if (row.kind === 'merge') {
+      const rule = await ruleOf(qid, row.line)
+      if (before(rule)) return out
+      const names = checkNames(rule).filter((n) => runnersOf(rule, n).length && tiersOf(rule, n).includes('post_merge'))
+      if (!names.length) return out
+      const c = await getCommit(qid, row.commit)
+      const paths = c.changes.map((ch) => ch.path)
+      // The post-merge tier always runs everything: a wrong pre-merge `affected` is caught here.
+      const affected = POST_ALL
+      for (const name of names) out.push(request({ qid, name, tier: 'post_merge', commit: row.commit, square: null, line: row.line, patch_no: row.patch_no, runners: runnersOf(rule, name), requested_by: 'policy', at: row.at, cause_seq: row.seq, paths, affected }))
+    }
+    return out
+  }
+
+  /**
+   * A square asks to merge and a required check with runners has no run on its head: write a
+   * log row that asks its runners (once per head: a run that exists is not asked again).
+   */
+  async function askForMissing (q, sq, missing, actor) {
+    if (!sq.head || !missing.length) return
+    if (svc.internals.pumpEvents) await svc.internals.pumpEvents(q) // runs already asked for are stored
+    const rule = await ruleOf(q, sq.line)
+    const have = new Set((await store.checkRuns(q, { square_id: sq.id, tier: 'pre_merge' })).filter((r) => r.commit === sq.head && !r.advisory).map((r) => r.name))
+    const ask = missing.filter((n) => runnersOf(rule, n).length && !have.has(n))
+    if (!ask.length) return
+    await store.setSquare({ square_id: sq.id, patch: {}, op: 'checks_requested', log: { checks: ask, head: sq.head }, actor, at: now() }).catch(() => {})
+  }
+
+  /**
+   * Records a reported verdict on its run. Returns { advisory: true } when the reporter is not one
+   * of the check's runners (the caller then leaves the gating state alone).
+   */
+  async function noteVerdict (me, q, { name, tier, commit, square, line, verdict, run_key: key, url }) {
+    const link = cleanUrl(url)
+    const rule = await ruleOf(q.id, line)
+    const runners = runnersOf(rule, name)
+    const counts = !runners.length || runners.includes(me.member_id) || (me.on_behalf_of && runners.includes(me.on_behalf_of))
+    const at = now()
+    if (!counts) {
+      await store.addCheckRuns({ quilt_id: q.id, runs: [{ id: uuidv7(at), run_key: `advisory:${tier}:${name}:${commit}:${me.member_id}`, name, tier, commit, square_id: square || null, line, runners, requested_by: 'holder', state: 'done', verdict, by: me.member_id, advisory: true, at, finished_at: at, ...(link ? { url: link } : {}) }] })
+      return { advisory: true }
+    }
+    let target = key
+    if (!target && tier === 'pre_merge') target = runKey({ tier, name, commit })
+    if (!target && tier === 'post_merge') {
+      const open = (await store.checkRuns(q.id, { tier, name, line })).filter((r) => r.state === 'queued' || r.state === 'running')
+      target = open.length ? open.at(-1).run_key : null // the oldest open one (the list is newest first)
+    }
+    if (target) {
+      try { await store.setCheckRun({ quilt_id: q.id, run_key: target, state: 'done', verdict, by: me.member_id, at, ...(link ? { url: link } : {}) }) } catch (err) { if (err.code !== 'not_found') throw err }
+    }
+    return {}
+  }
+
+  /**
+   * Cancels what a batch of new requests supersedes (13 "Tiers"): a pre-merge request cancels the
+   * open runs of the same check on the same square (an older head, or the same head re-run); a
+   * post-merge request on a line keeps the oldest open run and cancels the middle ones (their
+   * patches stay after the check's last green, so the next run covers them). A superseded request
+   * from the same batch is dropped before anyone hears of it; a stored run gets check.cancelled.
+   * Returns the events to write and the stored runs to mark cancelled once they are written.
+   */
+  async function settleRuns (qid, events) {
+    const cancels = []
+    const out = []
+    const pending = [] // requests of this batch still standing: [event, run]
+    for (const e of events) {
+      if (e.kind !== 'check.requested' || !e.run) { out.push(e); continue }
+      const r = e.run
+      const pre = r.tier === 'pre_merge'
+      const same = (x) => x.name === r.name && x.tier === r.tier && x.run_key !== r.run_key && (pre ? x.square_id === r.square_id : x.line === r.line)
+      const stored = (await store.checkRuns(qid, { name: r.name, tier: r.tier, ...(pre ? { square_id: r.square_id } : { line: r.line }), limit: 500 }))
+        .filter((x) => !x.advisory && OPEN.has(x.state) && same(x) && !cancels.some((c) => c.run_key === x.run_key) && !pending.some(([, b]) => b.run_key === x.run_key))
+        .reverse() // oldest first
+      const open = [...stored.map((x) => ({ stored: x })), ...pending.filter(([, b]) => same(b)).map(([ev, b]) => ({ ev, b }))]
+      for (const v of pre ? open : open.slice(1)) {
+        if (v.ev) { pending.splice(pending.findIndex(([ev]) => ev === v.ev), 1); out.splice(out.indexOf(v.ev), 1); continue }
+        const x = v.stored
+        cancels.push(x)
+        out.push({
+          kind: 'check.cancelled', at: e.at, cause_seq: e.cause_seq, square: x.square_id || null, line: x.line, paths: [],
+          payload: { check: x.name, tier: x.tier, commit: x.commit, run_key: x.run_key, reason: 'superseded', superseded_by: r.run_key },
+          recipients: x.runners || []
+        })
+      }
+      out.push(e)
+      pending.push([e, r])
+    }
+    return { events: out, cancels }
+  }
+
+  /** Marks the runs settleRuns cancelled (after their check.cancelled events are written). */
+  async function applyCancels (qid, cancels) {
+    for (const x of cancels) {
+      try { await store.setCheckRun({ quilt_id: qid, run_key: x.run_key, state: 'cancelled', at: now(), expect_state: x.state }) } catch (err) { if (!['not_found', 'square_state'].includes(err.code)) throw err }
+    }
+  }
+
+  /**
+   * POST /squares/:s/checks/:name/rerun and /lines/:l/checks/:name/rerun: asks the check's runners
+   * again, on the square's head (pre_merge) or the line's tip (post_merge), or on `commit`.
+   */
+  async function rerunCheck (me, ref, { check, square, line, commit } = {}) {
+    const q = await quiltFor(me, ref, 'write')
+    const name = String(check || '')
+    if (!name || (!square && !line)) throw new QuiltError(400, 'bad_request', 'give the check and a square or a line: seam check rerun <check> --square <square> | --line <line>')
+    let sq = null
+    let tier, at, lineName
+    if (square) {
+      sq = await squareByRef(q.id, square)
+      tier = 'pre_merge'; lineName = sq.line; at = commit || sq.head
+    } else {
+      lineName = String(line)
+      const ln = await store.getLine(q.id, lineName)
+      if (!ln) throw new QuiltError(404, 'not_found', `no line ${lineName}`)
+      tier = 'post_merge'; at = commit || ln.tip
+    }
+    if (!at) throw new QuiltError(409, 'nothing_to_run', `${sq ? squareShort(sq.id) : lineName} has no commit to run ${name} on`)
+    const full = (await getCommit(q.id, at)).id
+    const rule = await ruleOf(q.id, lineName)
+    if (!runnersOf(rule, name).length) throw new QuiltError(409, 'no_runners', `${name} has no runners on ${lineName}: name them with seam line require ${lineName} --runners ${name}=<member>`)
+    if (svc.internals.pumpEvents) await svc.internals.pumpEvents(q.id)
+    const base = runKey({ tier, name, commit: full })
+    const n = (await store.checkRuns(q.id, { name, tier, ...(sq ? { square_id: sq.id } : { line: lineName }), limit: 500 })).filter((r) => r.run_key.startsWith(base + ':rerun')).length + 1
+    const key = `${base}:rerun${n}`
+    try {
+      await store.requestCheckRun({ quilt_id: q.id, line: lineName, square_id: sq?.id || null, actor: me.member_id, at: now(), payload: { op: 'check_rerun', check: name, tier, commit: full, run_key: key } })
+    } catch (err) { throw svc.internals.fromStore(err) }
+    return { check: name, tier, commit: full, run_key: key, ...(sq ? { square: squareShort(sq.id) } : { line: lineName }) }
+  }
+
+  /** GET /checks?state=&name=&tier=&line=&square=: the quilt's check runs, newest first. */
+  async function checkRuns (me, ref, { state, name, tier, line, square, limit = 100 } = {}) {
+    const q = await quiltFor(me, ref, 'read')
+    if (state && !RUN_STATES.includes(state)) throw new QuiltError(400, 'bad_request', `state is one of ${RUN_STATES.join(', ')}`)
+    if (tier && !TIERS.includes(tier)) throw new QuiltError(400, 'bad_request', `tier is one of ${TIERS.join(', ')}`)
+    const sq = square ? await squareByRef(q.id, square) : null
+    if (svc.internals.pumpEvents) await svc.internals.pumpEvents(q.id) // as GET /events: every run asked for so far is there
+    const rows = await store.checkRuns(q.id, { state, name, tier, line, square_id: sq?.id, limit: Math.min(Number(limit) || 100, 500) })
+    return { runs: rows.map(view) }
+  }
+
+  return { requestedBy, askForMissing, noteVerdict, checkRuns, settleRuns, applyCancels, rerunCheck }
+}