@heyquilt/seam 0.27.0 → 0.130.0

package/lib/quilts/ignored.js

@@ -0,0 +1,46 @@
+// The server's ignore check (05 "Ignore rules and the .env rule"). A hosted agent or a hand-written
+// client never runs a client-side matcher, so with `ignoredPath` on (SEAM_IGNORED_PATH=1) a commit's
+// puts are refused with 422 ignored_path when a built-in names the path (always, tracked or not:
+// a .gitignore cannot un-ignore one), or when the path is not in the first parent's tree and a
+// .gitignore on its way down in that tree matches it (the deepest file with a rule wins, as in git).
+// Deletes always go through, so a tracked .env from an import can be removed.
+import ignore from 'ignore'
+
+/** Always ignored, everywhere. No tool's own folders: only what no project wants committed. */
+export const BUILTIN_IGNORED = ['.git', '.seam', 'node_modules', '.DS_Store', 'Thumbs.db', '.next', '.turbo', '.nuxt', '.svelte-kit', '.parcel-cache', '.vercel', '.env', '.env.*', '!.env.example', '*.swp', '*.swo', '*~', '.#*', '.seamignore']
+const BUILTIN = ignore().add(BUILTIN_IGNORED)
+
+export const builtinIgnored = (path) => BUILTIN.ignores(path)
+
+/**
+ * The paths among `puts` the rules refuse, in the order given. `tracked(path)` says whether the
+ * path is in the parent tree; `readText(path)` gives a file of the parent tree as text, or null.
+ */
+export async function ignoredPaths (puts, { tracked, readText }) {
+  const rules = new Map() // folder → ignore instance or null
+  const rulesIn = async (dir) => {
+    if (!rules.has(dir)) {
+      const text = await readText(dir ? `${dir}/.gitignore` : '.gitignore')
+      rules.set(dir, text == null ? null : ignore().add(text))
+    }
+    return rules.get(dir)
+  }
+  const out = []
+  for (const p of puts) {
+    if (builtinIgnored(p)) { out.push(p); continue }
+    if (await tracked(p)) continue
+    const parts = p.split('/')
+    let verdict = false
+    // Deepest first: the first .gitignore with a rule for the path decides.
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const dir = parts.slice(0, i).join('/')
+      const ig = await rulesIn(dir)
+      if (!ig) continue
+      const res = ig.test(parts.slice(i).join('/'))
+      if (res.ignored) { verdict = true; break }
+      if (res.unignored) break
+    }
+    if (verdict) out.push(p)
+  }
+  return out
+}

package/lib/quilts/import-git.js

@@ -77,7 +77,33 @@ function diffTree (repo, parent, sha) {
 }
 
 const agentEmail = /@agents\.noreply\.heyquilt\.com$/i
-const member = (who) => ({ member_id: `stub:${String(who.email || who.name).toLowerCase()}`, kind: agentEmail.test(who.email || '') ? 'agent' : 'person', name: who.name || who.email })
+/**
+ * A git author's member (14, "Authors to members"): `authors` (email → member id, like
+ * .mailmap, any case) wins; anything else is the stub member of its email. The server refuses a
+ * mapped id that is not a member of the quilt.
+ */
+export function checkAuthors (authors) {
+  if (authors == null) return {}
+  if (typeof authors !== 'object' || Array.isArray(authors)) throw Object.assign(new Error('authors: an object of email → member id'), { status: 400, code: 'bad_request' })
+  const out = {}
+  const entries = Object.entries(authors)
+  if (entries.length > 10000) throw Object.assign(new Error('authors: at most 10000 emails'), { status: 400, code: 'bad_request' })
+  for (const [email, id] of entries) {
+    if (!email.includes('@') || email.length > 320 || typeof id !== 'string' || !id || id.length > 200 || id.startsWith('stub:')) throw Object.assign(new Error(`authors: ${email.slice(0, 80)} must map to a member id`), { status: 400, code: 'bad_request' })
+    out[email.trim().toLowerCase()] = id
+  }
+  return out
+}
+
+const memberFor = (authors = {}) => {
+  const map = new Map(Object.entries(authors || {}).map(([e, id]) => [e.trim().toLowerCase(), String(id)]))
+  return (who) => {
+    const email = String(who.email || '').toLowerCase()
+    const kind = agentEmail.test(email) ? 'agent' : 'person'
+    const mapped = email && map.get(email)
+    return { member_id: mapped || `stub:${String(who.email || who.name).toLowerCase()}`, kind, name: who.name || who.email }
+  }
+}
 
 /**
  * The branches to import: [{ name, sha }], HEAD's branch first as main. Local branches, then
@@ -115,7 +141,28 @@ function gitTags (repo) {
  * where only the commits it does not have yet are added. Returns { quilt, slug, commits,
  * patches, lines, tags, report, validated? }.
  */
