@heyquilt/seam 0.27.0 → 0.130.0

package/lib/quilts/cas.js

@@ -0,0 +1,78 @@
+// The machine cache (plans/quilt-source-control/04 "Three tiers", 05): immutable objects by id,
+// shared by every block on this machine and every quilt, in ~/.seam/cas/<kind>/<id[0:2]>/<id>.
+// It plans downloads and nothing else (04): what is here is never a reason to skip an upload.
+// Every read checks the bytes against the id, so a file changed on disk is dropped, never served.
+// Kept under a byte cap (SEAM_CAS_BYTES, default 2 GiB; 0 turns it off), least recently used
+// first out. Only plain objects whose id is the hash of their bytes go in: tree nodes and the
+// files of quilts that are not sealed.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { idOf, isId } from './hash.js'
+
+export const CAS_BYTES = 2 * 1024 ** 3
+
+export function machineCas ({ dir = path.join(os.homedir(), '.seam', 'cas'), env = process.env, capBytes } = {}) {
+  const cap = capBytes ?? (env.SEAM_CAS_BYTES !== undefined && env.SEAM_CAS_BYTES !== '' ? Number(env.SEAM_CAS_BYTES) : CAS_BYTES)
+  const on = Number.isFinite(cap) && cap > 0
+  let total = null // bytes held, counted once per process on first write
+  const file = (kind, id) => path.join(dir, kind, id.slice(0, 2), id)
+  const all = () => {
+    const out = []
+    for (const kind of fs.existsSync(dir) ? fs.readdirSync(dir) : []) {
+      const kd = path.join(dir, kind)
+      for (const pre of fs.statSync(kd).isDirectory() ? fs.readdirSync(kd) : []) {
+        for (const id of fs.readdirSync(path.join(kd, pre))) {
+          const f = path.join(kd, pre, id)
+          try { const st = fs.statSync(f); out.push({ f, size: st.size, used: st.mtimeMs }) } catch {}
+        }
+      }
+    }
+    return out
+  }
+  const count = () => { if (total === null) total = all().reduce((n, x) => n + x.size, 0); return total }
+  const prune = () => {
+    const list = all().sort((a, b) => a.used - b.used)
+    total = list.reduce((n, x) => n + x.size, 0)
+    for (const x of list) {
+      if (total <= cap) break
+      try { fs.rmSync(x.f, { force: true }); total -= x.size } catch {}
+    }
+  }
+  return {
+    file,
+    bytes: () => count(),
+    /** The object's bytes, or null (not here, off, or changed on disk: then removed). */
+    get (kind, id) {
+      if (!on || !isId(id)) return null
+      const f = file(kind, id)
+      let b
+      try { b = fs.readFileSync(f) } catch { return null }
+      if (idOf(kind, b) !== id) { fs.rmSync(f, { force: true }); if (total !== null) total -= b.length; return null }
+      const t = new Date()
+      try { fs.utimesSync(f, t, t) } catch {}
+      return b
+    },
+    /** Keeps an object whose bytes hash to its id; false when they do not, or the cache is off. */
+    put (kind, id, bytes) {
+      if (!on || !isId(id) || bytes.length > cap || idOf(kind, bytes) !== id) return false
+      const f = file(kind, id)
+      if (fs.existsSync(f)) return true
+      // A home folder this process cannot write (a locked-down CI job) leaves the cache empty, never fails a checkout.
+      try {
+        count()
+        fs.mkdirSync(path.dirname(f), { recursive: true })
+        const tmp = `${f}.${process.pid}.tmp`
+        fs.writeFileSync(tmp, bytes)
+        fs.renameSync(tmp, f)
+        total += bytes.length
+        if (total > cap) prune()
+        return true
+      } catch { return false }
+    }
+  }
+}
+
+let shared = null
+/** This process's machine cache (home and settings read once). */
+export const theCas = () => (shared ??= machineCas())

package/lib/quilts/cbor.js

