@heyquilt/seam 0.27.0 → 0.131.0

package/lib/quilts/exit-archive.js

@@ -0,0 +1,184 @@
+// The whole quilt as an archive (14, "Export as the exit path"; D39): the owner's way out that keeps
+// everything Seam stores. One plain .tar holding
+//   MANIFEST.json   { format, quilt: { id, slug }, archive_seq, last_segment, members, files }
+//   w/<from>-<to>.qws  every log segment (archiver.js), so the log and its commit rows replay
+//   p/<pack id>        every pack as stored (sealed packs stay ciphertext, 11.11)
+//   members.json     the members the log names: { member_id, kind, name } and nothing else
+//   git_shas.json    [[git sha, commit id], …] sorted by sha: every translation an import or export kept
+// `files` lists every other entry with its size and BLAKE3, sorted by path. The bytes are a pure
+// function of what is stored, so exporting twice without a write in between gives the same file.
+// readArchive is the reader: it checks every size and hash, that nothing is missing or extra, and
+// replays the segments (their chain, hashes and seq continuity) into the log, commits and lines;
+// snapshotIn takes any commit's files out of it, with no server.
+import { blake3 } from '@noble/hashes/blake3.js'
+import { tar, untar } from './tarball.js'
+import { replaySegments } from './archiver.js'
+import { readIndex, readEntry, unsqueeze, deltaBase, usesTrained, trainedDictOf } from './pack.js'
+import { BUILTIN_DICT, BUILTIN_DICT_ID } from './dict.js'
+import { applyChanges } from './tree.js'
+import { decodeManifest } from './fastcdc.js'
+import { blobId } from './records.js'
+import { exportAuthor, exportMessage, COMMITTER, EXPORT_VERSION } from './export-format.js'
+
+export const ARCHIVE_FORMAT = 'seam-archive/1'
+// The archive is built in memory and answered as one download (ruling in 14, 2026-10-27).
+export const MAX_ARCHIVE = 512 * 1024 * 1024
+
+const hashOf = (bytes) => Buffer.from(blake3(bytes)).toString('hex')
+
+/** Builds the archive bytes from a quilt row, its segments, packs and members. */
+export function buildArchive ({ quilt, segments, packs, members, gitShas = [], attestation = false, stackedOn = null }) {
+  const entries = [
+    ...segments.map(({ name, bytes }) => ({ path: `w/${name}`, mode: 'file', bytes })),
+    ...packs.map(({ name, bytes }) => ({ path: `p/${name}`, mode: 'file', bytes })),
+    { path: 'git_shas.json', mode: 'file', bytes: Buffer.from(JSON.stringify(gitShas.map((g) => [g.sha, g.commit_id]).sort((a, b) => (a[0] < b[0] ? -1 : 1))) + '\n') },
+    { path: 'members.json', mode: 'file', bytes: Buffer.from(JSON.stringify(members.map(({ member_id, kind, name }) => ({ member_id, kind: kind || null, name: name || null })).sort((a, b) => (a.member_id < b.member_id ? -1 : 1)), null, 2) + '\n') }
+  ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  const manifest = {
+    format: ARCHIVE_FORMAT,
+    quilt: { id: quilt.id, slug: quilt.slug || null },
+    archive_seq: quilt.archive_seq || 0,
+    last_segment: quilt.last_segment || null,
+    // How the server exports (14): with the Quilt-Attestation trailer, so the offline rebuild writes the same shas.
+    // With Quilt-Stacked-On (stackedOn: square id → the square it was stacked on), the map the trailer reads.
+    ...(attestation || stackedOn ? { export: { ...(attestation ? { attestation: true } : {}), ...(stackedOn ? { stacked_on: stackedOn } : {}) } } : {}),
+    files: entries.map((e) => ({ path: e.path, size: e.bytes.length, blake3: hashOf(e.bytes) }))
+  }
+  return tar([{ path: 'MANIFEST.json', mode: 'file', bytes: Buffer.from(JSON.stringify(manifest, null, 2) + '\n') }, ...entries])
+}
+
+/**
+ * Reads and checks an archive. Answers { manifest, files, log, commits, lines, squares, members }
+ * or throws naming the first thing wrong (a size, a hash, a missing or extra file, a broken chain).
+ */
+export async function readArchive (bytes) {
+  const files = new Map(untar(bytes).map((f) => [f.path, f.bytes]))
+  const raw = files.get('MANIFEST.json')
+  if (!raw) throw new Error('not a Seam archive: it has no MANIFEST.json')
+  const manifest = JSON.parse(raw.toString('utf8'))
+  if (manifest.format !== ARCHIVE_FORMAT) throw new Error(`unknown archive format ${manifest.format} (this reader reads ${ARCHIVE_FORMAT})`)
+  const listed = new Set()
+  for (const f of manifest.files) {
+    const got = files.get(f.path)
+    if (!got) throw new Error(`${f.path} is in the manifest but not in the archive`)
+    if (got.length !== f.size) throw new Error(`${f.path} is ${got.length} bytes, the manifest says ${f.size}`)
+    if (hashOf(got) !== f.blake3) throw new Error(`${f.path} does not match its BLAKE3 in the manifest`)
+    listed.add(f.path)
+  }
+  for (const p of files.keys()) if (p !== 'MANIFEST.json' && !listed.has(p)) throw new Error(`${p} is in the archive but not in the manifest`)
+  const q = manifest.quilt.id
+  const under = (kind) => [...files.keys()].filter((p) => p.startsWith(kind + '/')).map((p) => p.slice(kind.length + 1)).sort()
+  const objects = { listFiles: async (_q, kind) => under(kind), readFile: async (_q, kind, name) => files.get(`${kind}/${name}`) }
+  const r = await replaySegments(objects, q)
+  if (r.archive_seq !== manifest.archive_seq) throw new Error(`the segments end at row ${r.archive_seq}, the manifest says ${manifest.archive_seq}`)
+  if ((r.last_segment || null) !== (manifest.last_segment || null)) throw new Error('the last segment is not the one the manifest names')
+  const members = JSON.parse((files.get('members.json') || Buffer.from('[]')).toString('utf8'))
+  const gitShas = new Map(JSON.parse((files.get('git_shas.json') || Buffer.from('[]')).toString('utf8')))
+  return { manifest, files, log: r.log, commits: r.commits, lines: r.lines, squares: r.squares, members, gitShas, packs: under('p') }
+}
+
+/** The commit id `rev` names in a read archive: a line's tip, a whole id, or a unique prefix (4+). */
+export function resolveIn (a, rev) {
+  const s = String(rev || 'main').trim()
+  if (a.lines.has(s)) { const tip = a.lines.get(s).tip; if (!tip) throw new Error(`line ${s} is empty`); return tip }
+  if (a.commits.has(s)) return s
+  if (/^[0-9a-f]{4,63}$/.test(s)) {
+    const hits = [...a.commits.keys()].filter((id) => id.startsWith(s))
+    if (hits.length === 1) return hits[0]
+    if (hits.length > 1) throw new Error(`${s} matches ${hits.length} commits: give more of it`)
+  }
+  throw new Error(`no line or commit ${s} in this archive`)
+}
+
+/**
+ * The files of commit `rev` from a read archive alone: its first-parent chain's changes applied
+ * from the start (each commit's changes are against its first parent), each blob read from the
+ * packs and checked against its id. Answers [{ path, mode, bytes }] sorted by path; a file in
+ * conflict refuses, as a tarball does. A sealed quilt's files are ciphertext and refuse.
+ */
+export function snapshotIn (a, rev) {
+  const id = resolveIn(a, rev)
+  const chain = []
+  for (let c = a.commits.get(id); c; c = c.parents?.[0] ? a.commits.get(c.parents[0]) : null) chain.push(c)
+  const last = chain[chain.length - 1]
+  if (last.parents?.length) throw new Error(`commit ${last.id.slice(0, 12)}'s parent is not in this archive`)
+  let entries = []
+  for (const c of chain.reverse()) entries = applyChanges(entries, c.changes || [])
+  const blob = blobReader(a)
+  const out = []
+  for (const x of entries) {
+    if (x.mode === 'conflict') throw new Error(`${x.path} is in conflict at ${rev}: take a settled commit`)
+    if (x.mode !== 'file' && x.mode !== 'exec' && x.mode !== 'symlink') continue
+    out.push({ path: x.path, mode: x.mode, bytes: blob(x.blob, x.path) })
+  }
+  return { commit: id, files: out }
+}
+
+/** blob(id, path) → the file's bytes from the archive's packs, checked against its id. */
+export function blobReader (a) {
+  const stored = new Map()
+  for (const name of a.packs) {
+    const bytes = a.files.get(`p/${name}`)
+    for (const e of readIndex(bytes).index) if (!stored.has(e.id)) stored.set(e.id, { e, raw: bytes.subarray(e.offset, e.offset + e.len) })
+  }
+  const object = (oid, what) => { const s = stored.get(oid); if (!s) throw new Error(`${what} ${oid.slice(0, 12)} is in no pack of this archive`); return s }
+  const blob = (bid, p, depth = 0) => {
+    const { e, raw } = object(bid, `the file ${p}:`)
+    // A delta (03 The background squeeze): its base read the same way, then the target rebuilt and checked.
+    if (e.kind === 'delta') {
+      if (depth >= 50) throw new Error(`${p}: its delta chain is over 50 deep`)
+      try { return readEntry(e, raw, { base: blob(deltaBase(raw), p, depth + 1) }) } catch (err) { throw new Error(`${p} does not rebuild from its delta: ${err.message}`) }
+    }
+    if (e.kind === 'blob') {
+      // An entry with the quilt's trained dictionary (03 Dictionaries) names it; the archive holds its pack.
+      let dict = null
+      if (usesTrained(e.flags) && raw.length >= 32) {
+        const did = trainedDictOf(raw)
+        if (did === BUILTIN_DICT_ID) dict = BUILTIN_DICT
+        else { const d = object(did, `the dictionary of ${p}:`); dict = readEntry(d.e, d.raw) }
+      }
+      try { return readEntry(e, raw, { dict }) } catch { throw new Error(`${p} does not match its id (a sealed quilt's files need its key, 11.11)`) }
+    }
+    if (e.kind !== 'chunked') throw new Error(`${p} is stored as ${e.kind}, which this reader cannot read`)
+    const root = decodeManifest(unsqueeze(e.flags, raw))
+    const chunks = root.chunks || root.children.flatMap((c) => { const m = object(c.id, 'manifest'); return decodeManifest(readEntry(m.e, m.raw)).chunks })
+    const bytes = Buffer.concat(chunks.map((c) => { const k = object(c.id, 'chunk'); return readEntry(k.e, k.raw) }))
+    if (blobId(bytes) !== bid) throw new Error(`${p} does not match its id`)
+    return bytes
+  }
+  return blob
+}
+
+/**
+ * A stand-in for the server client that export-git.js drives, answered from a read archive alone,
+ * so `seam export git` can rebuild a line's git history offline with the same commit shas as the
+ * server's export (the same patch fields, messages and authors from export.js).
+ */
+export function archiveClient (a) {
+  const blob = blobReader(a)
+  const shaOf = new Map([...a.gitShas].map(([sha, id]) => [id, sha]))
+  const merges = (line) => a.log.filter((r) => r.kind === 'merge' && r.line === line).sort((x, y) => x.patch_no - y.patch_no)
+  return {
+    quilt: async () => ({ id: a.manifest.quilt.id }),
+    blobs: async (_q, ids) => ({ blobs: Object.fromEntries(ids.map((id) => [id, blob(id, id.slice(0, 12)).toString('base64')])) }),
+    exportPatches: async (_q, { line = 'main', after = -1, limit = 200 } = {}) => {
+      if (!a.lines.has(line)) throw new Error(`no line ${line} in this archive`)
+      const patches = merges(line).filter((r) => r.patch_no > after).slice(0, limit).map((row) => {
+        const id = row.commit || row.to || row.commit_id
+        const c = a.commits.get(id)
+        if (!c) throw new Error(`patch ${row.patch_no}'s commit ${String(id).slice(0, 12)} is not in this archive`)
+        const au = exportAuthor(c.author)
+        return {
+          patch_no: row.patch_no,
+          commit: c.id,
+          parent: c.parents[0] || null,
+          author: { name: au.name, email: au.email, at: Math.floor((c.authored_at || 0) / 1000) },
+          committer: { ...COMMITTER, at: Math.floor((row.at || 0) / 1000) },
+          message: exportMessage({ commit: c, line, patch_no: row.patch_no, git_sha: shaOf.get(c.id) || null, attestation: a.manifest.export && a.manifest.export.attestation ? row.seq : null, stacked_on: (a.manifest.export && a.manifest.export.stacked_on && a.manifest.export.stacked_on[c.square_id]) || null, stack_map: row.payload?.stack || null }),
+          changes: (c.changes || []).map((ch) => (ch.op === 'delete' ? { path: ch.path, op: 'delete' } : { path: ch.path, op: 'put', blob: ch.blob, mode: ch.mode }))
+        }
+      })
+      return { version: EXPORT_VERSION, quilt: a.manifest.quilt.id, line, patch_count: a.lines.get(line).patch_count, patches }
+    }
+  }
+}

package/lib/quilts/export-format.js

@@ -0,0 +1,52 @@
+// The git fields of an exported commit (plans/quilt-source-control/14, Export, Determinism): worked
+// out from the commit record and the merge row only, so the same patch always gives the same commit
+// id. Shared by the server's export (export.js) and the archive reader (exit-archive.js), which
+// rebuilds the same git history offline; no server code here.
+export const EXPORT_VERSION = 1
+export const COMMITTER = { name: 'Quilt', email: 'export@heyquilt.com' }
+
+/** A member slug safe for an email local part. */
+const slugOf = (id) => String(id || 'unknown').replace(/^[a-z]+:/, '').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64) || 'unknown'
+
+/**
+ * The git identity of a commit's author, frozen in the commit record. A stub member from a git
+ * import keeps the email git had (it was public there); everyone else gets the noreply address
+ * of 14 (`<slug>@people|agents.noreply.heyquilt.com`), since no member has opted in to a
+ * public email yet.
+ */
+export function exportAuthor (author = {}) {
+  const id = String(author.member_id || '')
+  const kind = author.kind === 'agent' ? 'agent' : 'person'
+  const stub = id.startsWith('stub:') ? id.slice(5) : ''
+  const email = stub.includes('@') ? stub : `${slugOf(id)}@${kind === 'agent' ? 'agents' : 'people'}.noreply.heyquilt.com`
+  const name = String(author.name || stub || slugOf(id)).replace(/[<>\n]/g, '').trim() || slugOf(id)
+  return { name, email, slug: slugOf(id), kind, ...(author.tool ? { tool: author.tool } : {}), ...(author.model ? { model: author.model } : {}) }
+}
+
+/** A stack key as a trailer name part (10): `db_migration` → `Db-Migration`. */
+export const trainCase = (k) => String(k).split(/[_\-\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase()).join('-')
+
+/** The commit message with 14's trailers, in their fixed order. */
+export function exportMessage ({ commit, line, patch_no: patchNo, git_sha: gitSha, attestation = null, stacked_on: stackedOn = null, stack_map: stackMap = null }) {
+  const a = exportAuthor(commit.author)
+  const trailers = [
+    `Quilt-Commit: ${commit.id}`,
+    `Quilt-Square: ${commit.square_id}`,
+    `Quilt-Patch: ${line}/${patchNo}`,
+    `Quilt-Author: ${a.slug} (${[a.kind, a.tool, a.model].filter(Boolean).join(', ')})`,
+    ...(commit.on_behalf_of ? [`Quilt-On-Behalf-Of: ${slugOf(commit.on_behalf_of)}`] : []),
+    ...(commit.task_id ? [`Quilt-Task: ${commit.task_id}`] : []),
+    // The square the patch's square was stacked on when it merged (SEAM_EXPORT_STACKED_ON).
+    ...(stackedOn ? [`Quilt-Stacked-On: ${stackedOn}`] : []),
+    // 10, Export: a patch merged under SEAM_STACK_EXPORT has its full map (inherited and derived keys
+    // too) in its merge row, written in Train-Case; older patches keep the keys their commit set.
+    ...(stackMap
+      ? Object.keys(stackMap).sort().map((k) => `Quilt-Stack-${trainCase(k)}: ${stackMap[k].value}`)
+      : Object.keys(commit.stack || {}).sort().filter((k) => commit.stack[k] !== null).map((k) => `Quilt-Stack-${k}: ${commit.stack[k]}`)),
+    ...(gitSha ? [`Quilt-Git-Sha: ${gitSha}`] : []),
+    // 11.7: the seq of the patch's merge row, whose server attestation proves it (SEAM_EXPORT_ATTESTATION).
+    ...(attestation != null ? [`Quilt-Attestation: ${attestation}`] : [])
+  ]
+  const body = String(commit.message || '').replace(/\s+$/, '')
+  return `${body || '(no message)'}\n\n${trailers.join('\n')}\n`
+}

package/lib/quilts/export-git.js

@@ -8,6 +8,8 @@
 import { spawn, execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
+import { signCommits } from './export-sign.js'
+import { lfsPatterns } from './export-lfs.js'
 
 const MODES = { file: '100644', exec: '100755', symlink: '120000', gitlink: '160000' }
 const GIT_ENV = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_CONFIG_NOSYSTEM: '1' }
@@ -56,9 +58,12 @@ async function fetchBlobs (client, q, ids) {
 
 /**
  * Exports `line` of quilt `q` to `branch` of the repository at `dir` (created bare when
- * missing). Returns { exported, patch_no, sha, branch }.
+ * missing). Returns { exported, patch_no, sha, branch }. With `sign` (export-sign.js exportKey), every
+ * commit carries an SSH signature with that key. With `lfs` ({ threshold, upload(bytes) → pointer
+ * text }, export-lfs.js), a file over the threshold or named by a `filter=lfs` line of the root
+ * `.gitattributes` is written as an LFS pointer and its bytes uploaded.
  */
-export async function exportGit (client, { q, dir, line = 'main', branch, page = 200, log = () => {} }) {
+export async function exportGit (client, { q, dir, line = 'main', branch, page = 200, sign = null, lfs = null, log = () => {} }) {
   branch = branch || line
   const gitDir = openRepo(dir)
   const stateFile = path.join(gitDir, 'quilt-export.json')
@@ -78,6 +83,7 @@ export async function exportGit (client, { q, dir, line = 'main', branch, page =
   let exported = 0
   let version = state ? state.version : null
   let quiltId = state ? state.quilt : null
+  let lfsMatch = lfs && sha ? lfsPatterns(tryGit(dir, ['show', `${sha}:.gitattributes`])) : null
   for (;;) {
     const r = await client.exportPatches(q, { line, after, limit: page })
     if (version !== null && version !== r.version) throw new Error(`export format ${r.version} differs from the ${version} this branch was exported with: export to a new branch`)
@@ -105,9 +111,21 @@ export async function exportGit (client, { q, dir, line = 'main', branch, page =
       await send(s); await send(msg); s = '\n'
       if (first && sha) s += `from ${sha}\n`
       first = false
+      if (lfs) {
+        const attrs = p.changes.find((c) => c.path === '.gitattributes')
+        if (attrs) lfsMatch = attrs.op === 'delete' ? null : lfsPatterns(blobs.get(attrs.blob)?.toString('utf8'))
+      }
       for (const c of p.changes) {
-        if (c.op === 'delete') s += `D ${fiPath(c.path)}\n`
+        const bytes = lfs && c.op === 'put' && (!c.mode || c.mode === 'file' || c.mode === 'exec') && c.path !== '.gitattributes' ? blobs.get(c.blob) : null
+        if (bytes && (bytes.length > lfs.threshold || lfsMatch?.ignores(c.path))) {
+          const pointer = await lfs.upload(bytes)
+          s += `M ${MODES[c.mode || 'file']} inline ${fiPath(c.path)}\ndata ${Buffer.byteLength(pointer)}\n${pointer}\n`
+        } else if (c.op === 'delete') s += `D ${fiPath(c.path)}\n`
         else if (c.mode === 'gitlink') s += `M 160000 ${blobMark.get(c.blob)} ${fiPath(c.path)}\n`
+        // 02 mode `quilt`: a folder holding one file, .quilt-pointer, with the pointer record.
+        // With the target's git sha (its translation table), a gitlink to it, as git had it.
+        else if (c.mode === 'quilt' && c.git_sha) s += `M 160000 ${c.git_sha} ${fiPath(c.path)}\n`
+        else if (c.mode === 'quilt') s += `M 100644 :${blobMark.get(c.blob)} ${fiPath(`${c.path}/.quilt-pointer`)}\n`
         else s += `M ${MODES[c.mode || 'file'] || MODES.file} :${blobMark.get(c.blob)} ${fiPath(c.path)}\n`
       }
       await send(s + '\n')
@@ -115,6 +133,12 @@ export async function exportGit (client, { q, dir, line = 'main', branch, page =
     await fi.done()
     const marks = new Map(fs.readFileSync(marksFile, 'utf8').split('\n').filter(Boolean).map((l) => { const [m, h] = l.split(' '); return [Number(m.slice(1)), h] }))
     fs.rmSync(marksFile, { force: true })
+    if (sign) {
+      const olds = r.patches.map((p) => marks.get(commitMark.get(p.patch_no)))
+      const signed = signCommits(dir, olds, sign, GIT_ENV)
+      r.patches.forEach((p, i) => marks.set(commitMark.get(p.patch_no), signed[i]))
+      git(dir, ['update-ref', `refs/heads/${branch}`, signed[signed.length - 1], olds[olds.length - 1]])
+    }
     const lines = r.patches.map((p) => `${line} ${p.patch_no} ${marks.get(commitMark.get(p.patch_no))}`)
     fs.appendFileSync(shaFile, lines.join('\n') + '\n')
     const last = r.patches[r.patches.length - 1]

package/lib/quilts/export-lfs.js

@@ -0,0 +1,52 @@
+// Git LFS on the export to a remote (plans/quilt-source-control/14, Export: settings.export.lfs).
+// A file over `threshold_bytes`, or whose path a `filter=lfs` line of the exported tree's root
+// `.gitattributes` names, is written to git as an LFS pointer, and its bytes go to the LFS store
+// at `url` through the batch API (upload, then verify when asked). Without `lfs`, nothing changes.
+import crypto from 'node:crypto'
+import ignore from 'ignore'
+
+export const LFS_THRESHOLD = 50 * 1024 * 1024
+
+/** The pointer git keeps for `bytes`: { oid, size, text }. */
+export function lfsPointer (bytes) {
+  const oid = crypto.createHash('sha256').update(bytes).digest('hex')
+  return { oid, size: bytes.length, text: `version https://git-lfs.github.com/spec/v1\noid sha256:${oid}\nsize ${bytes.length}\n` }
+}
+
+/** A matcher for the `filter=lfs` patterns of a `.gitattributes` text (null when it names none). */
+export function lfsPatterns (text) {
+  const pats = String(text || '').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+    .map((l) => l.split(/\s+/)).filter(([, ...attrs]) => attrs.includes('filter=lfs')).map(([p]) => p)
+  return pats.length ? ignore().add(pats) : null
+}
+
+/**
+ * The uploader for `lfs` ({ url, threshold_bytes? }): upload(bytes) stores them at the LFS endpoint
+ * `url` (…/info/lfs) signed in with `secret` (a token, or user:password), and resolves the pointer.
+ */
+export function lfsUploader ({ url, secret = null, fetch = globalThis.fetch }) {
+  const base = String(url).replace(/\/+$/, '')
+  const auth = secret ? { authorization: `Basic ${Buffer.from(secret.includes(':') ? secret : `x-access-token:${secret}`).toString('base64')}` } : {}
+  const json = { accept: 'application/vnd.git-lfs+json', 'content-type': 'application/vnd.git-lfs+json' }
+  const done = new Set()
+  return async function upload (bytes) {
+    const p = lfsPointer(bytes)
+    if (done.has(p.oid)) return p.text
+    const res = await fetch(`${base}/objects/batch`, { method: 'POST', headers: { ...json, ...auth }, body: JSON.stringify({ operation: 'upload', transfers: ['basic'], objects: [{ oid: p.oid, size: p.size }] }) })
+    if (!res.ok) throw new Error(`Git LFS at ${base} answered ${res.status}`)
+    const o = ((await res.json().catch(() => ({}))).objects || [])[0] || {}
+    if (o.error) throw new Error(`Git LFS: ${o.error.message || o.error.code}`)
+    const up = o.actions?.upload
+    if (up?.href) {
+      const r = await fetch(up.href, { method: 'PUT', headers: { 'content-type': 'application/octet-stream', ...(up.header || {}) }, body: bytes })
+      if (!r.ok) throw new Error(`Git LFS upload answered ${r.status}`)
+    }
+    const verify = o.actions?.verify
+    if (verify?.href) {
+      const r = await fetch(verify.href, { method: 'POST', headers: { ...json, ...(verify.header || {}) }, body: JSON.stringify({ oid: p.oid, size: p.size }) })
+      if (!r.ok) throw new Error(`Git LFS verify answered ${r.status}`)
+    }
+    done.add(p.oid)
+    return p.text
+  }
+}

package/lib/quilts/export-sign.js

@@ -0,0 +1,49 @@
+// Signing of exported commits (plans/quilt-source-control/14, Export: "signature"): an SSH
+// signature (SSHSIG, namespace `git`) with the quilt's export key, Ed25519, whose signatures are
+// deterministic for a fixed key and message, so the same patch still gives the same commit id.
+// The key is derived from the service's secret (SEAM_EXPORT_SIGNING_SECRET) and the quilt id with
+// HKDF: nothing to store, one key per quilt. Off when no secret is set (it changes every sha).
+import crypto from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+
+const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex')
+const str = (b) => { b = Buffer.from(b); const n = Buffer.alloc(4); n.writeUInt32BE(b.length); return Buffer.concat([n, b]) }
+
+/** The quilt's export key: { privateKey, publicKey: 'ssh-ed25519 AAAA… seam-export:<quilt>' }. */
+export function exportKey (secret, quiltId) {
+  const seed = Buffer.from(crypto.hkdfSync('sha256', String(secret), 'seam-export-key', String(quiltId), 32))
+  const privateKey = crypto.createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, seed]), format: 'der', type: 'pkcs8' })
+  const raw = Buffer.from(crypto.createPublicKey(privateKey).export({ format: 'jwk' }).x, 'base64url')
+  const blob = Buffer.concat([str('ssh-ed25519'), str(raw)])
+  return { privateKey, blob, publicKey: `ssh-ed25519 ${blob.toString('base64')} seam-export:${quiltId}` }
+}
+
+/** An armored SSH signature of `bytes` (what `ssh-keygen -Y sign -n git` writes). */
+export function sshsig (bytes, key) {
+  const signed = Buffer.concat([Buffer.from('SSHSIG'), str('git'), str(''), str('sha512'), str(crypto.createHash('sha512').update(bytes).digest())])
+  const sig = Buffer.concat([str('ssh-ed25519'), str(crypto.sign(null, signed, key.privateKey))])
+  const n = Buffer.alloc(4); n.writeUInt32BE(1)
+  const body = Buffer.concat([Buffer.from('SSHSIG'), n, str(key.blob), str('git'), str(''), str('sha512'), str(sig)]).toString('base64')
+  return ['-----BEGIN SSH SIGNATURE-----', ...body.match(/.{1,70}/g), '-----END SSH SIGNATURE-----'].join('\n')
+}
+
+/**
+ * Rewrites `shas` (fast-import's commits, oldest first, each the child of the one before) as signed
+ * commits: each parent that was rewritten is replaced, then the `gpgsig` header goes after the
+ * committer. Returns the signed shas in the same order.
+ */
+export function signCommits (dir, shas, key, env) {
+  const run = (args, input) => execFileSync('git', ['-C', dir, ...args], { env, input, maxBuffer: 256 * 1024 * 1024 })
+  const map = new Map()
+  return shas.map((old) => {
+    const raw = run(['cat-file', 'commit', old]).toString('utf8')
+    const cut = raw.indexOf('\n\n')
+    const head = raw.slice(0, cut).split('\n').map((l) => (l.startsWith('parent ') && map.has(l.slice(7)) ? `parent ${map.get(l.slice(7))}` : l))
+    const unsigned = head.join('\n') + raw.slice(cut)
+    const at = head.findIndex((l) => l.startsWith('committer ')) + 1
+    head.splice(at, 0, 'gpgsig ' + sshsig(Buffer.from(unsigned, 'utf8'), key).split('\n').join('\n '))
+    const sha = run(['hash-object', '-t', 'commit', '-w', '--stdin'], head.join('\n') + raw.slice(cut)).toString().trim()
+    map.set(old, sha)
+    return sha
+  })
+}

package/lib/quilts/fastcdc.js

@@ -0,0 +1,186 @@
+// FastCDC content-defined chunking (plans/quilt-source-control/03, "FastCDC parameters"): files
+// over 1 MiB are cut where the bytes say, not at fixed offsets, so an edited binary or an
+// appended dataset shares all but its changed chunks with its previous version. Every client and
+// the server must cut identically, so everything here is part of the format, "quilt cdc v1":
+//
+// - Gear table: 256 values of 48 bits, the first 1,536 bytes BLAKE3 derives under the context
+//   "quilt cdc v1" from the bytes "gear", 6 bytes each, big-endian.
+// - Rolling hash: h = (2h + gear[byte]) mod 2^48, so each bit of h depends on at most the last 48
+//   bytes (the 48-byte window). Kept exactly in a double, no BigInt.
+// - Normalised chunking, two levels: no cut before 16 KiB (the hash starts there); from 16 KiB to
+//   64 KiB a cut needs the 18 bits of MASK_S clear, from 64 KiB to 256 KiB the 14 bits of MASK_L;
+//   a chunk never passes 256 KiB. Both masks sit in bits 16..47 of h, spread evenly (zero-padded).
+// - Chunk id: idOf('chunk', bytes), BLAKE3 under "quilt chunk v1".
+//
+// A manifest (02, 03) lists a chunked file's chunks as (chunk id, size), CBOR { v: 1, c: [[id,
+// size], …] }, at most MANIFEST_MAX entries. A file with more chunks has a root manifest
+// { v: 1, m: [[child manifest id, bytes it covers], …] } over leaf manifests: two levels cover
+// 16,384² chunks, far past the 500 GiB file limit. Manifest id: idOf('manifest', bytes).
+import { blake3 } from '@noble/hashes/blake3.js'
+import { idOf, idBytes } from './hash.js'
+import { encode, decode } from './cbor.js'
+
+export const CDC_MIN = 16 * 1024
+export const CDC_AVG = 64 * 1024
+export const CDC_MAX = 256 * 1024
+/** Files at or under this size are stored whole, never chunked (03 Blob encodings). */
+export const CDC_THRESHOLD = 1024 * 1024
+
+const TWO48 = 2 ** 48
+const GEAR = (() => {
+  const raw = blake3(new TextEncoder().encode('gear'), { context: new TextEncoder().encode('quilt cdc v1'), dkLen: 256 * 6 })
+  const g = new Float64Array(256)
+  for (let i = 0; i < 256; i++) { let v = 0; for (let j = 0; j < 6; j++) v = v * 256 + raw[i * 6 + j]; g[i] = v }
+  return g
+})()
+
+// `bits` one-bits spread evenly over the 32 bits 16..47 of h, as a mask on hi = floor(h / 2^16).
+function spread (bits) {
+  let m = 0
+  for (let i = 0; i < bits; i++) m |= 1 << Math.floor(i * 32 / bits)
+  return m >>> 0
+}
+export const MASK_S = spread(18)
+export const MASK_L = spread(14)
+
+/** Where the first chunk of `bytes` ends: an offset in (0, min(len, CDC_MAX)]. */
+export function cutPoint (bytes, start = 0, end = bytes.length) {
+  const n = end - start
+  if (n <= CDC_MIN) return n
+  const max = Math.min(n, CDC_MAX)
+  const normal = Math.min(n, CDC_AVG)
+  let h = 0
+  let i = CDC_MIN
+  for (; i < normal; i++) {
+    h = h * 2 + GEAR[bytes[start + i]]; if (h >= TWO48) { h -= TWO48; if (h >= TWO48) h -= TWO48 }
+    if ((Math.floor(h / 65536) & MASK_S) === 0) return i + 1
+  }
+  for (; i < max; i++) {
+    h = h * 2 + GEAR[bytes[start + i]]; if (h >= TWO48) { h -= TWO48; if (h >= TWO48) h -= TWO48 }
+    if ((Math.floor(h / 65536) & MASK_L) === 0) return i + 1
+  }
+  return max
+}
+
+/** The chunks of a whole buffer: [{ id, offset, size }], in order, covering every byte. */
+export function chunksOf (bytes) {
+  const out = []
+  for (let off = 0; off < bytes.length;) {
+    const size = cutPoint(bytes, off)
+    out.push({ id: idOf('chunk', bytes.subarray(off, off + size)), offset: off, size })
+    off += size
+  }
+  return out
+}
+
+/**
+ * The chunks of a stream of byte pieces (an async or sync iterable of Uint8Array), for files too
+ * large to hold: yields { id, offset, size, bytes } with the same cuts chunksOf would make.
+ */
+export async function * chunkStream (pieces) {
+  let buf = new Uint8Array(0)
+  let offset = 0
+  for await (const piece of pieces) {
+    const next = new Uint8Array(buf.length + piece.length)
+    next.set(buf); next.set(piece, buf.length)
+    buf = next
+    // A cut is final once CDC_MAX bytes are held: no later byte can move it.
+    let at = 0
+    while (buf.length - at >= CDC_MAX) {
+      const size = cutPoint(buf, at)
+      const bytes = buf.slice(at, at + size)
+      yield { id: idOf('chunk', bytes), offset, size, bytes }
+      offset += size; at += size
+    }
+    if (at) buf = buf.slice(at)
+  }
+  for (let at = 0; at < buf.length;) {
+    const size = cutPoint(buf, at)
+    const bytes = buf.slice(at, at + size)
+    yield { id: idOf('chunk', bytes), offset, size, bytes }
+    offset += size; at += size
+  }
+}
+
+export const MANIFEST_MAX = 16384
+const hex = (b) => Buffer.from(b).toString('hex')
+
+/**
+ * The manifests of a file's chunks ([{ id, size }] in order): { id, bytes, manifests }, where
+ * `id` and `bytes` are the root's and `manifests` is every manifest to store, root last.
+ */
+export function manifestsOf (chunks) {
+  const leaf = (cs) => encode({ v: 1, c: cs.map((c) => [idBytes(c.id), c.size]) })
+  if (chunks.length <= MANIFEST_MAX) {
+    const bytes = leaf(chunks)
+    const m = { id: idOf('manifest', bytes), bytes }
+    return { ...m, manifests: [m] }
+  }
+  if (chunks.length > MANIFEST_MAX * MANIFEST_MAX) throw new Error('file_too_large: more chunks than two manifest levels hold')
+  const children = []
+  for (let i = 0; i < chunks.length; i += MANIFEST_MAX) {
+    const part = chunks.slice(i, i + MANIFEST_MAX)
+    const bytes = leaf(part)
+    children.push({ id: idOf('manifest', bytes), bytes, size: part.reduce((n, c) => n + c.size, 0) })
+  }
+  const bytes = encode({ v: 1, m: children.map((c) => [idBytes(c.id), c.size]) })
+  const root = { id: idOf('manifest', bytes), bytes }
+  return { ...root, manifests: [...children.map(({ id, bytes }) => ({ id, bytes })), root] }
+}
+
+/**
+ * manifestsOf for a file cut as a stream (10, streaming the cut): chunks go in one at a time and
+ * only one leaf's ids and sizes are held. add(chunk) answers a finished leaf manifest ({ id, bytes })
+ * to store once its 16,384 chunks are in, else null; finish() answers what manifestsOf would, with
+ * `manifests` the ones not yet handed out (the last leaf and the root, or the single leaf). The
+ * bytes and ids are exactly manifestsOf's.
+ */
+export function manifestBuilder () {
+  const leaf = (cs) => encode({ v: 1, c: cs.map((c) => [idBytes(c.id), c.size]) })
+  let part = []; let partSize = 0; let count = 0
+  const children = []
+  return {
+    add (c) {
+      if (++count > MANIFEST_MAX * MANIFEST_MAX) throw new Error('file_too_large: more chunks than two manifest levels hold')
+      let done = null
+      if (part.length === MANIFEST_MAX) {
+        const bytes = leaf(part)
+        done = { id: idOf('manifest', bytes), bytes }
+        children.push({ id: done.id, size: partSize }); part = []; partSize = 0
+      }
+      part.push({ id: c.id, size: c.size }); partSize += c.size
+      return done
+    },
+    finish () {
+      const bytes = leaf(part)
+      const last = { id: idOf('manifest', bytes), bytes }
+      if (!children.length) return { ...last, manifests: [last] }
+      const rootBytes = encode({ v: 1, m: [...children, { id: last.id, size: partSize }].map((c) => [idBytes(c.id), c.size]) })
+      const root = { id: idOf('manifest', rootBytes), bytes: rootBytes }
+      return { ...root, manifests: [last, root] }
+    }
+  }
+}
+
+/** A manifest's entries: { chunks: [{ id, size }] } for a leaf, { children: [{ id, size }] } for a root. */
+export function decodeManifest (bytes) {
+  const r = decode(bytes)
+  if (!r || r.v !== 1 || (!Array.isArray(r.c) && !Array.isArray(r.m))) throw new Error('bad manifest')
+  const entries = (r.c || r.m).map(([id, size]) => ({ id: hex(id), size }))
+  return r.c ? { chunks: entries } : { children: entries }
+}
+
+/**
+ * A large file as a client uploads it (10, 03 "Chunk dedup"): pack entries for its chunks, its
+ * manifests (root included, so dedup finds it) and a `chunked` entry, the root manifest under the
+ * file's own id, last. A client asks `have` for the chunk ids and leaves out the ones the quilt holds.
+ */
+export function chunkedEntries (bytes) {
+  const file = Buffer.from(bytes)
+  const chunks = chunksOf(file)
+  const m = manifestsOf(chunks)
+  const out = new Map()
+  for (const c of chunks) if (!out.has(c.id)) out.set(c.id, { kind: 'chunk', id: c.id, bytes: file.subarray(c.offset, c.offset + c.size) })
+  for (const x of m.manifests) if (!out.has(x.id)) out.set(x.id, { kind: 'manifest', id: x.id, bytes: x.bytes })
+  return [...out.values(), { kind: 'chunked', id: idOf('blob', file), bytes: m.bytes }]
+}

package/lib/quilts/hash.js

@@ -13,11 +13,11 @@ function context (kind) {
   return c
 }
 
-export const KINDS = ['commit', 'blob', 'tree', 'chunk', 'pack', 'term', 'manifest']
+export const KINDS = ['commit', 'blob', 'tree', 'chunk', 'pack', 'term', 'manifest', 'dict']
 
 /** The id of `bytes` as an object of `kind`: BLAKE3 derive-key mode, 32 bytes, as hex. */
 // Not object kinds: keys made with their own contexts so they can never equal an object id.
-const KEY_KINDS = ['idempotency', 'resolution']
+const KEY_KINDS = ['idempotency', 'resolution', 'resolution-hunk']
 
 /** A key (not an object id) in its own context, e.g. 'idempotency' → "quilt idempotency v1". */
 export function keyOf (kind, bytes) {
@@ -30,6 +30,21 @@ export function idOf (kind, bytes) {
   return Buffer.from(blake3(bytes, { context: context(kind) })).toString('hex')
 }
 
+/**
+ * idOf(kind, …) computed piece by piece, for bytes too large to hold at once (10, streaming the
+ * cut): update(piece) as the pieces come, then digest() is the hex id of all of them in order.
+ */
+export function idHasher (kind) {
+  if (!KINDS.includes(kind)) throw new Error(`unknown object kind ${kind}`)
+  const h = blake3.create({ context: context(kind) })
+  let size = 0
+  return {
+    update (piece) { h.update(piece); size += piece.length; return this },
+    get size () { return size },
+    digest: () => Buffer.from(h.digest()).toString('hex')
+  }
+}
+
 export const ID = /^[0-9a-f]{64}$/
 
 /** Whether `s` looks like an id (64 lowercase hex). */