-export async function importGit (client, { repo, slug, batch = 100, log = () => {}, validate = false, limit = 0, onlyHead = false, fresh = false, follow = false }) {
+/**
+ * The authors an import would bring in (14, awaiting_authors): [{ email, name, commits }] over the
+ * same branches importGit reads, the most commits first. Emails in lower case; the latest name.
+ */
+export function gitAuthors (repo, { follow = false, onlyHead = false } = {}) {
+  const head = git(repo, ['rev-parse', 'HEAD']).toString().trim()
+  const refs = onlyHead ? [{ sha: head }] : branches(repo, head).filter((r) => !follow || r.name === 'main' || r.name.startsWith('release/'))
+  const out = new Map()
+  for (const row of git(repo, ['log', '--format=%aE%x00%aN', ...new Set(refs.map((r) => r.sha))]).toString().split('\n')) {
+    if (!row) continue
+    const [e, name] = row.split('\0')
+    const email = e.trim().toLowerCase()
+    const a = out.get(email) || { email, name: name || email, commits: 0 }
+    a.commits++
+    out.set(email, a)
+  }
+  return [...out.values()].sort((a, b) => b.commits - a.commits || (a.email < b.email ? -1 : 1))
+}
+
+export async function importGit (client, { repo, slug, batch = 100, log = () => {}, validate = false, limit = 0, onlyHead = false, fresh = false, follow = false, authors = {} }) {
+  const explicit = checkAuthors(authors)
+  let member = memberFor(explicit)
   const head = git(repo, ['rev-parse', 'HEAD']).toString().trim()
   // follow: only main and release/* (14: the lines an import follows).
   const refs = onlyHead ? [{ name: 'main', sha: head, git: 'HEAD' }] : branches(repo, head).filter((r) => !follow || r.name === 'main' || r.name.startsWith('release/'))
@@ -140,6 +187,11 @@ export async function importGit (client, { repo, slug, batch = 100, log = () =>
         for (const [sha, id] of Object.entries(known)) ids.set(sha, id)
       }
     }
+    // Authors to members, step 2 (14): the emails of new commits that are a member's account email.
+    const emails = [...new Set(all.filter((sha) => !ids.has(sha)).map((sha) => String(info.get(sha).author?.email || '').trim().toLowerCase()).filter((e) => e.includes('@') && e.length <= 320 && !explicit[e]))]
+    const found = {}
+    for (let i = 0; i < emails.length && client.importEmails; i += 5000) Object.assign(found, (await client.importEmails(quilt.id, emails.slice(i, i + 5000))).authors)
+    member = memberFor({ ...found, ...explicit })
     const lineTips = new Map((again ? await client.lines(quilt.id) : [{ name: 'main', tip: null }]).map((l) => [l.name, l.tip]))
     log(again ? `Adding to ${quilt.slug}: ${all.length - ids.size} new commits of ${all.length}…` : `Importing ${all.length} commits on ${refs.length} branches into ${quilt.slug}…`)
 

package/lib/quilts/journal.js

@@ -0,0 +1,105 @@
+// The tip journal (plans/quilt-source-control/03, "The tip journal"; 04): the other durable copy
+// of order, between the last WAL segment and the database. After a `merge`, `move` or `square`
+// row commits (and a `policy` row naming a line: making, freezing or unfreezing it, since replay
+// rebuilds `lines` from those too), the authority appends it to the quilt's current journal group
+// and acknowledges the write only when that group's PUT succeeded. Writes that land within one
+// 200 ms window share one group, so a quilt costs at most one PUT per window. `commit` rows are
+// not journaled: their content is in pack trailers (15's `recover-gap`).
+//
+// A group is the same canonical log records a segment holds, in the segment encoding (archiver.js:
+// 'QWS1', compressed body, hashed trailer), stored at q/<quilt_id>/j/<first_seq>-<last_seq>.qtj.
+// Groups whose rows are all in sealed segments are redundant; gc() deletes them 24 h after that.
+// Behind SEAM_TIP_JOURNAL=1 (index.js), since it adds a PUT to the ack of every merge.
+import { encodeSegment, decodeSegment } from './archiver.js'
+
+export const JOURNAL_WINDOW_MS = 200
+export const JOURNAL_KEEP_MS = 24 * 60 * 60 * 1000
+const ZERO = '0'.repeat(64)
+const pad = (n) => String(n).padStart(12, '0')
+export const groupName = (from, to) => `${pad(from)}-${pad(to)}.qtj`
+const parseName = (name) => { const m = /^(\d{12})-(\d{12})\.qtj$/.exec(name); return m ? { from: Number(m[1]), to: Number(m[2]) } : null }
+
+/** Whether a log row goes in the journal. */
+export const journaled = (row) => row.kind === 'merge' || row.kind === 'move' || row.kind === 'square' ||
+  (row.kind === 'policy' && !!row.line && ['line', 'freeze', 'unfreeze'].includes(row.payload?.op))
+
+/**
+ * The journal over a store and an object store. `sync(q)` resolves once every journaled row the
+ * quilt has now is in object storage (callers in one window share the PUT); it rejects when the
+ * PUT fails, so the write it guards is not acknowledged. `gc(q)` deletes redundant groups.
+ */
+export function createJournal ({ store, objects, now = Date.now, windowMs = JOURNAL_WINDOW_MS, keepMs = JOURNAL_KEEP_MS }) {
+  const done = new Map() // quilt -> the last seq looked at and written
+  const pending = new Map() // quilt -> the window's promise
+
+  async function startSeq (q) {
+    if (done.has(q)) return done.get(q)
+    const quilt = await store.getQuilt(q)
+    let at = quilt?.archive_seq || 0
+    for (const name of await objects.listFiles(q, 'j')) { const g = parseName(name); if (g && g.to > at) at = g.to }
+    return at
+  }
+
+  async function flush (q) {
+    pending.delete(q)
+    const after = await startSeq(q)
+    const rows = []
+    let last = after
+    for (;;) {
+      const page = await store.logRows(q, { after: last, limit: 1000 })
+      if (!page.length) break
+      for (const row of page) { last = row.seq; if (journaled(row)) rows.push(row) }
+      if (page.length < 1000) break
+    }
+    if (rows.length) {
+      const from = rows[0].seq
+      const to = rows[rows.length - 1].seq
+      const { bytes } = encodeSegment({ quilt_id: q, from_seq: from, to_seq: to, prev: ZERO, records: rows.map((row) => ({ t: 'log', row })) })
+      await objects.putFile(q, 'j', groupName(from, to), bytes)
+    }
+    if (last > (done.get(q) || 0)) done.set(q, last)
+    return { rows: rows.length, through: last }
+  }
+
+  function sync (q) {
+    if (pending.has(q)) return pending.get(q)
+    const p = new Promise((resolve) => setTimeout(resolve, windowMs)).then(() => flush(q))
+    pending.set(q, p)
+    return p
+  }
+
+  // When each group was first seen redundant (all its rows sealed in segments), in this process.
+  // A restart only delays a deletion; it never deletes early.
+  const redundantSince = new Map()
+  async function gc (q) {
+    const quilt = await store.getQuilt(q)
+    const sealed = quilt?.archive_seq || 0
+    let deleted = 0
+    for (const name of await objects.listFiles(q, 'j')) {
+      const g = parseName(name)
+      if (!g || g.to > sealed) continue
+      const key = `${q}/${name}`
+      if (!redundantSince.has(key)) redundantSince.set(key, now())
+      if (now() - redundantSince.get(key) < keepMs) continue
+      await objects.deleteFile(q, 'j', name)
+      redundantSince.delete(key)
+      deleted++
+    }
+    return { deleted }
+  }
+
+  return { sync, gc }
+}
+
+/** Every journaled row with seq past `after`, from the quilt's groups, in seq order (each group's hash checked). */
+export async function readJournal (objects, q, after = 0) {
+  const rows = new Map()
+  for (const name of await objects.listFiles(q, 'j')) {
+    const g = parseName(name)
+    if (!g || g.to <= after) continue
+    const { trailer, records } = decodeSegment(await objects.readFile(q, 'j', name))
+    if (trailer.quilt_id !== q) throw new Error(`journal group ${name} belongs to quilt ${trailer.quilt_id}`)
+    for (const r of records) if (r.t === 'log' && r.row.seq > after) rows.set(r.row.seq, r.row)
+  }
+  return [...rows.values()].sort((a, b) => a.seq - b.seq)
+}

package/lib/quilts/limits.js

@@ -0,0 +1,197 @@
+// Per-token rate limits (plans/quilt-source-control/04 "Rate limiting and load shedding",
+// decision 40): counted per token, so an agent's key and the person it works for are limited
+// apart; a person's token gets five times an agent's numbers (11). A limit answers at once with
+// 429 rate_limited, `limit` naming its row and `retry_after` seconds; nothing waits.
+// Counted in this API process (sliding windows of request times), where a token can reach one
+// allowance per machine; or, with `shared` (a store, SEAM_SHARED_LIMITS=1), in the database's
+// fixed windows (quilt_rate_take), one allowance however many machines answer.
+import crypto from 'node:crypto'
+import { QuiltError } from './errors.js'
+
+const MIN = 60 * 1000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+
+/** 04's rows for an agent token: [name, count, window ms, which requests]. */
+export const LIMITS = [
+  ['token_rate', 600, MIN, 'rpc'],
+  ['commit_rate', 60, MIN, 'commit'],
+  ['commit_rate', 2000, DAY, 'commit'],
+  ['merge_rate', 30, HOUR, 'merge']
+]
+export const PERSON_FACTOR = 5
+
+/** 04's fetch_rate row: 50 want-lists (POST /blobs) a second per token; on with `fetchRate` (SEAM_FETCH_RATE=1). */
+export const FETCH_RATE = ['fetch_rate', 50, 1000, 'fetch']
+
+// Rows that answer a code of their own (12's refusal list); the others answer rate_limited naming the row.
+const OWN_CODES = new Set(['quilt_busy', 'fetch_rate', 'fallback_rate', 'upload_rate'])
+
+/** 04's fallback_rate: a request with `x-quilt-fallback` (a daemon with no relay) gets a tenth of every token row, want-lists included. */
+export const fallbackRows = (limits) => limits.map(([, count, windowMs, kind]) => ['fallback_rate', Math.max(1, Math.floor(count / 10)), windowMs, kind])
+
+/** 04's auth_lockout row: 10 failed authentications a minute lock a token for a minute after its last failure. */
+export const AUTH_LOCKOUT = { failures: 10, windowMs: MIN, lockMs: MIN }
+
+/** 04's rows for a whole quilt, across every token that writes into it; a person's token is not ×5. */
+export const QUILT_LIMITS = [
+  ['quilt_busy', 6000, HOUR, 'commit'],
+  ['upload_rate', 2 ** 40, DAY, 'upload'], // 1 TiB of packs a day
+  ['quilt_busy', 200, 1000, 'write'] // 200 sequenced writes a second (rows only ever appended: the shared store keys by index)
+]
+
+/** 04's rows for one member in one quilt (a person's ×5): bytes of packs uploaded. */
+export const MEMBER_LIMITS = [
+  ['upload_rate', 100 * 2 ** 30, HOUR, 'upload'] // 100 GiB an hour: a 500 GiB file in five hours
+]
+
+/** Which counters a request takes: object traffic (packs, blob and object reads) takes none. */
+export function classify (method, url, body) {
+  const p = String(url).split('?')[0]
+  if (method === 'POST' && /^\/v1\/quilts\/[^/]+\/(blobs|objects)$/.test(p)) return ['fetch'] // a want-list
+  if (method === 'POST' && /^\/v1\/quilts\/[^/]+\/packs$/.test(p)) return ['upload'] // counted in bytes, per member and per quilt
+  if (/\/(packs|objects|blobs)(\/|$)/.test(p)) return []
+  // A sequenced write: any change inside one quilt but have? (an upload check); quilt_busy counts them.
+  const write = method !== 'GET' && method !== 'HEAD' && /^\/v1\/quilts\/[^/]+\/./.test(p) && !/\/have$/.test(p) ? ['write'] : []
+  if (method === 'POST' && /\/squares\/[^/]+\/commit$/.test(p)) return ['rpc', 'commit', ...write]
+  if (method === 'POST' && /\/lines\/[^/]+\/merge$/.test(p)) return body && body.dry_run ? ['rpc'] : ['rpc', 'merge', ...write] // a dry run is never merge-limited
+  return ['rpc', ...write]
+}
+
+/** The token's key: a hash of its Authorization header (the token itself is never kept). */
+export const tokenKey = (req, me) => {
+  const h = req && req.headers && req.headers.authorization
+  return h ? crypto.createHash('sha256').update(h).digest('hex').slice(0, 32) : `member:${me.member_id}:${me.kind}`
+}
+
+const refuse = (name, max, windowMs, retry, scope) => new QuiltError(429, OWN_CODES.has(name) ? name : 'rate_limited', `rate limit ${name}: ${max} in ${windowMs >= DAY ? 'a day' : windowMs >= HOUR ? 'an hour' : windowMs >= MIN ? 'a minute' : 'a second'} for this ${scope}; try again in ${retry} s`, { limit: name, retry_after: retry })
+
+/**
+ * A token's own `rate` (11.9: QuiltToken.rate, downward only) as a share per row name: `rate[name]`
+ * is the count for that name's first (shortest) row, and its longer rows shrink by the same share.
+ * A number above 04's is ignored (never raises).
+ */
+export function rateShares (limits, rate) {
+  if (!rate) return null
+  const out = {}
+  for (const [name, value] of Object.entries(rate)) {
+    const first = limits.find(([n]) => n === name)
+    if (first && Number.isInteger(value) && value > 0 && value < first[1]) out[name] = value / first[1]
+  }
+  return out
+}
+
+/** The names a token's `rate` may lower: 04's per-token rows, fetch_rate included. */
+export const RATE_NAMES = [...new Set([...LIMITS, FETCH_RATE].map(([n]) => n))]
+export const rateDefault = (name) => [...LIMITS, FETCH_RATE].find(([n]) => n === name)[1]
+
+/** A limiter for the token rows (`take`) and the quilt rows (`takeQuilt`, keyed `quilt:<id>`). */
+export function createLimiter ({ now = Date.now, fetchRate = false, limits = fetchRate ? [...LIMITS, FETCH_RATE] : LIMITS, quiltLimits = QUILT_LIMITS, memberLimits = MEMBER_LIMITS, personFactor = PERSON_FACTOR, authLockout = AUTH_LOCKOUT, shared = null } = {}) {
+  const make = shared ? sharedCounter : localCounter
+  const token = make({ now, limits, personFactor, shared, scope: 'token' })
+  const quilt = make({ now, limits: quiltLimits, personFactor: 1, shared, scope: 'quilt' })
+  const member = make({ now, limits: memberLimits, personFactor, shared, scope: 'member in this quilt' })
+  const fallback = make({ now, limits: fallbackRows(limits.some(([n]) => n === 'fetch_rate') ? limits : [...limits, FETCH_RATE]), personFactor, shared, scope: 'token' })
+  return {
+    /** Counts one request of `kinds` for `key`; `scale` (a reader with no token, 11.9) shrinks the allowance. */
+    // `rate`: the token's own lower numbers (11.9), { commit_rate: 10, … }.
+    take: (key, kinds, person, scale = 1, rate = null) => token(key, kinds, person, 1, scale, rateShares(limits, rate)),
+    /** Counts a fallback request (x-quilt-fallback) against a tenth of the token rows, apart from its normal count. */
+    takeFallback: (key, kinds, person) => fallback(`fallback:${key}`, kinds, person),
+    /** Counts one request of `kinds` against the quilt's own rows, whoever sends it. */
+    takeQuilt: (quiltId, kinds) => quilt(`quilt:${quiltId}`, kinds, false),
+    /** Counts `bytes` of a pack upload against the member's rows in the quilt, then the quilt's. */
+    async takeUpload (quiltId, memberId, bytes, person) {
+      await member(`upload:${quiltId}:${memberId}`, ['upload'], person, bytes)
+      await quilt(`quilt:${quiltId}`, ['upload'], false, bytes)
+    },
+    ...(shared ? sharedLockout({ now, shared, ...authLockout }) : lockout({ now, ...authLockout }))
+  }
+}
+
+// auth_lockout with `shared` (SEAM_SHARED_LIMITS=1): failures counted in the store's fixed
+// one-minute windows, checked with a read that counts nothing (`peek`); locked until the window
+// that saw the 10th failure ends.
+function sharedLockout ({ now, shared, failures, windowMs }) {
+  const rows = [{ i: 0, window_ms: windowMs, max: failures }]
+  return {
+    async authCheck (key) {
+      const r = await shared.rateTake({ key: `authfail:${key}`, at: now(), rows, peek: true })
+      if (r && r.ok === false) throw new QuiltError(429, 'auth_lockout', `too many failed sign-ins with these credentials; try again in ${r.retry_after} s`, { limit: 'auth_lockout', retry_after: r.retry_after })
+    },
+    async authFailed (key) { await shared.rateTake({ key: `authfail:${key}`, at: now(), rows }) }
+  }
+}
+
+// auth_lockout (04, 11) counted in this process.
+function lockout ({ now, failures, windowMs, lockMs }) {
+  const fails = new Map() // token key → { times: failure times in the window, until: locked until }
+  return {
+    /** Throws 429 auth_lockout while `key` is locked, before its credentials are even checked. */
+    authCheck (key) {
+      const f = fails.get(key)
+      const t = now()
+      if (f && f.until > t) {
+        const retry = Math.max(1, Math.ceil((f.until - t) / 1000))
+        throw new QuiltError(429, 'auth_lockout', `too many failed sign-ins with these credentials; try again in ${retry} s`, { limit: 'auth_lockout', retry_after: retry })
+      }
+    },
+    /** Records a failed authentication; the 10th in a minute, and each one after, locks for a minute from it. */
+    authFailed (key) {
+      const t = now()
+      let f = fails.get(key)
+      if (!f) { f = { times: [], until: 0 }; fails.set(key, f) }
+      f.times = f.times.filter((x) => x > t - windowMs)
+      f.times.push(t)
+      if (f.times.length >= failures) f.until = Math.max(f.until, t + lockMs)
+      if (fails.size > 10000) for (const [k, v] of fails) if (v.until <= t && !v.times.some((x) => x > t - windowMs)) fails.delete(k)
+    }
+  }
+}
+
+function sharedCounter ({ now, limits, personFactor, shared, scope }) {
+  /** Counts one request of `kinds` for `key` in the shared store, or rejects 429 without counting. */
+  return async function take (key, kinds, person, n = 1, scale = 1, shares = null) {
+    const rows = []
+    limits.forEach(([name, count, windowMs, kind], i) => { if (kinds.includes(kind)) rows.push({ i, window_ms: windowMs, max: Math.max(1, Math.floor((person ? count * personFactor : count) * scale * (shares?.[name] ?? 1))) }) })
+    if (!rows.length) return
+    const r = await shared.rateTake({ key, at: now(), rows, ...(n !== 1 ? { n } : {}) })
+    if (r && r.ok === false) {
+      const [name, , windowMs] = limits[r.row]
+      throw refuse(name, rows.find((x) => x.i === r.row).max, windowMs, r.retry_after, scope)
+    }
+  }
+}
+
+function localCounter ({ now, limits, personFactor, scope }) {
+  const seen = new Map() // key + row index → { list: [time, amount] oldest first, sum }
+
+  /** Counts `n` (1 a request, or bytes) of `kinds` for `key`, or throws 429 without counting it. */
+  return function take (key, kinds, person, n = 1, scale = 1, shares = null) {
+    const t = now()
+    const rows = []
+    for (let i = 0; i < limits.length; i++) {
+      const [name, count, windowMs, kind] = limits[i]
+      if (!kinds.includes(kind)) continue
+      // `scale`: a reader with no token (a public quilt, 11.9) gets a tenth, counted per address.
+      const max = Math.max(1, Math.floor((person ? count * personFactor : count) * scale * (shares?.[name] ?? 1)))
+      const id = `${key}\u0000${i}`
+      let w = seen.get(id)
+      if (!w) { w = { list: [], sum: 0 }; seen.set(id, w) }
+      let drop = 0
+      while (drop < w.list.length && w.list[drop][0] <= t - windowMs) w.sum -= w.list[drop++][1]
+      if (drop) w.list.splice(0, drop)
+      if (w.sum >= max) { // full: free again once enough of the oldest have slid out
+        let left = w.sum
+        let j = 0
+        while (left >= max) left -= w.list[j++][1]
+        const retry = Math.max(1, Math.ceil((w.list[j - 1][0] + windowMs - t) / 1000))
+        throw refuse(name, max, windowMs, retry, scope)
+      }
+      rows.push(w)
+    }
+    for (const w of rows) { w.list.push([t, n]); w.sum += n }
+    // Forget keys with nothing left in any window, so the map stays the size of the active ones.
+    if (seen.size > 10000) for (const [id, w] of seen) if (!w.list.length || w.list[w.list.length - 1][0] <= t - DAY) seen.delete(id)
+  }
+}

package/lib/quilts/linepolicy.js

@@ -0,0 +1,109 @@
+// A line's policy as versions (plans/quilt-source-control/11.4, 13 "Where a policy lives and who
+// changes it"): every change is a new version and a policy log row, and any version can be read
+// back. On a server with SEAM_POLICY_APPROVAL=1 a change waits: a second person who is an admin
+// approves it, or, where the proposer is the quilt's only person with admin, the proposer
+// confirms it with a signature from one of their own signing keys. An agent never proposes,
+// approves or confirms a policy, and nobody approves their own.
+import crypto from 'node:crypto'
+import { QuiltError } from './errors.js'
+import { canonical } from './attest.js'
+import { verifyText, localKey } from './signing.js'
+
+/** What a proposer signs to confirm a version alone: the quilt, line, version and the body's hash. */
+export const confirmText = (quiltId, line, version, body) => `seam-policy-confirm-v1\n${quiltId}\n${line}\n${version}\n${crypto.createHash('sha256').update(canonical(body)).digest('hex')}\n`
+
+const view = (v) => ({ version: v.version, state: v.state, base: v.base, body: v.body, proposed_by: v.proposed_by, at: v.at, ...(v.decided_by ? { decided_by: v.decided_by, decided_at: v.decided_at } : {}), ...(v.confirmed_key ? { confirmed_with: v.confirmed_key } : {}) })
+
+export function linePolicyOps (svc, { approval = false } = {}) {
+  const { store, now, quiltFor, fromStore } = svc.internals
+
+  const versionsOf = async (qid, line) => store.linePolicyVersions(qid, line)
+  const activeOf = (list) => list.filter((v) => v.state === 'active').reduce((m, v) => Math.max(m, v.version), 0)
+
+  /** The quilt's members who are people with the admin role. */
+  async function personAdmins (qid) { return (await store.members(qid)).filter((m) => m.level === 'admin' && m.member_id.startsWith('person:')).map((m) => m.member_id) }
+
+  /**
+   * Records `body` as the line's next version: active at once, or pending a second admin (or the
+   * proposer's signed confirmation) on a server that asks for approval.
+   */
+  async function propose (q, me, line, body) {
+    const state = approval ? 'pending' : 'active'
+    // The store numbers the version and records its base (the active version) in one call.
+    let row
+    try { row = await store.addLinePolicyVersion({ quilt_id: q.id, line, body, state, proposed_by: me.member_id, at: now() }) } catch (err) { throw fromStore(err) }
+    const version = row.version
+    if (!approval) return { version }
+    const admins = await personAdmins(q.id)
+    const alone = admins.filter((a) => a !== me.member_id).length === 0
+    return { version, pending: { version, needs: alone ? 'confirmation' : 'approval', how: alone ? `you are the only person with admin: confirm it with your signing key (seam policy confirm ${line} ${version})` : `another person with admin approves it (seam policy approve ${line} ${version})` } }
+  }
+
+  async function pendingVersion (me, ref, line, version) {
+    const q = await quiltFor(me, ref, 'admin')
+    if (me.kind !== 'person') throw new QuiltError(403, 'forbidden', 'only a person approves a line\'s policy; an agent\'s approval never counts')
+    const v = (await versionsOf(q.id, String(line))).find((x) => x.version === Number(version))
+    if (!v) throw new QuiltError(404, 'not_found', `${line} has no policy version ${version}`)
+    if (v.state !== 'pending') throw new QuiltError(409, 'policy_state', `version ${version} is ${v.state}`)
+    return { q, v }
+  }
+
+  async function decide (q, line, v, decision, me, extra = {}) {
+    try { await store.decideLinePolicy({ quilt_id: q.id, line, version: v.version, decision, by: me.member_id, at: now(), ...extra }) } catch (err) {
+      if (err.code === 'policy_moved') throw new QuiltError(409, 'policy_moved', `${line}'s policy changed since version ${v.version} was proposed: propose it again`)
+      throw fromStore(err)
+    }
+    return linePolicyVersions(me, q.id, line)
+  }
+
+  /** POST /lines/:line/policy/versions/:v/approve: a second person with admin makes it active. */
+  async function approveLinePolicy (me, ref, line, version) {
+    const { q, v } = await pendingVersion(me, ref, line, version)
+    if (v.proposed_by === me.member_id) throw new QuiltError(403, 'own_policy', 'nobody approves a policy they proposed: another person with admin does, or, alone, confirm it with your signing key')
+    return decide(q, String(line), v, 'approve', me)
+  }
+
+  /** POST /lines/:line/policy/versions/:v/confirm { key, signature }: the only admin confirms with a signing key. */
+  async function confirmLinePolicy (me, ref, line, version, { key, signature } = {}) {
+    const { q, v } = await pendingVersion(me, ref, line, version)
+    if (v.proposed_by !== me.member_id) throw new QuiltError(403, 'forbidden', 'only the proposer confirms a version; others approve it')
+    if ((await personAdmins(q.id)).some((a) => a !== me.member_id)) throw new QuiltError(409, 'needs_approval', 'another person in this quilt has admin: they approve it (a signed confirmation is for a quilt with one admin)')
+    const row = key ? await store.signingKey(String(key)) : null
+    if (!row || row.member !== me.member_id || row.removed_at) throw new QuiltError(400, 'bad_key', `${key || 'key'} is not one of your signing keys (seam key add)`)
+    if (!verifyText(row.public_key, confirmText(q.id, String(line), v.version, v.body), signature)) throw new QuiltError(422, 'bad_signature', 'the signature is not over this version')
+    return decide(q, String(line), v, 'approve', me, { confirmed_key: row.id })
+  }
+
+  /** POST /lines/:line/policy/versions/:v/reject: any person with admin, the proposer included. */
+  async function rejectLinePolicy (me, ref, line, version) {
+    const { q, v } = await pendingVersion(me, ref, line, version)
+    return decide(q, String(line), v, 'reject', me)
+  }
+
+  /** GET /lines/:line/policy/versions: every version, newest first, and which one is active. */
+  async function linePolicyVersions (me, ref, line) {
+    const q = await quiltFor(me, ref, 'read')
+    const list = await versionsOf(q.id, String(line))
+    return { line: String(line), active: activeOf(list), versions: list.slice().sort((a, b) => b.version - a.version).map(view) }
+  }
+
+  /** One version (GET /lines/:line/policy?version=). */
+  async function linePolicyVersion (me, ref, line, version) {
+    const r = await linePolicyVersions(me, ref, line)
+    const v = r.versions.find((x) => x.version === Number(version))
+    if (!v) throw new QuiltError(404, 'not_found', `${line} has no policy version ${version}`)
+    return { line: String(line), ...v.body, version: v.version, state: v.state }
+  }
+
+  return { propose, approveLinePolicy, confirmLinePolicy, rejectLinePolicy, linePolicyVersions, linePolicyVersion }
+}
+
+/** `seam policy confirm`: signs a pending version with this computer's signing key and sends it. */
+export async function confirmWithLocalKey (client, quilt, line, version) {
+  const k = localKey()
+  if (!k) throw new Error('No signing key on this computer: run seam key add first.')
+  const [info, list] = [await client.quilt(quilt), await client.linePolicyVersions(quilt, line)]
+  const v = list.versions.find((x) => x.version === version)
+  if (!v) throw new Error(`${line} has no policy version ${version}`)
+  return client.confirmLinePolicy(quilt, line, version, { key: k.key, signature: k.signText(confirmText(info.id, line, version, v.body)) })
+}