@@ -56,8 +56,10 @@ export function encode (v) {
 export function decode (buf) {
   const b = Buffer.from(buf.buffer ? buf : Buffer.from(buf))
   let pos = 0
+  const need = (n) => { if (pos + n > b.length) throw new Error('cbor: truncated') }
   const arg = (info) => {
     if (info < 24) return info
+    if (info <= 27) need(1 << (info - 24))
     if (info === 24) return b[pos++]
     if (info === 25) { const n = b.readUInt16BE(pos); pos += 2; return n }
     if (info === 26) { const n = b.readUInt32BE(pos); pos += 4; return n }

package/lib/quilts/claims.js

@@ -0,0 +1,409 @@
+// Claims on a square's files (plans/quilt-source-control/06, "Claims on squares"): a claim says
+// "this square is working on these paths" so nobody else spends work on them. A write under a
+// claimed pattern from another open square on the same line is refused (412 claim_refused) and the
+// writer is told who holds it and why. A claim lasts while its square is open: merging, abandoning
+// or archiving the square lets go of it. Merges never check claims; overlapping work that was
+// written before a claim existed still meets at the merge (07).
+import { QuiltError, squareShort } from './errors.js'
+import { uuidv7 } from './ids.js'
+
+export const MAX_PATTERN = 500
+export const MAX_NOTE = 300
+export const MAX_CLAIMS = 200 // per square
+
+/** A path, folder or simple glob (*, **, ?) as a matcher over file paths. */
+export function globMatcher (pattern) {
+  const p = String(pattern).trim().replace(/^\.\//, '')
+  if (!/[*?]/.test(p)) {
+    const base = p.replace(/\/+$/, '')
+    return (rel) => rel === base || rel.startsWith(base + '/')
+  }
+  let re = ''
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i]
+    if (c === '*' && p[i + 1] === '*') {
+      re += '.*'
+      i++
+      if (p[i + 1] === '/') i++
+    } else if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  const rx = new RegExp(`^${re}$`)
+  return (rel) => rx.test(rel)
+}
+
+/** Whether two patterns can cover the same file (paths: files that exist now). */
+export function patternsOverlap (a, b, paths = []) {
+  if (a === b) return true
+  const ma = globMatcher(a)
+  const mb = globMatcher(b)
+  if (ma(b) || mb(a) || paths.some((p) => ma(p) && mb(p))) return true
+  // A glob reaches every file under the text before its first wildcard: when one pattern's stem
+  // is inside the other's, they may meet on a file that does not exist yet.
+  const stem = (p) => p.split(/[*?]/)[0]
+  const [sa, sb] = [stem(a), stem(b)]
+  if (sa === a && sb === b) return false
+  const [short, long] = sa.length <= sb.length ? [sa, sb] : [sb, sa]
+  return short !== '' && (long.startsWith(short.endsWith('/') ? short : short + '/') || long === short)
+}
+
+/** A claim pattern: a relative path, folder or glob, no `..`. */
+export function claimPattern (raw) {
+  const p = String(raw || '').trim().replace(/^\.\//, '')
+  if (!p || p.length > MAX_PATTERN || p.startsWith('/') || p.split('/').includes('..') || p.includes('\0') || p.includes('\\')) {
+    throw new QuiltError(400, 'bad_request', `a claim is a relative path, folder or glob (*, **, ?), up to ${MAX_PATTERN} characters`)
+  }
+  return p
+}
+
+const ACTIVE = new Set(['open', 'merging'])
+
+/** 06 "Auto-claims following edits": an auto-claim lets go this long after the last write to it. */
+export const AUTO_CLAIM_QUIET_MS = 10 * 60_000
+
+/**
+ * After square `sq` wrote `paths` (SEAM_AUTO_CLAIMS): claims each path nobody's live claim covers
+ * for it, `auto`, and refreshes its own auto-claims on paths it wrote again. A path under a claim
+ * (its own made on purpose, or a parent's it writes under) is left alone. Best effort: a write never
+ * fails for it.
+ */
+export async function autoClaim (store, q, sq, paths, holder, at, idleMs = 0) {
+  if (!paths.length || sq.state !== 'open') return
+  try {
+    const live = (await liveClaims(store, q, at, idleMs)).filter((c) => c.line === sq.line)
+    let mine = live.filter((c) => c.square_id === sq.id).length
+    for (const p of new Set(paths)) {
+      if (/[*?]/.test(p) || p.length > MAX_PATTERN) continue
+      const covering = live.filter((c) => globMatcher(c.pattern)(p))
+      const own = covering.find((c) => c.auto && c.square_id === sq.id && c.pattern === p)
+      if (own) {
+        await store.deleteClaim({ quilt_id: q, id: own.id })
+        await store.createClaim({ quilt_id: q, id: uuidv7(at), square_id: sq.id, pattern: p, holder: own.holder, note: own.note || '', at, auto: true })
+        continue
+      }
+      if (covering.length || mine >= MAX_CLAIMS) continue
+      await store.createClaim({ quilt_id: q, id: uuidv7(at), square_id: sq.id, pattern: p, holder, note: '', at, auto: true })
+      mine++
+    }
+  } catch {}
+}
+
+/** 06 "Owner mode": the default owner paths, the costliest files to conflict in. */
+export const OWNER_PATHS_DEFAULT = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'Cargo.lock', 'go.sum', 'supabase/migrations/**']
+/** An owner claim lets go this long after the last write under it from its square (owner_idle_hours' default). */
+export const OWNER_IDLE_MS = 2 * 3600_000
+/** A quilt's owner idle time: settings.owner_idle_hours (1..24) or the 2-hour default. */
+export const ownerIdleMsOf = (quilt) => Number.isInteger(quilt?.settings?.owner_idle_hours) ? quilt.settings.owner_idle_hours * 3600_000 : OWNER_IDLE_MS
+
+/** SEAM_OWNER_PATHS: unset is off, `default` the list above, else comma-separated patterns. */
+export function ownerPathsFrom (v) {
+  const s = String(v ?? '').trim()
+  if (!s) return []
+  if (s === 'default') return [...OWNER_PATHS_DEFAULT]
+  return s.split(',').map((x) => x.trim()).filter(Boolean).map(claimPattern)
+}
+
+/**
+ * After square `sq` wrote `paths` (SEAM_OWNER_PATHS): a write under an owner pattern claims the
+ * whole pattern for the square, `owner`, or refreshes the square's own owner claim on it. A pattern
+ * another square holds was already refused at the write. Best effort, like autoClaim.
+ */
+export async function ownerClaim (store, q, sq, paths, holder, at, idleMs = 0, ownerPaths = []) {
+  if (!paths.length || !ownerPaths.length || sq.state !== 'open') return
+  try {
+    const hit = ownerPaths.filter((o) => paths.some((p) => globMatcher(o)(p)))
+    if (!hit.length) return
+    const live = (await liveClaims(store, q, at, idleMs)).filter((c) => c.line === sq.line && c.square_id === sq.id)
+    for (const o of hit) {
+      const own = live.find((c) => c.pattern === o)
+      if (own && !own.owner) continue // claimed on purpose: it holds until the square ends
+      if (own) await store.deleteClaim({ quilt_id: q, id: own.id })
+      else if (live.length >= MAX_CLAIMS) continue
+      await store.createClaim({ quilt_id: q, id: uuidv7(at), square_id: sq.id, pattern: o, holder: own?.holder || holder, note: own?.note || '', at, owner: true })
+    }
+  } catch {}
+}
+
+/** Claims after a write: owner patterns first (they cover their paths), then auto-claims. */
+export async function claimWrites (store, q, sq, paths, holder, at, { idleMs = 0, auto = false, ownerPaths = [], unchanged = [] } = {}) {
+  // 06: a write that leaves an owner path as the square had it (an install that changed nothing) takes no owner claim.
+  if (ownerPaths.length) await ownerClaim(store, q, sq, paths.filter((p) => !unchanged.includes(p)), holder, at, idleMs, ownerPaths)
+  if (auto) await autoClaim(store, q, sq, paths, holder, at, idleMs)
+}
+
+/**
+ * Moves claim `c` to request `r`'s square and holder, re-points the rest of its queue at the new
+ * square in order, and writes the `claim_handoff` row the events job turns into claim.granted and
+ * claim.handoff. Used by a handoff and by the idle sweep (06 "Queues and idle release").
+ */
+export async function moveClaim (store, qid, c, r, note, actor, at, why = null) {
+  await store.deleteClaim({ quilt_id: qid, id: c.id })
+  const row = await store.createClaim({ quilt_id: qid, id: uuidv7(at), square_id: r.by_square, pattern: c.pattern, holder: r.by, note: note || c.note || '', at, ...(c.expires_at ? { expires_at: c.expires_at } : {}) })
+  await store.deleteClaimRequest({ quilt_id: qid, id: r.id })
+  for (const x of queueOf(await store.claimRequests(qid), c)) {
+    await store.deleteClaimRequest({ quilt_id: qid, id: x.id })
+    if (x.by_square !== r.by_square) await store.addClaimRequest({ ...x, square_id: r.by_square })
+  }
+  await store.setSquare({ square_id: r.by_square, op: 'claim_handoff', patch: {}, log: { pattern: c.pattern, from: c.holder, from_square: c.square_id, to: r.by, note: note || c.note || '', ...(why ? { why } : {}) }, actor, at }).catch(() => {})
+  return row
+}
+
+/**
+ * 06 owner mode: an owner claim lets go once its square no longer changes anything under the
+ * pattern (`changed`: the paths that differ between the square's base and its new head, after a
+ * revert or a restore). The first waiter gets it (claim.granted, why settled); with nobody waiting
+ * it is released.
+ */
+export async function releaseSettled (store, q, sq, changed, at) {
+  const mine = (await store.claims(q)).filter((c) => c.owner && c.square_id === sq.id)
+  for (const c of mine) {
+    const m = globMatcher(c.pattern)
+    if (changed.some((p) => m(p))) continue
+    const waiting = queueOf(await store.claimRequests(q), c)
+    if (waiting.length) await moveClaim(store, q, c, waiting[0], '', 'system', at, 'settled')
+    else await store.deleteClaim({ quilt_id: q, id: c.id })
+  }
+}
+
+/** When square `sq` (open) last moved for claim `c`: its last change, its live work, or the claim itself. */
+export async function claimActiveAt (store, qid, sq, c) {
+  return Math.max(sq.updated_at || 0, sq.opened_at || 0, (await store.getLive(qid, sq.id))?.at || 0, c.at || 0)
+}
+
+/**
+ * The claims that still hold at `at`: those of open squares not past their `expires_at`. With
+ * `idleMs` (06 "Queues and idle release", SEAM_CLAIM_IDLE_MINUTES) a claim whose square has seen
+ * nothing for that long (no commit or other change to the square, no live work, the claim itself
+ * not newer) has let go.
+ */
+export async function liveClaims (store, q, at = Date.now(), idleMs = 0) {
+  const rows = await store.claims(q)
+  if (!rows.length) return []
+  const squares = new Map()
+  const active = new Map()
+  const out = []
+  let ownerIdleMs = null
+  for (const c of rows) {
+    if (c.owner && ownerIdleMs === null) ownerIdleMs = ownerIdleMsOf(await store.getQuilt(q))
+    if (!squares.has(c.square_id)) squares.set(c.square_id, await store.getSquare(c.square_id))
+    const sq = squares.get(c.square_id)
+    if (!sq || !ACTIVE.has(sq.state) || c.expires_at <= at) continue
+    if (c.auto && (c.at || 0) + AUTO_CLAIM_QUIET_MS <= at) continue
+    if (c.owner && (c.at || 0) + ownerIdleMs <= at) continue
+    if (idleMs > 0 && sq.state === 'open') {
+      if (!active.has(sq.id)) active.set(sq.id, Math.max(sq.updated_at || 0, sq.opened_at || 0, (await store.getLive(q, sq.id))?.at || 0))
+      if (Math.max(active.get(sq.id), c.at || 0) + idleMs <= at) continue
+    }
+    out.push({ ...c, line: sq.line })
+  }
+  return out
+}
+
+/**
+ * Refuses a write to `paths` from square `sq` when another open square on its line claims one.
+ * Given the `writer` (a commit, not live work, which repeats), the refusal is also written to the
+ * square's log so the writer hears claim.refused (12) wherever it reads events.
+ */
+export async function guardClaims (store, q, sq, paths, at = Date.now(), idleMs = 0, writer = null) {
+  if (!paths.length) return
+  // A stacked square writes under its parents' claims (06): it builds on their work.
+  const mine = new Set([sq.id])
+  for (let p = sq; p.parent_square && mine.size <= 10;) { mine.add(p.parent_square); p = await store.getSquare(p.parent_square); if (!p) break }
+  const others = (await liveClaims(store, q, at, idleMs)).filter((c) => !mine.has(c.square_id) && c.line === sq.line)
+  for (const c of others) {
+    const m = globMatcher(c.pattern)
+    const hit = paths.find((p) => m(p))
+    if (hit) {
+      if (writer) {
+        const pos = queueOf(await store.claimRequests(q), c).findIndex((r) => r.by_square === sq.id)
+        await store.setSquare({ square_id: sq.id, op: 'claim_refused', patch: {}, log: { path: hit, claim: c.id, pattern: c.pattern, holder: c.holder, holder_square: c.square_id, note: c.note || '', queue_position: pos < 0 ? null : pos + 1 }, actor: writer, at }).catch(() => {})
+      }
+      throw new QuiltError(412, 'claim_refused', `${hit} is claimed by ${c.holder} in ${squareShort(c.square_id)}${c.note ? ` (${c.note})` : ''}: wait for it, ask them to hand it over, or work on other files`,
+        { path: hit, claim: view(c) })
+    }
+  }
+}
+
+/**
+ * 06's `claims_overlap` for square `sq`: the claims that hold on its line, held by other squares
+ * (not its own stack's parents, whose claims it writes under), that cover a path it changed
+ * (`changed`) or overlap a pattern it claims. Each with holder, task and the paths it covers.
+ */
+export async function claimsOverlap (store, q, sq, changed = [], at = Date.now(), idleMs = 0) {
+  if (!['open', 'merging'].includes(sq.state)) return []
+  const mine = new Set([sq.id])
+  for (let p = sq; p.parent_square && mine.size <= 10;) { mine.add(p.parent_square); p = await store.getSquare(p.parent_square); if (!p) break }
+  const live = await liveClaims(store, q, at, idleMs)
+  const held = live.filter((c) => c.square_id === sq.id).map((c) => c.pattern)
+  const out = []
+  for (const c of live) {
+    if (mine.has(c.square_id) || c.line !== sq.line) continue
+    const m = globMatcher(c.pattern)
+    const paths = changed.filter((p) => m(p))
+    const patterns = held.filter((h) => patternsOverlap(h, c.pattern, changed))
+    if (!paths.length && !patterns.length) continue
+    const holderSq = await store.getSquare(c.square_id)
+    out.push({ ...view(c), ...(holderSq?.task_id ? { task_id: holderSq.task_id } : {}), paths: paths.slice(0, 50), ...(patterns.length ? { your_claims: patterns } : {}) })
+  }
+  return out.sort((a, b) => a.at - b.at)
+}
+
+const view = (c) => ({ id: c.id, pattern: c.pattern, square: squareShort(c.square_id), square_id: c.square_id, line: c.line, holder: c.holder, note: c.note || '', at: c.at, ...(c.auto ? { auto: true } : {}), ...(c.owner ? { owner: true } : {}), ...(c.expires_at ? { expires_at: c.expires_at } : {}) })
+
+// A claim made with `expires_in` (seconds) lets go by itself then (06 `expires_at`): from a minute to a week.
+const MIN_EXPIRY = 60
+const MAX_EXPIRY = 7 * 24 * 3600
+function expiresIn (v) {
+  if (v === undefined || v === null || v === '') return 0
+  const n = Number(v)
+  if (!Number.isInteger(n) || n < MIN_EXPIRY || n > MAX_EXPIRY) throw new QuiltError(400, 'bad_request', `expires_in is whole seconds from ${MIN_EXPIRY} to ${MAX_EXPIRY} (a week)`)
+  return n
+}
+
+// 06 "Reuse": today's claim-request limits.
+export const MAX_QUEUE = 20
+export const MAX_REQUEST_TITLE = 120
+export const MAX_REQUEST_TEXT = 300
+export const MAX_HANDOFF_TEXT = 2000
+
+const requestView = (r) => ({ id: r.id, by: r.by, square: squareShort(r.by_square), square_id: r.by_square, title: r.title, description: r.description || '', at: r.at })
+const queueOf = (requests, c) => requests.filter((r) => r.square_id === c.square_id && r.pattern === c.pattern)
+
+export function claimOps (svc) {
+  const { store, now, quiltFor, squareByRef, writable, entriesOf, snapshot, fromStore, claimIdleMs, memberName } = svc.internals
+  // TODO 0.6: a claim names its holder by name too (holder_name), the id staying in holder.
+  const named = async (v) => { const n = memberName ? await memberName(v.holder) : null; return n ? { ...v, holder_name: n } : v }
+
+  /** GET /claims[?square=]: the claims that hold now, oldest first. */
+  async function claims (me, ref, { square } = {}) {
+    const q = await quiltFor(me, ref, 'read')
+    let rows = await liveClaims(store, q.id, now(), claimIdleMs)
+    if (square) { const sq = await squareByRef(q.id, square); rows = rows.filter((c) => c.square_id === sq.id) }
+    const requests = await store.claimRequests(q.id)
+    return { claims_version: await store.claimsVersion(q.id), claims: await Promise.all(rows.sort((a, b) => a.at - b.at).map((c) => { const queue = queueOf(requests, c); return named({ ...view(c), ...(queue.length ? { queue: queue.map(requestView) } : {}) }) })) }
+  }
+
+  /** POST /squares/:id/claims { pattern, note? }: claims paths for the square. */
+  async function claim (me, ref, sqRef, body = {}) {
+    const q = await quiltFor(me, ref, 'write')
+    const sq = await writable(me, q, sqRef)
+    if (sq.state !== 'open') throw new QuiltError(409, 'square_closed', `the square is ${sq.state}`)
+    const pattern = claimPattern(body.pattern)
+    const note = String(body.note || '')
+    if (note.length > MAX_NOTE) throw new QuiltError(400, 'bad_request', `a claim's note is up to ${MAX_NOTE} characters`)
+    const ttl = expiresIn(body.expires_in)
+    const at = now()
+    const all = await liveClaims(store, q.id, at, claimIdleMs)
+    const mine = all.filter((c) => c.square_id === sq.id)
+    const same = mine.find((c) => c.pattern === pattern)
+    if (same && !same.auto) return view(same)
+    if (mine.length >= MAX_CLAIMS) throw new QuiltError(400, 'bad_request', `a square holds up to ${MAX_CLAIMS} claims`)
+    const others = all.filter((c) => c.square_id !== sq.id && c.line === sq.line)
+    if (others.length) {
+      const tip = (await store.getLine(q.id, sq.line))?.tip || sq.base
+      const paths = tip ? (await entriesOf(q.id, await snapshot(q.id, tip))).map((e) => e.path) : []
+      const taken = others.find((c) => patternsOverlap(c.pattern, pattern, paths))
+      if (taken) throw new QuiltError(409, 'claim_taken', `${taken.pattern} is already claimed by ${(memberName && await memberName(taken.holder)) || taken.holder} in ${squareShort(taken.square_id)}${taken.note ? ` (${taken.note})` : ''}`, { claim: view(taken) })
+    }
+    try {
+      // A lapsed claim of this square's is a dead row: clear them so unclaim by pattern finds the live one.
+      // Claiming on purpose a path the square holds by an auto-claim makes it a claim made on purpose.
+      if (same) await store.deleteClaim({ quilt_id: q.id, id: same.id })
+      for (const x of await store.claims(q.id)) if (x.square_id === sq.id && x.expires_at <= at) await store.deleteClaim({ quilt_id: q.id, id: x.id })
+      const row = await store.createClaim({ quilt_id: q.id, id: uuidv7(at), square_id: sq.id, pattern, holder: me.member_id, note, at, ...(ttl ? { expires_at: at + ttl * 1000 } : {}) })
+      return view({ ...row, line: sq.line })
+    } catch (err) { throw fromStore(err) }
+  }
+
+  /** DELETE /squares/:id/claims/:claim (its id or its pattern): lets go of a claim. */
+  async function unclaim (me, ref, sqRef, which) {
+    const q = await quiltFor(me, ref, 'write')
+    const sq = await writable(me, q, sqRef)
+    const key = String(which || '').trim().replace(/^\.\//, '')
+    const c = (await store.claims(q.id)).find((x) => x.square_id === sq.id && (x.id === key || x.pattern === key))
+    if (!c) throw new QuiltError(404, 'not_found', `${squareShort(sq.id)} has no claim ${key}`)
+    const waiting = queueOf(await store.claimRequests(q.id), c)
+    if (waiting.length) throw new QuiltError(409, 'claim_queued', `${waiting.length} waiting for ${c.pattern} (first: ${waiting[0].by}, "${waiting[0].title}"): hand it over with seam claim handoff ${c.pattern} and a note instead`, { queue: waiting.map(requestView) })
+    try { await store.deleteClaim({ quilt_id: q.id, id: c.id }) } catch (err) { throw fromStore(err) }
+    return { ok: true, released: view({ ...c, line: sq.line }) }
+  }
+
+  /** A live claim on square `sq` by id or pattern, or 404. */
+  async function heldClaim (q, sq, which) {
+    const key = String(which || '').trim().replace(/^\.\//, '')
+    const c = (await liveClaims(store, q.id, now(), claimIdleMs)).find((x) => x.square_id === sq.id && (x.id === key || x.pattern === key))
+    if (!c) throw new QuiltError(404, 'not_found', `${squareShort(sq.id)} holds no claim ${key}`)
+    return c
+  }
+
+  /** POST /claims/requests { claim (id or pattern), square, title, description? }: waits in a claim's queue. */
+  async function requestClaim (me, ref, body = {}) {
+    const q = await quiltFor(me, ref, 'write')
+    const mine = await writable(me, q, body.square)
+    const title = String(body.title || '').trim()
+    const description = String(body.description || '')
+    if (!title || title.length > MAX_REQUEST_TITLE) throw new QuiltError(400, 'bad_request', `a request has a title of 1 to ${MAX_REQUEST_TITLE} characters: what you need the files for`)
+    if (description.length > MAX_REQUEST_TEXT) throw new QuiltError(400, 'bad_request', `a request's description is up to ${MAX_REQUEST_TEXT} characters`)
+    const key = String(body.claim || '').trim().replace(/^\.\//, '')
+    const c = (await liveClaims(store, q.id, now(), claimIdleMs)).find((x) => x.line === mine.line && (x.id === key || x.pattern === key) && x.square_id !== mine.id)
+    if (!c) throw new QuiltError(400, 'bad_request', `no other square on ${mine.line} holds a claim ${key}`)
+    const queue = queueOf(await store.claimRequests(q.id), c)
+    const already = queue.find((r) => r.by_square === mine.id)
+    if (already) return requestView(already)
+    if (queue.length >= MAX_QUEUE) throw new QuiltError(409, 'queue_full', `${MAX_QUEUE} already wait for ${c.pattern}`)
+    try {
+      const at = now()
+      return requestView(await store.addClaimRequest({ quilt_id: q.id, id: uuidv7(at), square_id: c.square_id, pattern: c.pattern, by: me.member_id, by_square: mine.id, title, description, at }))
+    } catch (err) { throw fromStore(err) }
+  }
+
+  /** DELETE /claims/requests/:id: takes your request out of the queue. */
+  async function withdrawRequest (me, ref, id) {
+    const q = await quiltFor(me, ref, 'write')
+    const r = (await store.claimRequests(q.id)).find((x) => x.id === id && x.by === me.member_id)
+    if (!r) throw new QuiltError(404, 'not_found', `you have no request ${id}`)
+    try { await store.deleteClaimRequest({ quilt_id: q.id, id: r.id }) } catch (err) { throw fromStore(err) }
+    return { ok: true, withdrawn: requestView(r) }
+  }
+
+  /** POST /squares/:id/claims/handoff { claim, to? (request id), note? }: gives the claim to the first in its queue (or `to`). */
+  async function handoffClaim (me, ref, sqRef, body = {}) {
+    const q = await quiltFor(me, ref, 'write')
+    const sq = await writable(me, q, sqRef)
+    const note = String(body.note || '')
+    if (note.length > MAX_HANDOFF_TEXT) throw new QuiltError(400, 'bad_request', `a handoff note is up to ${MAX_HANDOFF_TEXT} characters`)
+    const c = await heldClaim(q, sq, body.claim)
+    const queue = []
+    for (const r of queueOf(await store.claimRequests(q.id), c)) if ((await store.getSquare(r.by_square))?.state === 'open') queue.push(r)
+    const r = body.to ? queue.find((x) => x.id === body.to) : queue[0]
+    if (!r) throw new QuiltError(409, 'no_request', body.to ? `no open request ${body.to} waits for ${c.pattern}` : `nobody waits for ${c.pattern}`)
+    try {
+      const row = await moveClaim(store, q.id, c, r, note, me.member_id, now())
+      return { claim: view({ ...row, line: c.line }), request: requestView(r), from: { square: squareShort(sq.id), holder: c.holder } }
+    } catch (err) { throw fromStore(err) }
+  }
+
+  /**
+   * POST /squares/:id/claims/finish: the writer says it is finished (06 "Auto-claims following
+   * edits"). Lets go of the square's auto-claims now instead of after 10 quiet minutes; one someone
+   * waits for goes to the first open square in its queue. Claims made on purpose stay.
+   */
+  async function finishClaims (me, ref, sqRef, body = {}) {
+    const q = await quiltFor(me, ref, 'write')
+    const sq = await writable(me, q, sqRef)
+    const note = String(body.note || '')
+    if (note.length > MAX_HANDOFF_TEXT) throw new QuiltError(400, 'bad_request', `a handoff note is up to ${MAX_HANDOFF_TEXT} characters`)
+    const auto = (await liveClaims(store, q.id, now(), claimIdleMs)).filter((c) => c.square_id === sq.id && c.auto).sort((a, b) => a.at - b.at)
+    const released = []
+    const handed = []
+    for (const c of auto) {
+      try { handed.push(await handoffClaim(me, ref, sq.id, { claim: c.id, ...(note ? { note } : {}) })); continue } catch (err) { if (err.code !== 'no_request') throw err }
+      try { await store.deleteClaim({ quilt_id: q.id, id: c.id }) } catch (err) { throw fromStore(err) }
+      released.push(view(c))
+    }
+    return { ok: true, released, handed }
+  }
+
+  return { claims, claim, unclaim, requestClaim, withdrawRequest, handoffClaim, finishClaims }
+}