@heyquilt/seam 0.0.0-stage → 0.1.0

package/lib/quilts/ids.js

@@ -0,0 +1,12 @@
+// Ids shared by the quilt server and seam's client (the git import makes its squares' ids).
+import crypto from 'node:crypto'
+
+/** A UUIDv7: 48 bits of milliseconds, then random (README §3.3: time-sortable, never collides). */
+export function uuidv7 (ms = Date.now()) {
+  const b = crypto.randomBytes(16)
+  b.writeUIntBE(ms, 0, 6)
+  b[6] = (b[6] & 0x0f) | 0x70
+  b[8] = (b[8] & 0x3f) | 0x80
+  const h = b.toString('hex')
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`
+}

package/lib/quilts/import-git.js

@@ -0,0 +1,193 @@
+// The local driver of a git import (plans/quilt-source-control/14): walks a repository on this
+// machine with `git cat-file --batch`, hashes blobs with BLAKE3, uploads the missing ones in
+// packs with the commit records, and sends the commits in order. Every commit on HEAD's
+// first-parent chain becomes a patch on main with a square of its own; a merge commit's side
+// commits become the commits of the merge's square (14, "Which square owns each commit").
+import { spawn, execFileSync } from 'node:child_process'
+import { cleanCommit, commitId, commitBytes, blobId } from './records.js'
+import { uuidv7 } from './ids.js'
+
+const GIT_ENV = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' }
+const MODES = { 100644: 'file', 100755: 'exec', 120000: 'symlink', 100664: 'file' }
+
+/** A long-lived `git cat-file --batch`: get(sha) → { type, bytes }. */
+function catFile (repo) {
+  const p = spawn('git', ['-C', repo, 'cat-file', '--batch'], { env: GIT_ENV, stdio: ['pipe', 'pipe', 'inherit'] })
+  let buf = Buffer.alloc(0)
+  const waiting = []
+  const pump = () => {
+    while (waiting.length) {
+      const nl = buf.indexOf(10)
+      if (nl < 0) return
+      const head = buf.subarray(0, nl).toString()
+      const [sha, type, size] = head.split(' ')
+      if (type === 'missing') { buf = buf.subarray(nl + 1); waiting.shift().reject(new Error(`git object ${sha} is missing`)); continue }
+      const n = Number(size)
+      if (buf.length < nl + 1 + n + 1) return
+      const bytes = Buffer.from(buf.subarray(nl + 1, nl + 1 + n))
+      buf = buf.subarray(nl + 1 + n + 1)
+      waiting.shift().resolve({ type, bytes })
+    }
+  }
+  p.stdout.on('data', (d) => { buf = buf.length ? Buffer.concat([buf, d]) : d; pump() })
+  return {
+    get (sha) { return new Promise((resolve, reject) => { waiting.push({ resolve, reject }); p.stdin.write(sha + '\n') }) },
+    close () { p.stdin.end(); p.kill() }
+  }
+}
+
+/** A git commit object's fields. */
+function parseCommit (bytes) {
+  const s = bytes.toString('utf8')
+  const end = s.indexOf('\n\n')
+  const headers = s.slice(0, end < 0 ? s.length : end).split('\n')
+  const message = end < 0 ? '' : s.slice(end + 2)
+  const out = { parents: [], message }
+  for (const h of headers) {
+    if (h.startsWith('parent ')) out.parents.push(h.slice(7))
+    else if (h.startsWith('tree ')) out.tree = h.slice(5)
+    else if (h.startsWith('author ') || h.startsWith('committer ')) {
+      const m = h.match(/^(\w+) (.*) <([^>]*)> (\d+) ([+-]\d{4})$/)
+      if (m) out[m[1]] = { name: m[2], email: m[3], at: Number(m[4]) * 1000, tz: m[5] }
+    }
+  }
+  return out
+}
+
+function git (repo, args) {
+  return execFileSync('git', ['-C', repo, ...args], { env: GIT_ENV, maxBuffer: 1024 * 1024 * 1024 })
+}
+
+/** The changes of `sha` against its first parent: [{ path, mode, sha } | { path, delete }]. */
+function diffTree (repo, parent, sha) {
+  const out = git(repo, parent ? ['diff-tree', '-r', '--no-renames', '--no-commit-id', '-z', '--raw', parent, sha] : ['diff-tree', '-r', '--no-renames', '--no-commit-id', '-z', '--raw', '--root', sha])
+  const parts = out.toString('utf8').split('\0')
+  const changes = []
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const meta = parts[i]
+    if (!meta.startsWith(':')) { i--; continue }
+    const [, newMode, , newSha, status] = meta.slice(1).split(' ')
+    const path = parts[i + 1]
+    if (status === 'D') changes.push({ path, delete: true })
+    else changes.push({ path, gitMode: newMode, sha: newSha })
+  }
+  return changes
+}
+
+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 })
+
+/**
+ * Imports the history of HEAD in `repo` into a new quilt `slug`. Returns { quilt, slug,
+ * commits, patches, report, validated? }.
+ */
+export async function importGit (client, { repo, slug, batch = 100, log = () => {}, validate = false, limit = 0 }) {
+  const head = git(repo, ['rev-parse', 'HEAD']).toString().trim()
+  const all = git(repo, ['rev-list', head]).toString().split('\n').filter(Boolean)
+  const cat = catFile(repo)
+  const report = []
+  try {
+    // Parents and fields of every commit, read once.
+    const info = new Map()
+    for (const sha of all) info.set(sha, parseCommit((await cat.get(sha)).bytes))
+    // HEAD's first-parent chain, root first.
+    const chain = []
+    for (let s = head; s; s = info.get(s).parents[0]) chain.push(s)
+    chain.reverse()
+    if (limit) chain.length = Math.min(chain.length, limit)
+
+    const quilt = await client.createQuilt({ slug, name: slug, import: true })
+    log(`Importing ${chain.length} patches (${all.length} commits in all) into ${quilt.slug}…`)
+    const ids = new Map() // git sha → quilt commit id
+    const blobs = new Map() // git blob sha → { id, size }
+    const assigned = new Set()
+    const items = []
+    let pending = []
+    let commits = 0; let patches = 0
+
+    const flush = async () => {
+      if (!items.length) return
+      await client.upload(quilt.id, pending)
+      const r = await client.importCommits(quilt.id, items.splice(0))
+      pending = []
+      commits += r.commits; patches += r.patches
+      log(`  ${patches} patches, ${commits} commits`)
+    }
+
+    const emit = async (sha, square, kind) => {
+      const g = info.get(sha)
+      const changes = []
+      for (const ch of diffTree(repo, g.parents[0] || null, sha)) {
+        if (ch.delete) { changes.push({ path: ch.path, op: 'delete' }); continue }
+        const mode = MODES[ch.gitMode]
+        if (!mode) { report.push({ kind: ch.gitMode === '160000' ? 'submodule' : 'mode', sha, path: ch.path, note: `git mode ${ch.gitMode} left out` }); continue }
+        let b = blobs.get(ch.sha)
+        if (!b) {
+          const { bytes } = await cat.get(ch.sha)
+          b = { id: blobId(bytes), size: bytes.length }
+          blobs.set(ch.sha, b)
+          pending.push({ kind: 'blob', id: b.id, bytes })
+        }
+        changes.push({ path: ch.path, op: 'put', blob: b.id, mode, size: b.size })
+      }
+      const c = cleanCommit({
+        quilt_id: quilt.id, square_id: square.id,
+        parents: g.parents.filter((p) => ids.has(p)).map((p) => ids.get(p)),
+        author: member(g.author || {}), message: g.message, authored_at: g.author?.at || 0, changes
+      })
+      const id = commitId(c)
+      ids.set(sha, id)
+      pending.push({ kind: 'commit', id, bytes: commitBytes(c) })
+      items.push({ id, commit: c, kind, square, git_sha: sha, payload: { committer: g.committer || null, author_email: g.author?.email || '' } })
+      if (items.length >= batch) await flush()
+    }
+
+    for (const sha of chain) {
+      const g = info.get(sha)
+      const title = String(g.message).split('\n')[0].slice(0, 200)
+      const square = { id: uuidv7(g.author?.at || Date.now()), title, base: g.parents[0] ? ids.get(g.parents[0]) || null : null, holder: member(g.author || {}).member_id }
+      if (g.parents.length > 1) {
+        // Side commits: reachable from parents 2..n and not yet in any square, parents first.
+        const side = []
+        const seen = new Set()
+        const visit = (s) => {
+          if (!s || seen.has(s) || assigned.has(s) || !info.has(s)) return
+          seen.add(s)
+          for (const p of info.get(s).parents) visit(p)
+          side.push(s)
+        }
+        for (const p of g.parents.slice(1)) visit(p)
+        if (side.length) {
+          const m = title.match(/^Merge (?:pull request #\d+ from |branch ')([^' ]+)/)
+          if (m) square.title = m[1]
+          for (const s of side) { assigned.add(s); await emit(s, square, 'side') }
+        }
+      }
+      assigned.add(sha)
+      await emit(sha, square, 'patch')
+    }
+    await flush()
+
+    let validated
+    if (validate) {
+      validated = 0
+      // validate: 'all' checks every imported commit (side commits of merges too), else the patches.
+      for (const sha of validate === 'all' ? [...ids.keys()] : chain) {
+        const want = new Map()
+        for (const row of git(repo, ['ls-tree', '-r', '-z', sha]).toString('utf8').split('\0').filter(Boolean)) {
+          const [meta, path] = row.split('\t')
+          const [mode, type, osha] = meta.split(' ')
+          if (type !== 'blob' || !MODES[mode]) continue
+          want.set(path, { mode: MODES[mode], blob: blobs.get(osha)?.id })
+        }
+        const t = await client.tree(quilt.id, `c:${ids.get(sha)}`)
+        const bad = t.entries.length !== want.size || t.entries.some((e) => { const w = want.get(e.path); return !w || w.mode !== e.mode || w.blob !== e.blob })
+        if (bad) throw new Error(`validation: the tree of git ${sha.slice(0, 12)} does not match quilt commit ${ids.get(sha).slice(0, 12)}`)
+        validated++
+      }
+    }
+    return { quilt: quilt.id, slug: quilt.slug, commits, patches, report, ...(validate ? { validated } : {}), tip: ids.get(chain[chain.length - 1]) }
+  } finally {
+    cat.close()
+  }
+}

package/lib/quilts/pack.js

@@ -0,0 +1,118 @@
+// Packs (plans/quilt-source-control/03, "Pack format"): the immutable upload container for a
+// commit's objects. Magic `QPK1`, then entries { kind u8, id [32], len u32, bytes }, then a
+// trailer { entry_count u32, index [entry], trailer_len u32 }. Each index entry is
+// (kind u8, id [32], offset u32, len u32, flags u8): offset and len name the stored bytes of
+// the entry, so a reader holding a row does one ranged read. The pack id is the BLAKE3 of the
+// trailer, so it names every entry's location and id.
+import zlib from 'node:zlib'
+import { idOf } from './hash.js'
+
+export const MAGIC = Buffer.from('QPK1')
+export const MAX_PACK = 64 * 1024 * 1024
+
+/** Entry kinds, and the id context each one's (decompressed) bytes hash under. */
+export const KIND = { blob: 1, delta: 2, chunked: 3, chunk: 4, manifest: 5, tree: 6, term: 7, commit: 8 }
+const NAME = Object.fromEntries(Object.entries(KIND).map(([k, v]) => [v, k]))
+const CONTEXT = { blob: 'blob', delta: 'blob', chunked: 'blob', chunk: 'chunk', manifest: 'manifest', tree: 'tree', term: 'term', commit: 'commit' }
+
+// Compression, in the entry's flags. zstd when this Node has it (≥ 22.15), else deflate.
+export const RAW = 0
+export const DEFLATE = 1
+export const ZSTD = 2
+const HAS_ZSTD = typeof zlib.zstdCompressSync === 'function'
+
+function squeeze (bytes) {
+  if (bytes.length < 64) return { flags: RAW, data: bytes }
+  const data = HAS_ZSTD ? zlib.zstdCompressSync(bytes) : zlib.deflateRawSync(bytes, { level: 6 })
+  // Stored raw unless compression saves at least 5% (03's rule for chunks, used for everything).
+  if (data.length > bytes.length * 0.95) return { flags: RAW, data: bytes }
+  return { flags: HAS_ZSTD ? ZSTD : DEFLATE, data }
+}
+
+/** The bytes of a stored entry, decompressed by its flags. */
+export function unsqueeze (flags, data) {
+  if (flags === RAW) return Buffer.from(data)
+  if (flags === DEFLATE) return zlib.inflateRawSync(data)
+  if (flags === ZSTD) {
+    if (!HAS_ZSTD) throw new Error('this pack entry is zstd and this Node cannot read zstd (needs Node 22.15 or later)')
+    return zlib.zstdDecompressSync(data)
+  }
+  throw new Error(`unknown pack entry flags ${flags}`)
+}
+
+const ENTRY_HEAD = 1 + 32 + 4
+const INDEX_ENTRY = 1 + 32 + 4 + 4 + 1
+
+/**
+ * Builds a pack from [{ kind: 'blob' | 'tree' | 'term' | 'commit' | ..., id, bytes }]
+ * (duplicate ids are written once). Returns { id, bytes, index: [{ kind, id, offset, len, flags }] }.
+ */
+export function buildPack (objects) {
+  const parts = [MAGIC]
+  let at = MAGIC.length
+  const index = []
+  const seen = new Set()
+  for (const o of objects) {
+    if (seen.has(o.id)) continue
+    seen.add(o.id)
+    const kind = KIND[o.kind]
+    if (!kind) throw new Error(`unknown pack entry kind ${o.kind}`)
+    const { flags, data } = squeeze(Buffer.from(o.bytes))
+    const h = Buffer.alloc(ENTRY_HEAD)
+    h[0] = kind; Buffer.from(o.id, 'hex').copy(h, 1); h.writeUInt32BE(data.length, 33)
+    parts.push(h, data)
+    index.push({ kind: o.kind, id: o.id, offset: at + ENTRY_HEAD, len: data.length, flags })
+    at += ENTRY_HEAD + data.length
+  }
+  const trailer = trailerBytes(index)
+  parts.push(trailer)
+  const bytes = Buffer.concat(parts)
+  if (bytes.length > MAX_PACK) throw Object.assign(new Error(`pack over 64 MiB (${bytes.length} bytes); split the commit`), { code: 'pack_too_large' })
+  return { id: idOf('pack', trailer), bytes, index }
+}
+
+function trailerBytes (index) {
+  const t = Buffer.alloc(4 + index.length * INDEX_ENTRY + 4)
+  t.writeUInt32BE(index.length, 0)
+  let p = 4
+  for (const e of index) {
+    t[p] = KIND[e.kind]; Buffer.from(e.id, 'hex').copy(t, p + 1)
+    t.writeUInt32BE(e.offset, p + 33); t.writeUInt32BE(e.len, p + 37); t[p + 41] = e.flags
+    p += INDEX_ENTRY
+  }
+  t.writeUInt32BE(t.length, p)
+  return t
+}
+
+/** The index of a whole pack, read from its trailer, and the pack id it implies. */
+export function readIndex (bytes) {
+  const b = Buffer.from(bytes)
+  if (!b.subarray(0, 4).equals(MAGIC)) throw new Error('not a Quilt pack')
+  const tlen = b.readUInt32BE(b.length - 4)
+  const t = b.subarray(b.length - tlen)
+  const n = t.readUInt32BE(0)
+  if (tlen !== 4 + n * INDEX_ENTRY + 4) throw new Error('pack trailer is damaged')
+  const index = []
+  for (let i = 0, p = 4; i < n; i++, p += INDEX_ENTRY) {
+    index.push({ kind: NAME[t[p]], id: t.subarray(p + 1, p + 33).toString('hex'), offset: t.readUInt32BE(p + 33), len: t.readUInt32BE(p + 37), flags: t[p + 41] })
+  }
+  return { id: idOf('pack', t), index }
+}
+
+/** The object `e` (an index entry) of a pack, from its stored bytes, checked against its id. */
+export function readEntry (e, stored) {
+  const bytes = unsqueeze(e.flags, stored)
+  if (idOf(CONTEXT[e.kind], bytes) !== e.id) throw Object.assign(new Error(`pack entry ${e.id} does not match its id`), { code: 'pack_corrupt', id: e.id })
+  return bytes
+}
+
+/**
+ * What sealing checks before any row is written (03, "Sealing a pack"): the pack id is the
+ * trailer's, and every entry decompresses to bytes whose id is the one claimed. Returns the index.
+ */
+export function verifyPack (bytes, expectId) {
+  const { id, index } = readIndex(bytes)
+  if (expectId && id !== expectId) throw Object.assign(new Error('pack id does not match its trailer'), { code: 'pack_corrupt' })
+  for (const e of index) readEntry(e, bytes.subarray(e.offset, e.offset + e.len))
+  return { id, index }
+}

package/lib/quilts/records.js

@@ -0,0 +1,210 @@
+// The immutable records of Quilt source control (plans/quilt-source-control/README §3.1):
+// commits, their file changes and conflict terms, as JSON for the API and as canonical CBOR
+// for their ids. A commit's id depends only on what its author made: no tree, no server time,
+// no sequence number, no git hash.
+import { encode, decode } from './cbor.js'
+import { idOf, isId, idBytes } from './hash.js'
+
+export const MODES = ['file', 'exec', 'symlink', 'quilt']
+export const TERM_KINDS = ['content', 'order', 'edit_vs_delete', 'name', 'mode', 'square_divergence']
+export const MAX_FILES_PER_COMMIT = 20000
+export const MAX_MESSAGE = 64 * 1024
+
+const hex = (b) => Buffer.from(b).toString('hex')
+
+/**
+ * A path as the quilt keeps it: NFC, posix, relative, no empty, '.' or '..' segments, no
+ * trailing slash, never inside .git. Throws on anything else.
+ */
+export function cleanPath (p) {
+  if (typeof p !== 'string' || !p) throw new Error('a path is required')
+  const s = p.normalize('NFC')
+  if (s.includes('\\') || s.includes('\0')) throw new Error(`bad path ${JSON.stringify(p)}: use / and no NUL`)
+  const parts = s.split('/')
+  if (parts.some((x) => !x || x === '.' || x === '..')) throw new Error(`bad path ${JSON.stringify(p)}`)
+  if (parts[0] === '.git') throw new Error(`bad path ${JSON.stringify(p)}: .git is not part of a quilt`)
+  return s
+}
+
+/** A path prefix (a block's directory): '' for the root, else a clean path. */
+export function cleanPrefix (p) {
+  const s = String(p || '').replace(/^\/+|\/+$/g, '')
+  return s ? cleanPath(s) : ''
+}
+
+/** Whether `path` lies under `prefix` (a directory, or the file itself). */
+export const under = (path, prefix) => !prefix || path === prefix || path.startsWith(prefix + '/')
+
+function side (s) {
+  return {
+    ...(s.blob ? { b: idBytes(s.blob) } : {}),
+    ...(s.mode ? { m: s.mode } : {}),
+    ...(s.from_commit ? { fc: idBytes(s.from_commit) } : {}),
+    ...(s.from_square ? { fs: s.from_square } : {}),
+    ...(s.by ? { by: s.by } : {})
+  }
+}
+const unside = (s) => ({
+  ...(s.b ? { blob: hex(s.b) } : {}),
+  ...(s.m ? { mode: s.m } : {}),
+  ...(s.fc ? { from_commit: hex(s.fc) } : {}),
+  ...(s.fs ? { from_square: s.fs } : {}),
+  ...(s.by ? { by: s.by } : {})
+})
+
+/** A conflict term's canonical bytes (kind, N adds, N−1 removes, origin). */
+export function termBytes (t) {
+  if (!TERM_KINDS.includes(t.kind)) throw new Error(`bad conflict kind ${t.kind}`)
+  if (!Array.isArray(t.adds) || !Array.isArray(t.removes) || t.adds.length !== t.removes.length + 1) throw new Error('a conflict term has N adds and N-1 removes')
+  return encode({
+    k: t.kind,
+    ad: t.adds.map(side),
+    rm: t.removes.map(side),
+    ...(t.origin ? { or: { r: t.origin.reason, ...(t.origin.against ? { ag: idBytes(t.origin.against) } : {}) } } : {}),
+    // 07's suggestion: a ladder step that may not merge by itself (`words`) and the text it made.
+    ...(t.suggestion ? { sg: { h: t.suggestion.how, b: idBytes(t.suggestion.blob) } } : {}),
+    // A name term's other paths (a file on a directory, or one case-folded name): kept side wins the name.
+    ...(t.clash && t.clash.length ? { cl: [...t.clash].sort() } : {})
+  })
+}
+
+export function decodeTerm (bytes) {
+  const r = decode(bytes)
+  return {
+    kind: r.k,
+    adds: r.ad.map(unside),
+    removes: r.rm.map(unside),
+    ...(r.or ? { origin: { reason: r.or.r, ...(r.or.ag ? { against: hex(r.or.ag) } : {}) } } : {}),
+    ...(r.sg ? { suggestion: { how: r.sg.h, blob: hex(r.sg.b) } } : {}),
+    ...(r.cl ? { clash: r.cl } : {})
+  }
+}
+
+export const termId = (t) => idOf('term', termBytes(t))
+
+/** Checks and normalises one FileChange (JSON form). */
+export function cleanChange (c) {
+  const path = cleanPath(c.path)
+  if (c.op === 'delete') return { path, op: 'delete' }
+  if (c.op === 'put') {
+    if (!isId(c.blob)) throw new Error(`${path}: put needs a blob id`)
+    const mode = c.mode || 'file'
+    if (!MODES.includes(mode)) throw new Error(`${path}: bad mode ${mode}`)
+    if (!Number.isSafeInteger(c.size) || c.size < 0) throw new Error(`${path}: put needs a size`)
+    const out = { path, op: 'put', blob: c.blob, mode, size: c.size }
+    if (c.copy_from) out.copy_from = { path: cleanPath(c.copy_from.path), commit: c.copy_from.commit }
+    return out
+  }
+  if (c.op === 'conflict') {
+    if (!isId(c.term)) throw new Error(`${path}: conflict needs a term id`)
+    return { path, op: 'conflict', term: c.term }
+  }
+  throw new Error(`${path}: bad op ${c.op}`)
+}
+
+/** Sorts and checks a commit's changes: by path (bytewise, as the tree sorts), no duplicates. */
+export function cleanChanges (changes) {
+  if (!Array.isArray(changes)) throw new Error('changes must be a list')
+  if (changes.length > MAX_FILES_PER_COMMIT) throw Object.assign(new Error(`too many files in one commit (${changes.length}; at most ${MAX_FILES_PER_COMMIT})`), { code: 'too_many_files' })
+  const out = changes.map(cleanChange).sort((a, b) => cmpPath(a.path, b.path))
+  for (let i = 1; i < out.length; i++) if (out[i].path === out[i - 1].path) throw new Error(`${out[i].path} is changed twice`)
+  return out
+}
+
+/** Bytewise order of UTF-8 paths, the order of every tree and change list. */
+export function cmpPath (a, b) {
+  return a === b ? 0 : Buffer.compare(Buffer.from(a), Buffer.from(b))
+}
+
+function changeCbor (c) {
+  if (c.op === 'delete') return { p: c.path, o: 'delete' }
+  if (c.op === 'conflict') return { p: c.path, o: 'conflict', t: idBytes(c.term) }
+  return {
+    p: c.path, o: 'put', b: idBytes(c.blob), m: c.mode, z: c.size,
+    ...(c.copy_from ? { cf: { p: c.copy_from.path, c: idBytes(c.copy_from.commit) } } : {})
+  }
+}
+function unchange (c) {
+  if (c.o === 'delete') return { path: c.p, op: 'delete' }
+  if (c.o === 'conflict') return { path: c.p, op: 'conflict', term: hex(c.t) }
+  return { path: c.p, op: 'put', blob: hex(c.b), mode: c.m, size: c.z, ...(c.cf ? { copy_from: { path: c.cf.p, commit: hex(c.cf.c) } } : {}) }
+}
+
+/**
+ * A commit in its JSON form, checked and normalised: { quilt_id, square_id, parents,
+ * predecessor?, author: { member_id, kind, name, tool?, model? }, on_behalf_of?, task_id?,
+ * session_room?, message, authored_at, changes, stack, conflicted }.
+ */
+export function cleanCommit (c) {
+  if (!c.quilt_id || !c.square_id) throw new Error('a commit names its quilt and square')
+  const parents = c.parents || []
+  if (!parents.every(isId)) throw new Error('parents must be commit ids')
+  if (c.predecessor != null && !isId(c.predecessor)) throw new Error('predecessor must be a commit id')
+  const a = c.author || {}
+  if (!a.member_id || !['person', 'agent', 'system'].includes(a.kind)) throw new Error('author needs member_id and kind')
+  const message = String(c.message ?? '')
+  if (Buffer.byteLength(message) > MAX_MESSAGE) throw new Error('commit message over 64 KiB')
+  const changes = cleanChanges(c.changes || [])
+  const stack = {}
+  for (const [k, v] of Object.entries(c.stack || {})) if (v != null) stack[k] = String(v)
+  return {
+    quilt_id: String(c.quilt_id),
+    square_id: String(c.square_id),
+    parents: [...parents],
+    ...(c.predecessor ? { predecessor: c.predecessor } : {}),
+    author: { member_id: String(a.member_id), kind: a.kind, name: String(a.name || ''), ...(a.tool ? { tool: String(a.tool) } : {}), ...(a.model ? { model: String(a.model) } : {}) },
+    ...(c.on_behalf_of ? { on_behalf_of: String(c.on_behalf_of) } : {}),
+    ...(c.task_id ? { task_id: String(c.task_id) } : {}),
+    ...(c.session_room ? { session_room: String(c.session_room) } : {}),
+    message,
+    authored_at: Math.trunc(Number(c.authored_at) || 0),
+    changes,
+    stack,
+    conflicted: changes.filter((x) => x.op === 'conflict').length
+  }
+}
+
+/** A commit's canonical bytes. */
+export function commitBytes (c) {
+  const a = c.author
+  return encode({
+    q: c.quilt_id,
+    s: c.square_id,
+    p: c.parents.map(idBytes),
+    pr: c.predecessor ? idBytes(c.predecessor) : undefined,
+    a: { m: a.member_id, k: a.kind, n: a.name, t: a.tool, md: a.model },
+    ob: c.on_behalf_of,
+    tk: c.task_id,
+    sr: c.session_room,
+    msg: c.message,
+    at: c.authored_at,
+    c: c.changes.map(changeCbor),
+    st: Object.keys(c.stack).length ? c.stack : undefined,
+    cn: c.conflicted
+  })
+}
+
+export function decodeCommit (bytes) {
+  const r = decode(bytes)
+  return {
+    quilt_id: r.q,
+    square_id: r.s,
+    parents: r.p.map(hex),
+    ...(r.pr ? { predecessor: hex(r.pr) } : {}),
+    author: { member_id: r.a.m, kind: r.a.k, name: r.a.n, ...(r.a.t ? { tool: r.a.t } : {}), ...(r.a.md ? { model: r.a.md } : {}) },
+    ...(r.ob ? { on_behalf_of: r.ob } : {}),
+    ...(r.tk ? { task_id: r.tk } : {}),
+    ...(r.sr ? { session_room: r.sr } : {}),
+    message: r.msg,
+    authored_at: r.at,
+    changes: r.c.map(unchange),
+    stack: r.st || {},
+    conflicted: r.cn
+  }
+}
+
+/** The commit's id, from its canonical bytes. */
+export const commitId = (c) => idOf('commit', commitBytes(c))
+
+/** A blob's id: BLAKE3 of the raw file bytes under the blob context. */
+export const blobId = (bytes) => idOf('blob', bytes)

package/lib/quilts/textdiff.js

@@ -0,0 +1,96 @@
+// Line diffs for quilts: unified text for `diff` and `show`, and the line mapping `blame` walks.
+
+import { xdiff } from './xdiff.js'
+
+const MAX_TEXT = 8 * 1024 * 1024
+
+/** Whether bytes read as text: valid UTF-8, no NUL, at most 8 MiB (07's max_merge_text_bytes). */
+export function isText (buf) {
+  if (!buf) return true
+  if (buf.length > MAX_TEXT || buf.includes(0)) return false
+  try { new TextDecoder('utf-8', { fatal: true }).decode(buf); return true } catch { return false }
+}
+
+/** A text's lines, split on \n, without the empty string after a final newline. */
+export function splitLines (s) {
+  if (!s) return []
+  const ls = s.split('\n')
+  if (ls[ls.length - 1] === '') ls.pop()
+  return ls
+}
+
+/** Lines back to bytes, each ended by \n (what `hunks` diffs). */
+function linesBuf (ls) { return Buffer.from(ls.length ? ls.join('\n') + '\n' : '', 'utf8') }
+
+/**
+ * The hunks between two line lists: [{ a: [start, len], b: [start, len] }], chosen the way git's
+ * xdiff chooses them (its Myers variant, record cleanup, and sliding with the indent heuristic),
+ * so `diff`, `show` and `blame` agree with git's.
+ */
+export function hunks (a, b) {
+  return xdiff(linesBuf(a), linesBuf(b))
+}
+
+/** +added −removed counts between two texts. */
+export function lineStat (a, b) {
+  let add = 0; let del = 0
+  for (const h of hunks(splitLines(a), splitLines(b))) { del += h.a[1]; add += h.b[1] }
+  return { add, del }
+}
+
+/**
+ * A unified diff of one file (git's format, 3 lines of context). `before`/`after` are strings,
+ * or null when the file is added or deleted.
+ */
+export function unified (path, before, after, { context = 3, fromPath = path } = {}) {
+  const a = splitLines(before ?? '')
+  const b = splitLines(after ?? '')
+  const head = [`--- ${before == null ? '/dev/null' : `a/${fromPath}`}`, `+++ ${after == null ? '/dev/null' : `b/${path}`}`]
+  const hs = hunks(a, b)
+  if (!hs.length) return ''
+  const out = [...head]
+  // Group hunks whose context overlaps.
+  let i = 0
+  while (i < hs.length) {
+    let j = i
+    while (j + 1 < hs.length && hs[j + 1].a[0] - (hs[j].a[0] + hs[j].a[1]) <= context * 2) j++
+    const aStart = Math.max(0, hs[i].a[0] - context)
+    const aEnd = Math.min(a.length, hs[j].a[0] + hs[j].a[1] + context)
+    const bStart = Math.max(0, hs[i].b[0] - context)
+    const bEnd = Math.min(b.length, hs[j].b[0] + hs[j].b[1] + context)
+    const body = []
+    let ap = aStart
+    for (let k = i; k <= j; k++) {
+      const h = hs[k]
+      while (ap < h.a[0]) body.push(' ' + a[ap++])
+      for (let x = 0; x < h.a[1]; x++) body.push('-' + a[h.a[0] + x])
+      for (let x = 0; x < h.b[1]; x++) body.push('+' + b[h.b[0] + x])
+      ap = h.a[0] + h.a[1]
+    }
+    while (ap < aEnd) body.push(' ' + a[ap++])
+    const range = (s, n) => `${n === 0 ? s : s + 1}${n === 1 ? '' : `,${n}`}`
+    out.push(`@@ -${range(aStart, aEnd - aStart)} +${range(bStart, bEnd - bStart)} @@`, ...body)
+    i = j + 1
+  }
+  return out.join('\n') + '\n'
+}
+
+/**
+ * For each line of `b`, its line in `a` when the diff kept it, else -1 (it was added or
+ * changed in b). What blame follows from a commit back to its parent. Given Buffers (the files'
+ * bytes) it diffs exactly as `git blame` does, final newline and common-tail trim included.
+ */
+export function lineMap (a, b) {
+  const bytes = Buffer.isBuffer(a)
+  const hs = bytes ? xdiff(a, b, { trimTail: true }) : hunks(a, b)
+  const n = bytes ? splitLines(b.toString('utf8')).length : b.length
+  const map = new Array(n).fill(-1)
+  let ai = 0; let bi = 0
+  for (const h of hs) {
+    while (bi < h.b[0]) map[bi++] = ai++
+    ai = h.a[0] + h.a[1]
+    bi = h.b[0] + h.b[1]
+  }
+  while (bi < n) map[bi++] = ai++
+  return map
+}