heyquilt 0.3.122 → 0.3.140

package/src/quilts/service.js

@@ -1,963 +0,0 @@
-// The server of Quilt source control (plans/quilt-source-control/04): every commit, merge,
-// diff, blame and history query runs here, behind one API that the CLI, both MCPs and plain
-// HTTP share. It holds no state of its own: rows are in the store (store-memory.js, or
-// Postgres through the migration's functions), bytes in packs (objects.js).
-//
-// A caller (`me`) is { member_id: 'person:<id>' | 'agent:<id>' | 'token:<id>', kind: 'person' | 'agent', name, tool? }
-// (a quilt token, tokens.js, calls as an agent and is a member of its one quilt).
-import { uuidv7 } from './ids.js'
-import { buildPack, readEntry, verifyPack, KIND } from './pack.js'
-import { cleanCommit, cleanChanges, commitBytes, commitId, blobId, cleanPath, cleanPrefix, under, termBytes, termId, decodeTerm, decodeCommit } from './records.js'
-import { buildTree, updateTree, TreeReader, EMPTY_TREE } from './tree.js'
-import { isText, unified, lineStat } from './textdiff.js'
-import { idOf, isId, keyOf, shardOf } from './hash.js'
-import { StoreError } from './store-memory.js'
-import { guardClaims } from './claims.js'
-import { remember } from './resolutions.js'
-import { QuiltError, squareShort } from './errors.js'
-
-export { QuiltError, squareShort }
-
-const LEVELS = { read: 1, write: 2, admin: 3 }
-const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/
-const IDEM_MS = 24 * 60 * 60 * 1000
-/** sq:<id>:live, a square's shared uncommitted work (02). */
-const LIVE = /^sq:[^:~^]+:live$/
-const MAX_ATTEMPTS = 5
-
-export const MAX_STACK = 10
-
-export const shortId = (id, n = 12) => (id ? id.slice(0, n) : null)
-
-const statusOf = {
-  not_found: 404, head_moved: 409, tip_moved: 409, square_merging: 409, square_closed: 409, holder_moved: 409, square_state: 409, exists: 409, slug_taken: 409,
-  conflict: 422, line_frozen: 423, line_exists: 409, tag_exists: 409, claim_refused: 412, claim_taken: 409, policy: 428, own_square: 403, parent_open: 409, bad_parent: 422, bad_request: 400, forbidden: 403, not_holder: 403, too_many_files: 422, pack_corrupt: 422, key_exists: 409, moved: 409, too_many_agents: 409, not_claimable: 403
-}
-
-/** A store error as a QuiltError with its wire status. */
-function fromStore (err) {
-  if (err instanceof QuiltError) return err
-  if (err instanceof StoreError || err?.code in statusOf) {
-    const { code, message, ...extra } = err
-    return new QuiltError(statusOf[err.code] || 500, err.code, message, extra)
-  }
-  return err
-}
-
-export function createQuiltService ({ store, objects, now = Date.now }) {
-  // Immutable objects are cached by id, forever (decision 30): bytes never change under an id.
-  const objCache = new Map()
-  const cacheObj = (id, bytes) => {
-    objCache.set(id, bytes)
-    if (objCache.size > 5000) objCache.delete(objCache.keys().next().value)
-  }
-  const entriesCache = new Map() // tree root → sorted entries
-  const readers = new Map() // quilt id → TreeReader
-
-  // ---- access ----
-
-  async function quiltFor (me, ref, need = 'read') {
-    const q = await findQuilt(me, ref)
-    const level = await store.memberLevel(q.id, me.member_id)
-    if (!level) throw new QuiltError(404, 'not_found', 'no such quilt')
-    if (LEVELS[level] < LEVELS[need]) throw new QuiltError(403, 'forbidden', `you need ${need} on this quilt`)
-    return { ...q, level }
-  }
-
-  async function findQuilt (me, ref) {
-    const s = String(ref || '')
-    const byId = /^[0-9a-f-]{36}$/i.test(s) ? await store.getQuilt(s) : null
-    let q = byId || await store.quiltBySlug(me.member_id, s)
-    if (!q) {
-      // A quilt someone else owns, by its slug, when only one of the caller's quilts has it.
-      const mine = (await store.quiltsFor(me.member_id)).filter((x) => x.slug === s)
-      if (mine.length > 1) throw new QuiltError(400, 'bad_request', `${s} names ${mine.length} of your quilts; use its id`)
-      q = mine[0] || null
-    }
-    if (!q) throw new QuiltError(404, 'not_found', 'no such quilt')
-    return q
-  }
-
-  // ---- objects ----
-
-  async function readObject (q, id, { blob = false } = {}) {
-    const hit = objCache.get(id)
-    if (hit) return hit
-    const row = blob ? await store.getBlob(q, id) : await store.getObject(q, id)
-    if (!row) throw new QuiltError(404, 'not_found', `no object ${id.slice(0, 12)} in this quilt`)
-    // One more read when the store misses a pack it acked (read-after-write lag) or returns bytes
-    // that fail their checksum (15); a second failure is real and goes to the caller.
-    let bytes
-    for (let attempt = 1; ; attempt++) {
-      try {
-        bytes = readEntry({ kind: row.kind, id, flags: row.flags }, await objects.readPack(q, row.pack_id, row.offset, row.len))
-        break
-      } catch (err) {
-        if (attempt > 1 || !(err.code === 'pack_corrupt' || err.code === 'not_found' || err.status === 404)) throw err
-      }
-    }
-    cacheObj(id, bytes)
-    return bytes
-  }
-  const readBlob = (q, id) => readObject(q, id, { blob: true })
-
-  /**
-   * Seals objects into one server pack (03: before any row names them) and writes their rows.
-   * Objects already in the quilt are left out; nothing is written when none are new.
-   */
-  async function seal (q, list, { origin = 'server', by = 'system' } = {}) {
-    const uniq = [...new Map(list.map((o) => [o.id, o])).values()]
-    const blobIds = uniq.filter((o) => o.kind === 'blob').map((o) => o.id)
-    const have = new Set([...(blobIds.length ? await store.hasBlobs(q, blobIds) : []), ...(await hasObjects(q, uniq.filter((o) => o.kind !== 'blob').map((o) => o.id)))])
-    const fresh = uniq.filter((o) => !have.has(o.id))
-    if (!fresh.length) return null
-    const pack = buildPack(fresh)
-    await objects.putPack(q, pack.id, pack.bytes)
-    await sealRows(q, pack, fresh.map((o) => o.bytes.length), origin, by)
-    for (const o of fresh) cacheObj(o.id, Buffer.from(o.bytes))
-    return pack.id
-  }
-
-  async function hasObjects (q, ids) {
-    if (!ids.length) return []
-    if (store.hasObjects) return store.hasObjects(q, ids)
-    const out = []
-    for (const id of ids) if (await store.getObject(q, id)) out.push(id)
-    return out
-  }
-
-  async function sealRows (q, pack, sizes, origin, by) {
-    const blobs = []; const objs = []
-    pack.index.forEach((e, i) => {
-      const row = { id: e.id, kind: e.kind, offset: e.offset, len: e.len, flags: e.flags, size: sizes[i] }
-      if (e.kind === 'blob') blobs.push(row); else objs.push(row)
-    })
-    await store.sealPack({ quilt_id: q, pack: { id: pack.id, size: pack.bytes.length, object_count: pack.index.length, origin, uploaded_by: by }, blobs, objects: objs, at: now() })
-  }
-
-  // ---- trees and snapshots ----
-
-  function reader (q) {
-    let r = readers.get(q)
-    if (!r) { r = new TreeReader((id) => readObject(q, id)); readers.set(q, r) }
-    return r
-  }
-
-  async function entriesOf (q, root) {
-    if (!root || root === EMPTY_TREE) return []
-    let e = entriesCache.get(root)
-    if (!e) {
-      e = await reader(q).entries(root)
-      entriesCache.set(root, e)
-      if (entriesCache.size > 64) entriesCache.delete(entriesCache.keys().next().value)
-    }
-    return e
-  }
-
-  /** Builds a tree from entries and returns { root, objects } with the nodes to seal. */
-  function treeObjects (entries) {
-    const { root, nodes } = buildTree(entries)
-    entriesCache.set(root, entries)
-    if (entriesCache.size > 64) entriesCache.delete(entriesCache.keys().next().value)
-    return { root, objects: [...nodes].map(([id, bytes]) => ({ kind: 'tree', id, bytes })) }
-  }
-
-  /**
-   * `grow(root, changes)` → { root, objects }: the tree with the changes applied, touching only
-   * the nodes they reach (tree.js updateTree). Nodes it made and has not sealed yet stay readable
-   * to the next call, so a chain of commits can be grown before one seal.
-   */
-  function treeGrower (q) {
-    const pending = new Map()
-    const r = new TreeReader(async (id) => pending.get(id) || readObject(q, id))
-    r.cache = reader(q).cache
-    return async (root, changes) => {
-      const { root: next, nodes } = await updateTree(r, root || EMPTY_TREE, changes)
-      const objects = []
-      for (const [id, bytes] of nodes) if (!pending.has(id)) { pending.set(id, bytes); objects.push({ kind: 'tree', id, bytes }) }
-      return { root: next, objects }
-    }
-  }
-
-  /**
-   * A commit's snapshot root (03: eager for lines, lazy for squares): derived from the nearest
-   * first-parent ancestor that has one plus the changes since, then stored.
-   */
-  async function snapshot (q, id) {
-    if (!id) return EMPTY_TREE
-    const chain = []
-    let c = await getCommit(q, id)
-    while (c && !c.snapshot_root) {
-      chain.push(c)
-      c = c.parents[0] ? await getCommit(q, c.parents[0]) : null
-    }
-    let root = c ? c.snapshot_root : EMPTY_TREE
-    if (!chain.length) return root
-    const toSeal = []
-    const roots = []
-    const grow = treeGrower(q)
-    for (const x of chain.reverse()) {
-      const t = await grow(root, x.changes)
-      toSeal.push(...t.objects)
-      roots.push([x.id, t.root])
-      root = t.root
-    }
-    await seal(q, toSeal)
-    for (const [cid, r] of roots) await store.setSnapshot({ quilt_id: q, commit_id: cid, root: r })
-    return root
-  }
-
-  /** The conflict terms in a commit's tree: a square may hold them, a line never (D10). */
-  // A commit never changes, so its terms are cached by id (the last 2,000 commits asked about).
-  const conflictCache = new Map()
-  async function conflictsAt (q, id) {
-    const key = `${q}:${id}`
-    if (conflictCache.has(key)) return conflictCache.get(key).map((e) => ({ ...e }))
-    const c = await getCommit(q, id)
-    const out = (!c.conflicted && !(await treeHasConflicts(q, c))) ? [] : (await entriesOf(q, await snapshot(q, id))).filter((e) => e.mode === 'conflict')
-    conflictCache.set(key, out)
-    if (conflictCache.size > 2000) conflictCache.delete(conflictCache.keys().next().value)
-    return out.map((e) => ({ ...e }))
-  }
-
-  // Whether any first-parent ancestor inside the square left a conflict that may still be in the
-  // tree. The walk stops at the head the square row last stored its conflicted paths for.
-  async function treeHasConflicts (q, c) {
-    const sq = c.square_id ? await store.getSquare(c.square_id) : null
-    let x = c
-    for (let i = 0; x && i < 10000; i++) {
-      if (x.conflicted) return true
-      if (sq?.conflicted_at && sq.conflicted_at === x.id) return (sq.conflicted_paths || []).length > 0
-      if (x.patch || !x.parents[0]) return false
-      const p = await store.getCommit(q, x.parents[0])
-      if (!p || p.square_id !== c.square_id) return false
-      x = p
-    }
-    return false
-  }
-
-  async function getCommit (q, id) {
-    const c = await store.getCommit(q, id)
-    if (!c) throw new QuiltError(404, 'not_found', `no commit ${String(id).slice(0, 12)}`)
-    return c
-  }
-
-  // ---- revisions (02's grammar) ----
-
-  async function squareByRef (q, ref) {
-    const s = String(ref || '').replace(/^sq:/, '')
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s)) {
-      const sq = await store.getSquare(s)
-      if (sq && sq.quilt_id === q) return sq
-      throw new QuiltError(404, 'not_found', 'no such square')
-    }
-    const tail = s.toLowerCase()
-    if (!/^[0-9a-f]{4,32}$/.test(tail)) throw new QuiltError(404, 'not_found', `no square ${ref}`)
-    const found = await store.squaresByTail(q, tail)
-    if (!found.length) throw new QuiltError(404, 'not_found', `no square ${ref}`)
-    if (found.length > 1) throw new QuiltError(400, 'bad_request', `${ref} names ${found.length} squares; give more of its id`)
-    return found[0]
-  }
-
-  /**
-   * A revision to a commit id, or null for an empty line or a square with nothing yet.
-   * Tokens: main, release/x, main~3, main:12, patch:12, sq:<tail>[:base|~n], <hex>, c:<hex>,
-   * git:<sha>, and <rev>^n.
-   */
-  async function resolve (q, token) {
-    let s = String(token || 'main').trim()
-    if (!s) s = 'main'
-    let caret = 0
-    const cm = s.match(/^(.*?)\^(\d*)$/)
-    if (LIVE.test(s)) throw new QuiltError(400, 'live_revision', `${s} is the square's uncommitted work, not a commit: read it with ls, cat or diff`)
-    if (cm && cm[1]) { s = cm[1]; caret = cm[2] === '' ? 1 : Number(cm[2]) }
-    let tilde = 0
-    const tm = s.match(/^(.*)~(\d+)$/)
-    if (tm) { s = tm[1]; tilde = Number(tm[2]) }
-    let id
-    let stopAt = null
-    if (/^\d+$/.test(s)) throw new QuiltError(400, 'bad_request', `say patch:${s} or c:${s}…`)
-    if (s.startsWith('sq:')) {
-      const base = s.endsWith(':base')
-      const sq = await squareByRef(q, base ? s.slice(0, -5) : s)
-      id = base ? sq.base : (sq.head || sq.base)
-      stopAt = sq.base
-    } else if (s.startsWith('tag:')) {
-      const tag = await store.getTag(q, s.slice(4))
-      if (!tag) throw new QuiltError(404, 'not_found', `no tag ${s.slice(4)}`)
-      id = tag.commit
-    } else if (s.startsWith('git:')) {
-      id = await store.gitSha(q, s.slice(4))
-      if (!id && store.gitShaPrefix) id = await store.gitShaPrefix(q, s.slice(4))
-      if (!id) throw new QuiltError(404, 'not_found', `no commit for git ${s.slice(4)}`)
-    } else if (/^(patch|[\w./-]+):\d+$/.test(s)) {
-      const [ln, n] = s.startsWith('patch:') ? ['main', Number(s.slice(6))] : [s.slice(0, s.lastIndexOf(':')), Number(s.slice(s.lastIndexOf(':') + 1))]
-      const row = await store.patch(q, ln, n)
-      if (!row) throw new QuiltError(404, 'not_found', `no patch ${n} on ${ln}`)
-      id = row.commit
-    } else if (/^c:[0-9a-f]+$/.test(s) || (/^[0-9a-f]{4,64}$/.test(s) && !(await store.getLine(q, s)))) {
-      id = await commitByPrefix(q, s.replace(/^c:/, ''))
-    } else {
-      const line = await store.getLine(q, s)
-      if (!line) throw new QuiltError(404, 'not_found', `no line or revision ${token}`)
-      id = line.tip
-    }
-    for (let i = 0; i < tilde && id; i++) {
-      if (stopAt && id === stopAt) break
-      const c = await getCommit(q, id)
-      id = c.parents[0] || null
-    }
-    if (caret) {
-      if (!id) throw new QuiltError(404, 'not_found', `${token} names nothing`)
-      const c = await getCommit(q, id)
-      id = c.parents[caret - 1]
-      if (!id) throw new QuiltError(404, 'not_found', `${token}: that commit has no parent ${caret}`)
-    }
-    return id || null
-  }
-
-  /**
-   * A revision's tree: { id, root }. sq:<id>:live is the square's head with its shared uncommitted
-   * changes laid over it (whole files: each put or delete replaces what the head has); every
-   * other revision is a commit's snapshot.
-   */
-  async function rootAt (q, token) {
-    const s = String(token || 'main').trim()
-    if (!LIVE.test(s)) { const id = await resolve(q, s); return { id, root: await snapshot(q, id) } }
-    const sq = await squareByRef(q, s.slice(0, -5))
-    const id = sq.head || sq.base
-    const root = await snapshot(q, id)
-    const live = store.getLive ? await store.getLive(q, sq.id) : null
-    if (!live || !live.changes.length) return { id, root }
-    const t = await treeGrower(q)(root, live.changes)
-    await seal(q, t.objects)
-    return { id, root: t.root, live: true }
-  }
-
-  async function commitByPrefix (q, prefix) {
-    if (isId(prefix)) { await getCommit(q, prefix); return prefix }
-    if (prefix.length < 4) throw new QuiltError(400, 'bad_request', 'give at least 4 hex characters of a commit id')
-    const found = await store.resolvePrefix(q, prefix)
-    if (!found.length) throw new QuiltError(404, 'not_found', `no commit ${prefix}`)
-    if (found.length > 1) throw new QuiltError(400, 'bad_request', `${prefix} names more than one commit; give more of it`)
-    return found[0]
-  }
-
-  // ---- describing ----
-
-  /** { on: 'sq:…' } while the square's parent (06) is open or merging; nothing once it merged. */
-  async function stackedOn (sq) {
-    if (!sq.parent_square || sq.state !== 'open') return {}
-    const p = await store.getSquare(sq.parent_square)
-    return p && (p.state === 'open' || p.state === 'merging') ? { on: squareShort(p.id) } : {}
-  }
-
-  async function squareView (sq) {
-    if (!sq) return null
-    let behind = 0
-    const line = await store.getLine(sq.quilt_id, sq.line)
-    if (sq.state === 'open' && line && line.tip !== sq.base) {
-      // behind_by: patches on the line since the square's base (06).
-      const at = sq.base ? (await store.getCommit(sq.quilt_id, sq.base))?.patch : null
-      behind = line.patch_count - (at && at.line === sq.line ? at.patch_no : 0)
-    }
-    const conflicted = (await conflictedPaths(sq)).length
-    return {
-      id: sq.id, short: squareShort(sq.id), title: sq.title, state: sq.state, line: sq.line,
-      base: sq.base, head: sq.head, holder: sq.holder, opened_by: sq.opened_by,
-      ...(sq.task_id ? { task_id: sq.task_id } : {}),
-      ...(await stackedOn(sq)),
-      writers: sq.writers || [], behind_by: behind, conflicted_paths: conflicted,
-      ...(sq.merged ? { merged: sq.merged } : {}), ...(sq.folded_into ? { folded_into: sq.folded_into } : {}),
-      opened_at: sq.opened_at, updated_at: sq.updated_at
-    }
-  }
-
-  /** A square's conflicted paths: from its row when stored for its head, else worked out and stored. */
-  async function conflictedPaths (sq) {
-    if (!sq.head) return []
-    if (sq.conflicted_at === sq.head && sq.conflicted_paths) return sq.conflicted_paths
-    const paths = (await conflictsAt(sq.quilt_id, sq.head)).map((e) => e.path)
-    await store.setConflicted({ square_id: sq.id, head: sq.head, paths })
-    return paths
-  }
-
-  function commitView (c, { changes = true } = {}) {
-    return {
-      id: c.id, short: shortId(c.id), seq: c.seq, square_id: c.square_id, square: squareShort(c.square_id),
-      parents: c.parents, ...(c.predecessor ? { predecessor: c.predecessor } : {}),
-      author: c.author, ...(c.on_behalf_of ? { on_behalf_of: c.on_behalf_of } : {}), ...(c.task_id ? { task_id: c.task_id } : {}),
-      message: c.message, authored_at: c.authored_at, at: c.at,
-      ...(c.patch ? { patch: c.patch } : {}), ...(c.hidden_seq ? { hidden: true } : {}),
-      conflicted: c.conflicted, stack: c.stack || {},
-      ...(changes ? { changes: c.changes } : { files: c.changes.length })
-    }
-  }
-
-  // ---- idempotency (04: (square_id, expect_head, op, body_hash), kept 24 h) ----
-
-  async function once (op, squareId, expectHead, body, fn) {
-    const key = keyOf('idempotency', Buffer.from(JSON.stringify([op, squareId, expectHead || null, body])))
-    const prior = await store.recall(key, IDEM_MS, now())
-    if (prior) return prior
-    const result = await fn()
-    await store.remember({ key, result, at: now() })
-    return result
-  }
-
-  // ---- quilts and members ----
-
-  async function createQuilt (me, { slug, name, import: importing = false }) {
-    if (me.token) throw new QuiltError(403, 'forbidden', 'a quilt token reaches its one quilt; it cannot make quilts')
-    const s = String(slug || '').toLowerCase()
-    if (!SLUG.test(s)) throw new QuiltError(400, 'bad_request', 'a quilt slug is lowercase letters, digits and dashes')
-    const id = uuidv7(now())
-    const quilt = { id, owner: me.member_id, slug: s, name: String(name || s).slice(0, 200), shard: shardOf(id), settings: { importing: !!importing } }
-    let row
-    try { row = await store.createQuilt({ quilt, at: now() }) } catch (err) { throw fromStore(err) }
-    // Ruling (2026-10-24): main starts at an empty root commit, so a line's tip is never empty.
-    // An imported quilt takes git's own root commit instead (its history stays git's).
-    if (!importing) await rootCommit(me, row)
-    return importing ? row : store.getQuilt(id)
-  }
-
-  /** Patch 0 of a new quilt: an empty root commit on main, in a merged square of its own. */
-  async function rootCommit (me, q) {
-    const at = now()
-    const square = { id: uuidv7(at), quilt_id: q.id, title: 'root', line: 'main', base: null, holder: me.member_id, opened_by: me.member_id, writers: [], import: true }
-    const c = cleanCommit({ quilt_id: q.id, square_id: square.id, parents: [], author: authorOf(me), message: 'Root', authored_at: at, changes: [] })
-    const id = commitId(c)
-    await seal(q.id, [{ kind: 'commit', id, bytes: commitBytes(c) }], { by: me.member_id })
-    try {
-      await store.openSquare({ square, at })
-      await store.stageFiles({ quilt_id: q.id, commit_id: id, files: [] })
-      await store.merge({ commit: { ...c, id, at }, line: 'main', expected_tip: null, expect_head: null, snapshot_root: EMPTY_TREE, actor: me.member_id, at, payload: { root: true }, import: true, root: true })
-      await store.fillLinePaths({ quilt_id: q.id })
-    } catch (err) { throw fromStore(err) }
-  }
-
-  async function addMember (me, ref, { member_id: m, level }) {
-    const q = await quiltFor(me, ref, 'admin')
-    if (level && !LEVELS[level]) throw new QuiltError(400, 'bad_request', 'level is read, write or admin')
-    if (!/^(person|agent|stub):\S+$/.test(String(m || ''))) throw new QuiltError(400, 'bad_request', 'member_id is person:<id> or agent:<id>')
-    return store.setMember({ quilt_id: q.id, member_id: m, level: level || null, actor: me.member_id, at: now() })
-  }
-
-  // ---- squares ----
-
-  async function openSquare (me, ref, { title, line = 'main', base, task_id: taskId, on } = {}) {
-    const q = await quiltFor(me, ref, 'write')
-    // Stacked (06): `on` another open square starts from its head, on its line, and merges after it.
-    let parent = null
-    if (on) {
-      if (base) throw new QuiltError(400, 'bad_request', 'give on (a square to stack on) or base, not both')
-      parent = await squareByRef(q.id, on)
-      if (parent.state !== 'open') throw new QuiltError(409, 'square_closed', `${squareShort(parent.id)} is ${parent.state}: stack on an open square`)
-      let depth = 1
-      for (let p = parent; p.parent_square; depth++) {
-        p = await store.getSquare(p.parent_square)
-        if (!p || (p.state !== 'open' && p.state !== 'merging')) break
-        if (depth >= MAX_STACK) throw new QuiltError(400, 'bad_request', `a stack is at most ${MAX_STACK} squares deep`)
-      }
-      line = parent.line
-    }
-    const ln = await store.getLine(q.id, line)
-    if (!ln) throw new QuiltError(404, 'not_found', `no line ${line}`)
-    const at = parent ? (parent.head || parent.base) : base ? await resolve(q.id, base) : ln.tip
-    const square = {
-      id: uuidv7(now()), quilt_id: q.id, title: String(title || 'untitled').slice(0, 200), line,
-      base: at, holder: me.member_id, opened_by: me.member_id, writers: [],
-      ...(parent ? { parent_square: parent.id } : {}),
-      ...(taskId ? { task_id: String(taskId), task_primary: true } : {})
-    }
-    try { return await squareView(await store.openSquare({ square, at: now() })) } catch (err) { throw fromStore(err) }
-  }
-
-  async function writable (me, q, sqRef) {
-    const sq = await squareByRef(q.id, sqRef)
-    if (sq.holder !== me.member_id && !(sq.writers || []).includes(me.member_id) && q.level !== 'admin') {
-      throw new QuiltError(403, 'not_holder', `this square is held by ${sq.holder}`, { holder: sq.holder })
-    }
-    return sq
-  }
-
-  // ---- commit ----
-
-  /**
-   * Seals changes as a commit in a square (D17). `changes`: [{ path, op: 'put', content
-   * (base64) | blob, mode? } | { path, op: 'delete' }]; blobs named by id must be in the quilt
-   * already (uploaded in a pack). `expect_head` is the head the caller saw (null before the
-   * square's first commit).
-   */
-  async function commit (me, ref, sqRef, body) {
-    const q = await quiltFor(me, ref, 'write')
-    const sq = await writable(me, q, sqRef)
-    const expect = body.expect_head === undefined ? sq.head : body.expect_head
-    return once('commit', sq.id, expect, body, async () => {
-      if (sq.state !== 'open') throw new QuiltError(409, sq.state === 'merging' ? 'square_merging' : 'square_closed', `the square is ${sq.state}`)
-      const parents = [expect || sq.base].filter(Boolean)
-      let c, id, resolved
-      if (body.commit) {
-        // 03: the client built the commit record and sealed it in its own pack with the blobs.
-        ;({ c, id, resolved } = await clientRecord(q, sq, me, parents, body.commit))
-        await guardClaims(store, q.id, sq, c.changes.map((x) => x.path))
-      } else {
-        const prep = await prepareChanges(q.id, sq, body.changes || [])
-        if (!prep.changes.length) throw new QuiltError(400, 'bad_request', 'nothing to commit')
-        resolved = prep.resolved
-        c = cleanCommit({
-          quilt_id: q.id, square_id: sq.id, parents, author: authorOf(me),
-          ...(me.on_behalf_of ? { on_behalf_of: me.on_behalf_of } : {}),
-          ...(sq.task_id ? { task_id: sq.task_id } : {}),
-          message: body.message || '', authored_at: body.authored_at || now(), changes: prep.changes, stack: body.stack
-        })
-        id = commitId(c)
-        await guardClaims(store, q.id, sq, c.changes.map((x) => x.path))
-        await seal(q.id, [...prep.blobs, { kind: 'commit', id, bytes: commitBytes(c) }], { by: me.member_id })
-      }
-      await store.stageFiles({ quilt_id: q.id, commit_id: id, files: c.changes })
-      try {
-        const row = await store.commit({ commit: { ...c, id, at: now() }, expect_head: expect || null, actor: me.member_id, at: now(), payload: resolved.length ? { resolved } : {} })
-        if (resolved.length) await rememberHand(q.id, resolved, c.changes, me)
-        return { ok: true, seq: row.seq, square: await squareView(await store.getSquare(sq.id)), result: commitView({ ...row, changes: c.changes }) }
-      } catch (err) { throw fromStore(err) }
-    })
-  }
-
-  /**
-   * Amends the square's last commit (04: POST /squares/:id/amend): a new commit with the same
-   * parents, the old one's changes with `changes` laid over them, and `message` (or the old
-   * message). The old commit becomes its predecessor and is hidden from the square's history.
-   */
-  async function amend (me, ref, sqRef, body = {}) {
-    const q = await quiltFor(me, ref, 'write')
-    const sq = await writable(me, q, sqRef)
-    const expect = body.expect_head === undefined ? sq.head : body.expect_head
-    return once('amend', sq.id, expect, body, async () => {
-      if (sq.state !== 'open') throw new QuiltError(409, sq.state === 'merging' ? 'square_merging' : 'square_closed', `the square is ${sq.state}`)
-      if ((sq.head || null) !== (expect || null)) throw new QuiltError(409, 'head_moved', 'the square moved on since you looked', { head: sq.head })
-      const old = sq.head ? await getCommit(q.id, sq.head) : null
-      if (!old || old.square_id !== sq.id || old.patch) throw new QuiltError(409, 'nothing_to_amend', 'the square has no commit of its own yet: commit instead')
-      const prep = await prepareChanges(q.id, sq, body.changes || [])
-      await guardClaims(store, q.id, sq, prep.changes.map((x) => x.path))
-      const parentRoot = await snapshot(q.id, old.parents[0] || null)
-      const byPath = new Map(old.changes.map((c) => [c.path, c]))
-      for (const ch of prep.changes) {
-        // A change that puts the file back as the parent had it drops out of the commit.
-        const was = await reader(q.id).lookup(parentRoot, ch.path)
-        const same = ch.op === 'delete' ? !was : (was && was.blob === ch.blob && was.mode === ch.mode)
-        if (same) byPath.delete(ch.path); else byPath.set(ch.path, ch)
-      }
-      if (!byPath.size) throw new QuiltError(400, 'bad_request', 'the amended commit would change nothing: to drop the commit, reset to sq:<id>~1 and commit that')
-      const c = cleanCommit({
-        quilt_id: q.id, square_id: sq.id, parents: old.parents, predecessor: old.id, author: authorOf(me),
-        ...(me.on_behalf_of ? { on_behalf_of: me.on_behalf_of } : {}),
-        ...(sq.task_id ? { task_id: sq.task_id } : {}),
-        message: body.message != null && body.message !== '' ? body.message : old.message, authored_at: now(), changes: [...byPath.values()], stack: old.stack
-      })
-      const id = commitId(c)
-      await seal(q.id, [...prep.blobs, { kind: 'commit', id, bytes: commitBytes(c) }], { by: me.member_id })
-      await store.stageFiles({ quilt_id: q.id, commit_id: id, files: c.changes })
-      try {
-        const row = await store.commit({ commit: { ...c, id, at: now() }, expect_head: old.id, actor: me.member_id, at: now(), payload: prep.resolved.length ? { resolved: prep.resolved, amend: true } : { amend: true } })
-        if (prep.resolved.length) await rememberHand(q.id, prep.resolved, c.changes, me)
-        return { ok: true, seq: row.seq, amended: old.id, square: await squareView(await store.getSquare(sq.id)), result: commitView({ ...row, changes: c.changes }) }
-      } catch (err) { throw fromStore(err) }
-    })
-  }
-
-  const authorOf = (me) => ({ member_id: me.member_id, kind: me.kind, name: me.name, ...(me.tool ? { tool: me.tool } : {}) })
-
-  /**
-   * A commit record the client sealed in its pack (03): read back, and accepted only when it is
-   * exactly the record the server would have written for this caller, square and head.
-   */
-  async function clientRecord (q, sq, me, parents, recordId) {
-    if (!isId(recordId)) throw new QuiltError(400, 'bad_request', 'commit is a commit record id')
-    if (!(await hasObjects(q.id, [recordId])).length) throw new QuiltError(422, 'pack_unsealed', `commit record ${recordId.slice(0, 12)} is not uploaded`, { ids: [recordId] })
-    let c
-    try { c = cleanCommit(decodeCommit(await readObject(q.id, recordId))) } catch (err) { throw new QuiltError(422, 'record_mismatch', `commit record ${recordId.slice(0, 12)}: ${err.message}`) }
-    if (commitId(c) !== recordId) throw new QuiltError(422, 'record_mismatch', 'the object is not a canonical commit record')
-    const want = {
-      quilt_id: q.id, square_id: sq.id, parents, author: cleanCommit({ quilt_id: q.id, square_id: sq.id, author: authorOf(me) }).author,
-      on_behalf_of: me.on_behalf_of || undefined, task_id: sq.task_id || undefined, predecessor: undefined, conflicted: 0
-    }
-    for (const [k, v] of Object.entries(want)) {
-      if (JSON.stringify(c[k]) !== JSON.stringify(v)) {
-        if (k === 'parents') throw new QuiltError(409, 'head_moved', 'the square moved on since you looked', { head: sq.head })
-        throw new QuiltError(422, 'record_mismatch', `commit record ${k} is not what this server records for you (${JSON.stringify(v ?? null)})`, { field: k })
-      }
-    }
-    if (!c.changes.length) throw new QuiltError(400, 'bad_request', 'nothing to commit')
-    const prep = await prepareChanges(q.id, sq, c.changes)
-    if (JSON.stringify(cleanChanges(prep.changes)) !== JSON.stringify(c.changes)) throw new QuiltError(422, 'record_mismatch', 'the record\'s changes are not what this server would record (a file still conflicted, or a size that differs): commit the changes instead', { field: 'changes' })
-    return { c, id: recordId, resolved: prep.resolved }
-  }
-
-  /** A conflict settled by hand is always remembered (07, D12): the committed file is the answer. */
-  async function rememberHand (q, resolved, changes, me) {
-    const byPath = new Map(changes.map((x) => [x.path, x]))
-    const picks = resolved.map((r) => { const x = byPath.get(r.path); return { ...r, pick: x && x.op === 'put' ? { blob: x.blob, mode: x.mode, size: x.size } : null } })
-    await remember(store, getTerm, q, picks, me, now())
-  }
-
-  /**
-   * Checks a commit's changes and turns inline contents into blobs. A path that holds a conflict
-   * term at the parent stays conflicted while its new content still carries the term's marker,
-   * and is recorded as resolved by hand once it does not (07).
-   */
-  async function prepareChanges (q, sq, list) {
-    const blobs = []
-    const out = []
-    const resolved = []
-    const terms = new Map()
-    // Every term still in the head's tree, also those an earlier commit of the square left.
-    if (sq.head) for (const e of await conflictsAt(q, sq.head)) terms.set(e.path, e.term)
-    for (const ch of list) {
-      const path = cleanPath(ch.path)
-      if (path.split('/')[0] === '.seam') throw new QuiltError(400, 'bad_request', '.seam/ is the block\'s own folder and is never committed')
-      if (ch.op === 'delete') { out.push({ path, op: 'delete' }); continue }
-      if (ch.op === 'conflict') { out.push(await importedTerm(q, path, ch, blobs)); continue }
-      if (ch.op !== 'put') throw new QuiltError(400, 'bad_request', `${path}: op is put or delete`)
-      let id = ch.blob
-      let size = ch.size
-      if (ch.content != null) {
-        const bytes = Buffer.from(String(ch.content), 'base64')
-        const term = terms.get(path)
-        if (term && bytes.includes(Buffer.from(`quilt-conflict ${term.slice(0, 12)}`))) continue // still conflicted: the term stays
-        if (term) resolved.push({ path, term, how: 'hand' })
-        id = blobId(bytes)
-        size = bytes.length
-        blobs.push({ kind: 'blob', id, bytes })
-      } else {
-        if (!isId(id)) throw new QuiltError(400, 'bad_request', `${path}: give content (base64) or a blob id`)
-        const row = await store.getBlob(q, id)
-        if (!row) throw new QuiltError(422, 'pack_unsealed', `${path}: blob ${id.slice(0, 12)} is not uploaded`, { ids: [id] })
-        size = row.size
-        const term = terms.get(path)
-        if (term && (await readBlob(q, id)).includes(Buffer.from(`quilt-conflict ${term.slice(0, 12)}`))) continue
-        if (term) resolved.push({ path, term, how: 'hand' })
-      }
-      let copyFrom
-      if (ch.copy_from) {
-        // 02 invariant 14: the copy_from commit had that path (one path lookup); a bad one is refused.
-        const from = cleanPath(ch.copy_from.path)
-        const at = ch.copy_from.commit ? await resolve(q, ch.copy_from.commit).catch(() => null) : null
-        if (!at || !(await reader(q).lookup(await snapshot(q, at), from))) throw new QuiltError(422, 'bad_copy_from', `${path}: copy_from ${from} is not in ${String(ch.copy_from.commit || '(no commit)').slice(0, 12)}`)
-        copyFrom = { path: from, commit: at }
-      }
-      out.push({ path, op: 'put', blob: id, mode: ch.mode || 'file', size, ...(copyFrom ? { copy_from: copyFrom } : {}) })
-    }
-    return { changes: out, blobs, resolved }
-  }
-
-  /**
-   * A conflict brought in from another system (16: an open merge of a session that became a
-   * quilt): `{ path, op: 'conflict', reason: 'import', base, ours, theirs }`, each side
-   * `{ content (base64), from_square?, from_commit?, by? }` or null for a side without the file.
-   * Writes a `content` term (`edit_vs_delete` when a side is gone) whose origin says it was
-   * imported; from then on it is a term like a merge's (07): materialised, settled by hand.
-   */
-  async function importedTerm (q, path, ch, blobs) {
-    if (ch.reason !== 'import') throw new QuiltError(400, 'bad_request', `${path}: a commit writes a conflict only with reason 'import'; merges make the others`)
-    if (!ch.ours && !ch.theirs) throw new QuiltError(400, 'bad_request', `${path}: a conflict needs at least one side with the file`)
-    const side = async (s, which) => {
-      if (s == null) return {}
-      if (typeof s !== 'object') throw new QuiltError(400, 'bad_request', `${path}: ${which} is { content } or null`)
-      const out = {}
-      if (s.content != null) {
-        const bytes = Buffer.from(String(s.content), 'base64')
-        out.blob = blobId(bytes)
-        out.mode = 'file'
-        blobs.push({ kind: 'blob', id: out.blob, bytes })
-      }
-      if (s.from_commit != null) {
-        if (!isId(s.from_commit) || !(await store.getCommit(q, s.from_commit))) throw new QuiltError(422, 'bad_request', `${path}: ${which}.from_commit is not a commit of this quilt`)
-        out.from_commit = s.from_commit
-      }
-      if (s.from_square != null) {
-        const sq = await store.getSquare(String(s.from_square))
-        if (!sq || sq.quilt_id !== q) throw new QuiltError(422, 'bad_request', `${path}: ${which}.from_square is not a square of this quilt`)
-        out.from_square = sq.id
-      }
-      if (s.by != null) out.by = String(s.by).slice(0, 200)
-      return out
-    }
-    const [base, ours, theirs] = [await side(ch.base, 'base'), await side(ch.ours, 'ours'), await side(ch.theirs, 'theirs')]
-    const term = { kind: ours.blob && theirs.blob ? 'content' : 'edit_vs_delete', adds: [ours, theirs], removes: [base], origin: { reason: 'import' } }
-    const id = termId(term)
-    blobs.push({ kind: 'term', id, bytes: termBytes(term) })
-    return { path, op: 'conflict', term: id }
-  }
-
-  // ---- uploads (04: have?, then one pack of what is missing) ----
-
-  async function have (me, ref, ids) {
-    const q = await quiltFor(me, ref, 'write')
-    const list = (ids || []).filter(isId).slice(0, 10000)
-    const present = new Set([...(await store.hasBlobs(q.id, list)), ...(await hasObjects(q.id, list))])
-    return { missing: list.filter((id) => !present.has(id)) }
-  }
-
-  /** A client's pack: verified entry by entry before any row is written (03, "Sealing a pack"). */
-  async function uploadPack (me, ref, bytes) {
-    const q = await quiltFor(me, ref, 'write')
-    let index
-    try { index = verifyPack(bytes).index } catch (err) { throw new QuiltError(422, 'pack_corrupt', err.message) }
-    const { id } = verifyPack(bytes)
-    const sizes = index.map((e) => readEntry(e, bytes.subarray(e.offset, e.offset + e.len)).length)
-    if (index.some((e) => !['blob', 'commit', 'tree', 'term'].includes(e.kind))) throw new QuiltError(422, 'pack_corrupt', 'this server takes blobs, commits, tree nodes and terms only')
-    await objects.putPack(q.id, id, bytes)
-    await sealRows(q.id, { id, bytes, index }, sizes, 'client', me.member_id)
-    return { pack: id, objects: index.length }
-  }
-
-  // ---- reads ----
-
-  async function quilts (me) { return (await store.quiltsFor(me.member_id)).map((q) => ({ id: q.id, slug: q.slug, name: q.name, owner: q.owner, level: q.level })) }
-
-  async function quiltInfo (me, ref) {
-    const q = await quiltFor(me, ref)
-    const lines = await store.lines(q.id)
-    return { id: q.id, slug: q.slug, name: q.name, owner: q.owner, level: q.level, head_seq: q.head_seq, lines: lines.map((l) => ({ name: l.name, tip: l.tip, patch_count: l.patch_count, frozen: l.frozen })), members: await store.members(q.id), stub_members: await store.stubMembers(q.id), you: { ...authorOf(me), ...(me.on_behalf_of ? { on_behalf_of: me.on_behalf_of } : {}) } }
-  }
-
-  async function squares (me, ref, filter = {}) {
-    const q = await quiltFor(me, ref)
-    const list = await store.squares(q.id, { state: filter.state, holder: filter.mine ? me.member_id : filter.holder, task: filter.task })
-    return Promise.all(list.map(squareView))
-  }
-
-  async function square (me, ref, sqRef) {
-    const q = await quiltFor(me, ref)
-    return squareView(await squareByRef(q.id, sqRef))
-  }
-
-  async function show (me, ref, rev, { format = 'unified', paths } = {}) {
-    const q = await quiltFor(me, ref)
-    const id = await resolve(q.id, rev)
-    if (!id) throw new QuiltError(404, 'not_found', `${rev || 'main'} has no commits yet`)
-    const c = await getCommit(q.id, id)
-    const out = { commit: commitView(c, { changes: true }), square: await squareView(await store.getSquare(c.square_id)) }
-    if (format !== 'none') {
-      const from = c.parents[0] || null
-      out.diff = await diffTrees(q.id, from, id, { format, paths })
-    }
-    return out
-  }
-
-  /**
-   * The patches on `line` at or below `upTo` (and above `stop`'s) that touched any of `prefixes`
-   * (a file's own rows, or a directory's 'dir/' rows), newest first: { ids, more }.
-   */
-  async function pathPatches (q, line, prefixes, upTo, stop, limit) {
-    let floor = 0
-    if (stop) { const s = await store.getCommit(q, stop); if (s && s.patch && s.patch.line === line) floor = s.patch.patch_no }
-    const rows = new Map()
-    for (const p of prefixes) {
-      const keys = p ? [p, p + '/'] : null
-      if (!keys) return { ids: (await store.patches(q, line, { after: floor, before: upTo + 1, limit })).map((r) => r.commit), more: false }
-      for (const key of keys) for (const r of await store.linePaths(q, line, key, { upTo, limit: limit + 1 })) if (r.patch_no > floor) rows.set(r.patch_no, r.commit_id)
-    }
-    const ns = [...rows.keys()].sort((a, b) => b - a)
-    return { ids: ns.slice(0, limit).map((n) => rows.get(n)), more: ns.length > limit }
-  }
-
-  /**
-   * Inside a square: the commits on `c`'s first-parent chain that are in `c`'s square (from its
-   * commit rows, no file rows), and `exit`, the first parent of the lowest of them (outside the
-   * square). `cache` keeps a square's rows across calls.
-   */
-  async function squareChain (q, c, cache = new Map()) {
-    let rows = cache.get(c.square_id)
-    if (!rows) { rows = new Map((await store.squareCommits(q, c.square_id)).map((r) => [r.id, r])); cache.set(c.square_id, rows) }
-    const chain = new Map()
-    let id = c.id
-    let exit = null
-    while (id && rows.has(id) && !chain.has(id)) { const r = rows.get(id); chain.set(id, r.seq); exit = r.parents[0] || null; id = exit }
-    if (id && !rows.has(id)) exit = id
-    return { chain, exit }
-  }
-
-  /**
-   * The commits on `c`'s chain inside its square that touched any of `prefixes`, newest first,
-   * from the square's file rows (commit_files) instead of a walk over its commits.
-   */
-  async function squarePathIds (q, c, prefixes, chain) {
-    const seqs = new Map()
-    for (const p of prefixes) {
-      if (!p) { for (const [id, seq] of chain) seqs.set(id, seq); continue }
-      for (const key of [p, p + '/']) {
-        for (const r of await store.squarePathCommits(q, c.square_id, key, { upTo: c.seq, limit: chain.size })) if (chain.has(r.commit_id)) seqs.set(r.commit_id, r.seq)
-      }
-    }
-    return [...seqs].sort((a, b) => b[1] - a[1]).map(([id]) => id)
-  }
-
-  async function log (me, ref, { rev = 'main', paths = [], limit = 20, all_squares: allSquares = false } = {}) {
-    const q = await quiltFor(me, ref)
-    const prefixes = (paths || []).map(cleanPrefix)
-    let range = String(rev || 'main')
-    let stop = null
-    if (range.includes('..')) {
-      const [a, b] = range.split('..')
-      stop = a ? await resolve(q.id, a) : null
-      range = b || 'main'
-    }
-    let id = await resolve(q.id, range)
-    const out = []
-    const max = Math.min(Number(limit) || 20, 1000)
-    let walked = 0
-    const chains = new Map()
-    while (id && id !== stop && out.length < max && walked < 100000) {
-      walked++
-      const c = await getCommit(q.id, id)
-      // On a line, the patches that touched the paths come from line_paths, not a walk.
-      if (prefixes.length && c.patch && c.patch.line) {
-        const more = await pathPatches(q.id, c.patch.line, prefixes, c.patch.patch_no, stop, max - out.length)
-        for (const cid of more.ids) out.push(commitView(await getCommit(q.id, cid), { changes: false }))
-        return { commits: out, more: more.more }
-      }
-      // Inside a square, the commits that touched the paths come from its file rows, not a walk.
-      if (prefixes.length && !c.patch) {
-        const { chain, exit } = await squareChain(q.id, c, chains)
-        const stopSeq = stop && chain.has(stop) ? chain.get(stop) : -1
-        for (const cid of await squarePathIds(q.id, c, prefixes, chain)) {
-          if (chain.get(cid) <= stopSeq) break
-          if (out.length >= max) return { commits: out, more: true }
-          out.push(commitView(await getCommit(q.id, cid), { changes: false }))
-        }
-        if (stopSeq >= 0) return { commits: out, more: false }
-        walked += chain.size
-        id = exit
-        continue
-      }
-      if (!prefixes.length || c.changes.some((ch) => prefixes.some((p) => under(ch.path, p)))) out.push(commitView(c, { changes: false }))
-      id = c.parents[0] || null
-    }
-    void allSquares
-    return { commits: out, more: !!id && id !== stop }
-  }
-
-  /** A line's patches, newest first, in one store read (the dashboard's history, numbers and people). */
-  async function linePatches (me, ref, line = 'main', { before, limit = 100 } = {}) {
-    const q = await quiltFor(me, ref)
-    const max = Math.min(Math.max(Number(limit) || 100, 1), 1000)
-    const rows = await store.linePatchesView(q.id, line, { before: Number(before) > 0 ? Number(before) : undefined, limit: max + 1 })
-    return { patches: rows.slice(0, max), more: rows.length > max }
-  }
-
-  /** The tree diff between two commits, with per-file text diffs in `format`. */
-  async function diffTrees (q, fromId, toId, opts) {
-    return diffRoots(q, await snapshot(q, fromId), await snapshot(q, toId), opts)
-  }
-
-  async function diffRoots (q, ra, rb, { format = 'unified', paths = [] } = {}) {
-    const prefixes = (paths || []).map(cleanPrefix)
-    const files = (await reader(q).diff(ra, rb)).filter((d) => !prefixes.length || prefixes.some((p) => under(d.path, p)))
-    return describeFileDiffs(q, files, format)
-  }
-
-  async function describeFileDiffs (q, files, format) {
-    const out = []
-    let add = 0; let del = 0
-    for (const d of files) {
-      const status = !d.before ? 'added' : !d.after ? 'deleted' : (d.after.mode === 'conflict' ? 'conflicted' : 'modified')
-      const f = { path: d.path, status, ...(d.before?.blob ? { before: d.before.blob } : {}), ...(d.after?.blob ? { after: d.after.blob } : {}) }
-      if (format === 'names') { out.push(f); continue }
-      const [a, b] = [d.before?.blob ? await readBlob(q, d.before.blob) : null, d.after?.blob ? await readBlob(q, d.after.blob) : null]
-      if (!isText(a) || !isText(b)) { f.binary = true; out.push(f); continue }
-      const [ta, tb] = [a ? a.toString('utf8') : null, b ? b.toString('utf8') : null]
-      const st = lineStat(ta || '', tb || '')
-      Object.assign(f, st)
-      add += st.add; del += st.del
-      if (format === 'unified') f.patch = d.after?.mode === 'conflict' ? `conflict in ${d.path} (term ${d.after.term.slice(0, 12)})\n` : unified(d.path, ta, tb)
-      out.push(f)
-    }
-    return { files: out, add, del }
-  }
-
-  async function diff (me, ref, { from, to, paths, format = 'unified' } = {}) {
-    const q = await quiltFor(me, ref)
-    const b = await rootAt(q.id, to || 'main')
-    let a
-    if (from) a = await rootAt(q.id, from)
-    else if (String(to || '').startsWith('sq:')) {
-      const sq = await squareByRef(q.id, String(to).split(/[~:^]/).slice(0, 2).join(':'))
-      // The square's live work against its head; any other square revision against its base.
-      const id = b.live || LIVE.test(String(to)) ? (sq.head || sq.base) : sq.base
-      a = { id, root: await snapshot(q.id, id) }
-    } else { const id = b.id ? (await getCommit(q.id, b.id)).parents[0] || null : null; a = { id, root: await snapshot(q.id, id) } }
-    return { from: a.id, to: b.id, ...(b.live ? { live: true } : {}), ...(await diffRoots(q.id, a.root, b.root, { format, paths })) }
-  }
-
-  /** The entries under `paths` at a revision (ls-tree; what a block checks out). */
-  async function tree (me, ref, rev, { paths = [''] } = {}) {
-    const q = await quiltFor(me, ref)
-    const { id, root } = await rootAt(q.id, rev)
-    const prefixes = (paths && paths.length ? paths : ['']).map(cleanPrefix)
-    return { commit: id, root, entries: await reader(q.id).list(root, prefixes) }
-  }
-
-  /** Blob contents by id, base64 (want-only fetch, decision 31). */
-  async function blobs (me, ref, ids) {
-    const q = await quiltFor(me, ref)
-    const out = {}
-    let total = 0
-    for (const id of (ids || []).slice(0, 2000)) {
-      if (!isId(id)) continue
-      const b = await readBlob(q.id, id)
-      total += b.length
-      out[id] = b.toString('base64')
-      if (total > 32 * 1024 * 1024) break
-    }
-    return { blobs: out }
-  }
-
-  /** A file at a revision (`cat`), with a conflict term materialised. */
-  async function cat (me, ref, rev, path, { format = 'diff' } = {}) {
-    const q = await quiltFor(me, ref)
-    const { root } = await rootAt(q.id, rev)
-    const e = await reader(q.id).lookup(root, cleanPath(path))
-    if (!e) throw new QuiltError(404, 'not_found', `${path} is not in ${rev || 'main'}`)
-    if (e.mode === 'conflict') return { path, conflict: true, term: e.term, content: Buffer.from(await materialise(q.id, e.term, format)).toString('base64') }
-    return { path, mode: e.mode, blob: e.blob, size: e.size, content: (await readBlob(q.id, e.blob)).toString('base64') }
-  }
-
-  async function getTerm (q, id) { return decodeTerm(await readObject(q, id)) }
-
-  /** A conflict term as text a person or agent can edit (07): `diff` (default), `snapshot` or `git`. */
-  async function materialise (q, termIdHex, format = 'diff') {
-    const t = await getTerm(q, termIdHex)
-    const side = async (s) => (s && s.blob ? (await readBlob(q, s.blob)).toString('utf8') : '')
-    const label = (s, which) => `${which} (${[s.by || 'someone', s.from_square && squareShort(s.from_square), s.from_commit && s.from_commit.slice(0, 8)].filter(Boolean).join(' · ')})`
-    const tag = `quilt-conflict ${termIdHex.slice(0, 12)}`
-    if (format === 'git' && t.adds.length > 2) throw new QuiltError(400, 'too_many_sides', `git markers hold two sides; this term has ${t.adds.length}: ask for format diff or snapshot`)
-    if (format === 'snapshot') {
-      const parts = [`<<<<<<< ${tag} ${t.kind}`]
-      for (let i = 0; i < t.adds.length; i++) parts.push(`+++++++ ${label(t.adds[i], `side ${i}`)}`, await side(t.adds[i]))
-      for (let i = 0; i < t.removes.length; i++) parts.push(`------- base ${i}`, await side(t.removes[i]))
-      parts.push(`>>>>>>> ${tag}`)
-      return parts.join('\n') + '\n'
-    }
-    if (format === 'diff') {
-      const { diffMarkers } = await import('./conflict-format.js')
-      const sides = await Promise.all(t.adds.map(async (s, i) => ({ text: s.blob ? await side(s) : null, label: label(s, i === 0 ? 'ours' : 'theirs'), by: s.by })))
-      return diffMarkers({ sides, bases: await Promise.all(t.removes.map(side)), tag, kind: t.kind })
-    }
-    const { gitMarkers } = await import('./conflict-format.js')
-    const sideOf = async (s, which) => ({ text: s.blob ? await side(s) : null, label: label(s, which), by: s.by })
-    return gitMarkers({ ours: await sideOf(t.adds[0], 'ours'), base: await side(t.removes[0]), theirs: await sideOf(t.adds[1], 'theirs'), tag })
-  }
-
-  return {
-    // used by the other modules (merge.js, blame.js, import)
-    internals: { rootAt, prepareChanges, pathPatches, squareChain, squarePathIds, conflictedPaths, store, objects, now, conflictsAt, quiltFor, squareByRef, resolve, getCommit, snapshot, entriesOf, treeObjects, treeGrower, reader, seal, readBlob, readObject, squareView, commitView, writable, once, getTerm, materialise, describeFileDiffs, fromStore },
-    createQuilt, addMember, quilts, quiltInfo,
-    openSquare, squares, square,
-    commit, amend, have, uploadPack,
-    show, log, linePatches, diff, tree, blobs, cat
-  }
-}
-
-export { KIND, termBytes, termId, decodeCommit, uuidv7 }