@volter/world-core 2.0.0

package/src/git/history.ts

@@ -0,0 +1,177 @@
+// HISTORY AND DIFF: what a hosting twin's REST plane asks of the object store beyond raw reads —
+// the merge base of two commits, the changed-file list between two commits with GitHub's
+// three-dot semantics (merge-base(base, head)..head), per-file addition/deletion counts and a
+// unified patch from a Myers line diff. Pure functions of the store; the `git` binary is the
+// oracle these were proven against, never a dependency.
+import { GitObjectStore, decodeCommit, decodeTree, type TreeEntry } from './objects.ts';
+
+async function parentsOf(store: GitObjectStore, sha: string): Promise<string[]> { const o = await store.read(sha); return o?.type === 'commit' ? decodeCommit(o.payload).parents : []; }
+
+/** Ancestors of `sha` (inclusive), bounded. */
+async function ancestors(store: GitObjectStore, sha: string, limit: number): Promise<Set<string>> {
+  const seen = new Set<string>(); const stack = [sha];
+  while (stack.length && seen.size < limit) { const s = stack.pop()!; if (seen.has(s)) continue; seen.add(s); stack.push(...(await parentsOf(store, s))); }
+  return seen;
+}
+/** A best common ancestor of `a` and `b` (one that is not an ancestor of another common ancestor), or null. */
+export async function mergeBase(store: GitObjectStore, a: string, b: string, limit = 20000): Promise<string | null> {
+  if (!(await store.has(a)) || !(await store.has(b))) return null;
+  const ofA = await ancestors(store, a, limit);
+  // BFS from b in parent order: the first commits reached that lie in A's ancestry are candidates; a
+  // candidate reached through another candidate is dominated and dropped.
+  const candidates: string[] = []; const seen = new Set<string>(); const queue = [b];
+  while (queue.length && seen.size < limit) {
+    const s = queue.shift()!; if (seen.has(s)) continue; seen.add(s);
+    if (ofA.has(s)) { candidates.push(s); continue; }
+    queue.push(...(await parentsOf(store, s)));
+  }
+  if (candidates.length === 0) return null;
+  if (candidates.length === 1) return candidates[0]!;
+  const dominated = new Set<string>();
+  for (const c of candidates) { const anc = await ancestors(store, c, limit); for (const d of candidates) if (d !== c && anc.has(d)) dominated.add(d); }
+  return candidates.find((c) => !dominated.has(c)) ?? candidates[0]!;
+}
+
+export type TreeChange = { path: string; status: 'added' | 'removed' | 'modified'; oldSha?: string; newSha?: string; oldMode?: string; newMode?: string };
+async function treeOf(store: GitObjectStore, sha: string): Promise<TreeEntry[]> {
+  const o = await store.read(sha); if (!o) return [];
+  if (o.type === 'commit') return treeOf(store, decodeCommit(o.payload).tree);
+  return o.type === 'tree' ? decodeTree(o.payload) : [];
+}
+const isDir = (m: string) => m === '40000' || m === '040000';
+/** Recursive tree compare between two commits or trees (paths in the post-image order, no rename pairing — like `diff-tree -r` without -M). */
+export async function diffTrees(store: GitObjectStore, from: string | null, to: string, prefix = ''): Promise<TreeChange[]> {
+  const a = from ? await treeOf(store, from) : []; const b = await treeOf(store, to);
+  const byName = new Map(a.map((e) => [e.name, e])); const out: TreeChange[] = []; const seenNames = new Set<string>();
+  const all = [...a.map((e) => e.name), ...b.map((e) => e.name)].filter((n) => (seenNames.has(n) ? false : (seenNames.add(n), true))).sort();
+  const bByName = new Map(b.map((e) => [e.name, e]));
+  for (const name of all) {
+    const ax = byName.get(name), by = bByName.get(name); const path = prefix + name;
+    if (ax && by && ax.sha === by.sha && ax.mode === by.mode) continue;
+    const xd = ax ? isDir(ax.mode) : false, yd = by ? isDir(by.mode) : false;
+    if (xd || yd) {
+      if (xd && yd) out.push(...(await diffTrees(store, ax!.sha, by!.sha, `${path}/`)));
+      else { if (xd) out.push(...(await diffTrees(store, ax!.sha, '4b825dc642cb6eb9a060e54bf8d69288fbee4904', `${path}/`)).map((c) => ({ ...c }))); else if (ax) out.push({ path, status: 'removed', oldSha: ax.sha, oldMode: ax.mode }); if (yd) out.push(...(await diffTrees(store, null, by!.sha, `${path}/`))); else if (by) out.push({ path, status: 'added', newSha: by.sha, newMode: by.mode }); }
+      continue;
+    }
+    if (ax && by) out.push({ path, status: 'modified', oldSha: ax.sha, newSha: by.sha, oldMode: ax.mode, newMode: by.mode });
+    else if (ax) out.push({ path, status: 'removed', oldSha: ax.sha, oldMode: ax.mode });
+    else if (by) out.push({ path, status: 'added', newSha: by.sha, newMode: by.mode });
+  }
+  return out;
+}
+
+// ── Myers line diff ─────────────────────────────────────────────────────────────────────
+export type Edit = { kind: ' ' | '-' | '+'; line: string };
+function splitLines(text: string): string[] { if (text === '') return []; const lines = text.split('\n'); if (lines[lines.length - 1] === '') lines.pop(); return lines; }
+/** A shortest edit script between two texts (Myers, O((N+M)D)). */
+export function lineDiff(oldText: string, newText: string): Edit[] {
+  const a = splitLines(oldText), b = splitLines(newText); const n = a.length, m = b.length; const max = n + m;
+  const v = new Map<number, number>([[1, 0]]); const trace: Map<number, number>[] = [];
+  outer: for (let d = 0; d <= max; d++) {
+    trace.push(new Map(v));
+    for (let k = -d; k <= d; k += 2) {
+      let ax = k === -d || (k !== d && (v.get(k - 1) ?? 0) < (v.get(k + 1) ?? 0)) ? (v.get(k + 1) ?? 0) : (v.get(k - 1) ?? 0) + 1;
+      let by = ax - k;
+      while (ax < n && by < m && a[ax] === b[by]) { ax++; by++; }
+      v.set(k, ax);
+      if (ax >= n && by >= m) break outer;
+    }
+  }
+  const edits: Edit[] = []; let ax = n, by = m;
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const vv = trace[d]!; const k = ax - by;
+    const prevK = k === -d || (k !== d && (vv.get(k - 1) ?? 0) < (vv.get(k + 1) ?? 0)) ? k + 1 : k - 1;
+    const prevX = vv.get(prevK) ?? 0; const prevY = prevX - prevK;
+    while (ax > prevX && by > prevY) { edits.push({ kind: ' ', line: a[ax - 1]! }); ax--; by--; }
+    if (d > 0) { if (ax === prevX) { edits.push({ kind: '+', line: b[by - 1]! }); by--; } else { edits.push({ kind: '-', line: a[ax - 1]! }); ax--; } }
+  }
+  return edits.reverse();
+}
+/** The unified-diff hunks (the body GitHub serves as a file's `patch`), 3 lines of context. */
+export function unifiedPatch(oldText: string, newText: string, context = 3): string {
+  const edits = lineDiff(oldText, newText); if (!edits.some((e) => e.kind !== ' ')) return '';
+  const oldNoNl = oldText !== '' && !oldText.endsWith('\n'), newNoNl = newText !== '' && !newText.endsWith('\n');
+  const oldLines = splitLines(oldText).length, newLines = splitLines(newText).length;
+  // group edits into hunks: a run of changes with up to `context` unchanged lines around it
+  const hunks: Array<{ start: number; end: number }> = []; let i = 0;
+  while (i < edits.length) {
+    if (edits[i]!.kind === ' ') { i++; continue; }
+    const start = Math.max(0, i - context); let end = i;
+    while (end < edits.length) { if (edits[end]!.kind !== ' ') { end++; continue; } let run = end; while (run < edits.length && edits[run]!.kind === ' ') run++; if (run - end > context * 2 || run >= edits.length) { end = Math.min(edits.length, end + context); break; } end = run; }
+    hunks.push({ start, end }); i = end;
+  }
+  let oldPos = 0, newPos = 0, out = ''; let cursor = 0;
+  for (const h of hunks) {
+    for (; cursor < h.start; cursor++) { const e = edits[cursor]!; if (e.kind !== '+') oldPos++; if (e.kind !== '-') newPos++; }
+    let oc = 0, nc = 0, body = '';
+    for (let j = h.start; j < h.end; j++) {
+      const e = edits[j]!; body += `${e.kind}${e.line}\n`;
+      const lastOld = e.kind !== '+' && oldPos + oc === oldLines - 1, lastNew = e.kind !== '-' && newPos + nc === newLines - 1;
+      if (e.kind !== '+') oc++; if (e.kind !== '-') nc++;
+      if ((e.kind === '-' && lastOld && oldNoNl) || (e.kind === '+' && lastNew && newNoNl) || (e.kind === ' ' && lastOld && oldNoNl && lastNew && newNoNl)) body += '\\n';
+    }
+    const range = (p: number, c: number) => (c === 1 ? `${p + 1}` : `${c === 0 ? p : p + 1},${c}`);
+    out += `@@ -${range(oldPos, oc)} +${range(newPos, nc)} @@\n${body}`;
+    oldPos += oc; newPos += nc; cursor = h.end;
+  }
+  return out.replace(/\n$/, '');
+}
+
+export type DiffFile = { filename: string; status: 'added' | 'removed' | 'modified'; additions: number; deletions: number; sha?: string; patch?: string };
+const DEC = new TextDecoder();
+function looksBinary(bytes: Uint8Array): boolean { const n = Math.min(bytes.length, 8000); for (let i = 0; i < n; i++) if (bytes[i] === 0) return true; return false; }
+/** GitHub's file list between `base` and `head` (three-dot: from merge-base(base, head), or base when histories are unrelated), with counts and patches. */
+export async function diffFiles(store: GitObjectStore, baseSha: string, headSha: string, opts: { patch?: boolean } = {}): Promise<DiffFile[] | null> {
+  if (!(await store.has(baseSha)) || !(await store.has(headSha))) return null;
+  const from = (await mergeBase(store, baseSha, headSha)) ?? baseSha;
+  const out: DiffFile[] = [];
+  for (const c of await diffTrees(store, from, headSha)) {
+    const oldB = c.oldSha ? (await store.read(c.oldSha))?.payload ?? new Uint8Array() : new Uint8Array();
+    const newB = c.newSha ? (await store.read(c.newSha))?.payload ?? new Uint8Array() : new Uint8Array();
+    const file: DiffFile = { filename: c.path, status: c.status, additions: 0, deletions: 0, ...(c.newSha ? { sha: c.newSha } : {}) };
+    if (!looksBinary(oldB) && !looksBinary(newB)) {
+      const oldT = DEC.decode(oldB), newT = DEC.decode(newB); const edits = lineDiff(oldT, newT);
+      file.additions = edits.filter((e) => e.kind === '+').length; file.deletions = edits.filter((e) => e.kind === '-').length;
+      if (opts.patch) { const p = unifiedPatch(oldT, newT); if (p) file.patch = p; }
+    }
+    out.push(file);
+  }
+  return out;
+}
+
+/** Three-way line merge. Return null for overlapping edits; preserve exact line endings.
+ * Binary payloads belong to the caller's conflict path, never a text decoder's replacement. */
+export function mergeText(base: string, ours: string, theirs: string): string | null {
+  if (ours === theirs || theirs === base) return ours;
+  if (ours === base) return theirs;
+  type Hunk = { start: number; end: number; lines: string[] };
+  // Encode whole lines, including their terminators, before diffing. Thus changing the final
+  // newline is a real edit and CRLF bytes survive without a separate post-merge guess.
+  const lines = (text: string): string[] => (text.match(/[^\n]*\n|[^\n]+$/g) ?? []).map(s => JSON.stringify(s));
+  const original = lines(base);
+  const changes = (text: string): Hunk[] => {
+    const out: Hunk[] = []; let cursor = 0; let hunk: Hunk | undefined;
+    for (const edit of lineDiff(original.join('\n'), lines(text).join('\n'))) {
+      if (edit.kind === ' ') { hunk = undefined; cursor++; continue; }
+      if (!hunk) { hunk = { start: cursor, end: cursor, lines: [] }; out.push(hunk); }
+      if (edit.kind === '-') { cursor++; hunk.end++; } else hunk.lines.push(edit.line);
+    }
+    return out;
+  };
+  const left = changes(ours), right = changes(theirs);
+  const identical = (a: Hunk, b: Hunk) => a.start === b.start && a.end === b.end && JSON.stringify(a.lines) === JSON.stringify(b.lines);
+  const edits = [...left];
+  for (const b of right) {
+    if (left.some(a => identical(a, b))) continue;
+    for (const a of left) {
+      // Two insertions at one point or touching changed intervals have ambiguous order.
+      if (a.start <= b.end && b.start <= a.end) return null;
+    }
+    edits.push(b);
+  }
+  edits.sort((a, b) => b.start - a.start);
+  const result = [...original];
+  for (const h of edits) result.splice(h.start, h.end - h.start, ...h.lines);
+  return result.map(line => JSON.parse(line) as string).join('');
+}

package/src/git/index.ts

@@ -0,0 +1,6 @@
+export * from './inflate.ts';
+export * from './objects.ts';
+export * from './pack.ts';
+export * from './refs.ts';
+export * from './smart-http.ts';
+export * from './history.ts';

package/src/git/inflate.ts

@@ -0,0 +1,125 @@
+// A pure-JS zlib INFLATE that reports the bytes it consumed — the one thing the standard
+// DecompressionStream cannot say, and the one thing a packfile reader must know (each object's
+// zlib stream is followed by the next object's header with no length in between). Stored,
+// fixed-Huffman and dynamic-Huffman blocks (RFC 1951) inside a zlib wrapper (RFC 1950: a 2-byte
+// header, an Adler-32 trailer). No dependency; runs on Bun and workerd alike.
+
+const LENGTH_BASE = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258];
+const LENGTH_EXTRA = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0];
+const DIST_BASE = [1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577];
+const DIST_EXTRA = [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13];
+const CL_ORDER = [16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15];
+
+type Huffman = { counts: Uint16Array; symbols: Uint16Array };
+
+function buildHuffman(lengths: Uint8Array | number[], n: number): Huffman {
+  const counts = new Uint16Array(16); const symbols = new Uint16Array(n);
+  for (let i = 0; i < n; i++) counts[lengths[i]!]!++;
+  counts[0] = 0;
+  const offs = new Uint16Array(16);
+  for (let i = 1; i < 16; i++) offs[i] = offs[i - 1]! + counts[i - 1]!;
+  for (let i = 0; i < n; i++) if (lengths[i]) symbols[offs[lengths[i]!]!++] = i;
+  return { counts, symbols };
+}
+
+class BitReader {
+  pos: number; bitBuf = 0; bitCount = 0;
+  constructor(readonly input: Uint8Array, offset: number) { this.pos = offset; }
+  bit(): number {
+    if (this.bitCount === 0) { if (this.pos >= this.input.length) throw new Error('inflate: unexpected end of input'); this.bitBuf = this.input[this.pos++]!; this.bitCount = 8; }
+    const b = this.bitBuf & 1; this.bitBuf >>>= 1; this.bitCount--; return b;
+  }
+  bits(n: number): number { let v = 0; for (let i = 0; i < n; i++) v |= this.bit() << i; return v; }
+  symbol(h: Huffman): number {
+    let code = 0, first = 0, index = 0;
+    for (let len = 1; len < 16; len++) {
+      code |= this.bit(); const count = h.counts[len]!;
+      if (code - count < first) return h.symbols[index + (code - first)]!;
+      index += count; first += count; first <<= 1; code <<= 1;
+    }
+    throw new Error('inflate: bad huffman code');
+  }
+  alignByte(): void { this.bitBuf = 0; this.bitCount = 0; }
+}
+
+class Out {
+  buf = new Uint8Array(1 << 16); len = 0;
+  push(b: number): void { if (this.len === this.buf.length) { const n = new Uint8Array(this.buf.length * 2); n.set(this.buf); this.buf = n; } this.buf[this.len++] = b; }
+  copy(dist: number, length: number): void { if (dist > this.len) throw new Error('inflate: distance too far back'); for (let i = 0; i < length; i++) this.push(this.buf[this.len - dist]!); }
+  // A right-sized copy: a view would pin the whole (>= 64 KiB, doubling) scratch buffer behind
+  // every inflated object, which is what a 105k-object push cost the github twin (~7 GB).
+  bytes(): Uint8Array { return this.buf.slice(0, this.len); }
+}
+
+let FIXED: { lit: Huffman; dist: Huffman } | undefined;
+function fixedTables(): { lit: Huffman; dist: Huffman } {
+  if (FIXED) return FIXED;
+  const l = new Uint8Array(288); for (let i = 0; i < 144; i++) l[i] = 8; for (let i = 144; i < 256; i++) l[i] = 9; for (let i = 256; i < 280; i++) l[i] = 7; for (let i = 280; i < 288; i++) l[i] = 8;
+  const d = new Uint8Array(30).fill(5);
+  FIXED = { lit: buildHuffman(l, 288), dist: buildHuffman(d, 30) }; return FIXED;
+}
+
+function inflateBlockData(r: BitReader, out: Out, lit: Huffman, dist: Huffman): void {
+  for (;;) {
+    const sym = r.symbol(lit);
+    if (sym < 256) out.push(sym);
+    else if (sym === 256) return;
+    else {
+      const li = sym - 257; if (li >= 29) throw new Error('inflate: bad length symbol');
+      const length = LENGTH_BASE[li]! + r.bits(LENGTH_EXTRA[li]!);
+      const di = r.symbol(dist); if (di >= 30) throw new Error('inflate: bad distance symbol');
+      out.copy(DIST_BASE[di]! + r.bits(DIST_EXTRA[di]!), length);
+    }
+  }
+}
+
+function inflateDynamic(r: BitReader, out: Out): void {
+  const hlit = r.bits(5) + 257, hdist = r.bits(5) + 1, hclen = r.bits(4) + 4;
+  const cl = new Uint8Array(19); for (let i = 0; i < hclen; i++) cl[CL_ORDER[i]!] = r.bits(3);
+  const clh = buildHuffman(cl, 19);
+  const lengths = new Uint8Array(hlit + hdist);
+  for (let i = 0; i < hlit + hdist;) {
+    const sym = r.symbol(clh);
+    if (sym < 16) lengths[i++] = sym;
+    else if (sym === 16) { if (i === 0) throw new Error('inflate: repeat with no previous length'); const prev = lengths[i - 1]!; for (let n = 3 + r.bits(2); n > 0; n--) lengths[i++] = prev; }
+    else if (sym === 17) { for (let n = 3 + r.bits(3); n > 0; n--) lengths[i++] = 0; }
+    else { for (let n = 11 + r.bits(7); n > 0; n--) lengths[i++] = 0; }
+  }
+  inflateBlockData(r, out, buildHuffman(lengths.subarray(0, hlit), hlit), buildHuffman(lengths.subarray(hlit), hdist));
+}
+
+/** Raw DEFLATE (RFC 1951) starting at `offset`: the bytes out and the input consumed. */
+export function inflateRaw(input: Uint8Array, offset = 0): { out: Uint8Array; consumed: number } {
+  const r = new BitReader(input, offset); const out = new Out();
+  let final = 0;
+  do {
+    final = r.bit(); const type = r.bits(2);
+    if (type === 0) {
+      r.alignByte();
+      const len = input[r.pos]! | (input[r.pos + 1]! << 8); const nlen = input[r.pos + 2]! | (input[r.pos + 3]! << 8);
+      if ((len ^ 0xffff) !== nlen) throw new Error('inflate: stored block length mismatch');
+      r.pos += 4; for (let i = 0; i < len; i++) out.push(input[r.pos++]!);
+    } else if (type === 1) { const t = fixedTables(); inflateBlockData(r, out, t.lit, t.dist); }
+    else if (type === 2) inflateDynamic(r, out);
+    else throw new Error('inflate: reserved block type');
+  } while (!final);
+  return { out: out.bytes(), consumed: r.pos - offset };
+}
+
+export function adler32(bytes: Uint8Array): number {
+  let a = 1, b = 0;
+  for (let i = 0; i < bytes.length; i++) { a = (a + bytes[i]!) % 65521; b = (b + a) % 65521; }
+  return ((b << 16) | a) >>> 0;
+}
+
+/** zlib (RFC 1950) starting at `offset`: header checked, Adler-32 verified, consumed includes both. */
+export function inflateZlib(input: Uint8Array, offset = 0): { out: Uint8Array; consumed: number } {
+  const cmf = input[offset]!, flg = input[offset + 1]!;
+  if ((cmf & 0x0f) !== 8 || ((cmf << 8) | flg) % 31 !== 0) throw new Error('inflate: not a zlib stream');
+  if (flg & 0x20) throw new Error('inflate: preset dictionary is not supported');
+  const { out, consumed } = inflateRaw(input, offset + 2);
+  const t = offset + 2 + consumed;
+  const expected = ((input[t]! << 24) | (input[t + 1]! << 16) | (input[t + 2]! << 8) | input[t + 3]!) >>> 0;
+  if (expected !== adler32(out)) throw new Error('inflate: adler32 mismatch');
+  return { out, consumed: consumed + 6 };
+}

package/src/git/objects.ts

@@ -0,0 +1,110 @@
+// GIT OBJECTS OVER THE BLOB SEAM (docs/contributing/architecture.md#the-engine-slot): loose objects — `<type>
+// <size>\0<payload>`, zlib-deflated, addressed by the SHA-1 of the uncompressed form — written
+// and read through the active BlobStore under `<prefix>/objects/<ab>/<rest>`, the exact layout
+// a bare repository keeps. Pure JS: SHA-1 through WebCrypto, loose objects stored uncompressed in zlib framing (storeZlib),
+// a pack deflated through the standard CompressionStream, inflate through ./inflate.ts (it reports consumed bytes, which a packfile
+// reader needs). Bun and workerd alike; no `git` binary anywhere.
+import { inflateZlib } from './inflate.ts';
+import type { BlobStore } from '../blob-store.ts';
+
+export type GitObjectType = 'commit' | 'tree' | 'blob' | 'tag';
+const ENC = new TextEncoder(); const DEC = new TextDecoder();
+
+export async function sha1Hex(bytes: Uint8Array): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer));
+  return [...digest].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+export function hexToBytes(hex: string): Uint8Array { const out = new Uint8Array(hex.length / 2); for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16); return out; }
+export function bytesToHex(b: Uint8Array): string { return [...b].map((byte) => byte.toString(16).padStart(2, '0')).join(''); }
+export function concat(...parts: Uint8Array[]): Uint8Array { const n = parts.reduce((s, p) => s + p.length, 0); const out = new Uint8Array(n); let o = 0; for (const p of parts) { out.set(p, o); o += p.length; } return out; }
+
+/** The loose-object form: header + payload (what the sha is computed over). */
+export function encodeLoose(type: GitObjectType, payload: Uint8Array): Uint8Array { return concat(ENC.encode(`${type} ${payload.length}\0`), payload); }
+export function decodeLoose(bytes: Uint8Array): { type: GitObjectType; payload: Uint8Array } {
+  const nul = bytes.indexOf(0); if (nul < 0) throw new Error('git object: no header');
+  const [type, size] = DEC.decode(bytes.subarray(0, nul)).split(' ');
+  const payload = bytes.subarray(nul + 1);
+  if (Number(size) !== payload.length) throw new Error(`git object: header says ${size} bytes, payload is ${payload.length}`);
+  return { type: type as GitObjectType, payload };
+}
+export async function hashObject(type: GitObjectType, payload: Uint8Array): Promise<string> { return sha1Hex(encodeLoose(type, payload)); }
+
+export async function deflateZlib(bytes: Uint8Array): Promise<Uint8Array> {
+  const cs = new CompressionStream('deflate'); const w = cs.writable.getWriter(); void w.write(new Uint8Array(bytes) as unknown as BufferSource); void w.close();
+  return new Uint8Array(await new Response(cs.readable).arrayBuffer());
+}
+
+/** zlib with stored (uncompressed) deflate blocks: what git writes at `core.compression 0`, and what every
+ *  inflater reads. A loose object is written on every commit a World makes; compressing each one through the
+ *  asynchronous CompressionStream made a write's cost the stream's round trips, not the object's size. */
+export function storeZlib(bytes: Uint8Array): Uint8Array {
+  const blocks = Math.max(1, Math.ceil(bytes.length / 0xffff));
+  const out = new Uint8Array(2 + bytes.length + blocks * 5 + 4);
+  out[0] = 0x78; out[1] = 0x01; let o = 2;
+  for (let b = 0; b < blocks; b++) {
+    const start = b * 0xffff; const len = Math.min(0xffff, bytes.length - start);
+    out[o++] = b === blocks - 1 ? 1 : 0; out[o++] = len & 0xff; out[o++] = len >>> 8; out[o++] = ~len & 0xff; out[o++] = (~len >>> 8) & 0xff;
+    out.set(bytes.subarray(start, start + len), o); o += len;
+  }
+  let a = 1; let d = 0;
+  for (let i = 0; i < bytes.length; i++) { a = (a + bytes[i]!) % 65521; d = (d + a) % 65521; }
+  const adler = ((d << 16) | a) >>> 0;
+  out[o++] = adler >>> 24; out[o++] = (adler >>> 16) & 0xff; out[o++] = (adler >>> 8) & 0xff; out[o++] = adler & 0xff;
+  return out;
+}
+
+/** The object store: one bare repo's objects under a key prefix in the blob seam. */
+export class GitObjectStore {
+  constructor(private readonly blobs: BlobStore, private readonly prefix: string) {}
+  key(sha: string): string { return `${this.prefix}/objects/${sha.slice(0, 2)}/${sha.slice(2)}`; }
+  async has(sha: string): Promise<boolean> { return this.blobs.exists(this.key(sha)); }
+  async write(type: GitObjectType, payload: Uint8Array): Promise<string> {
+    const loose = encodeLoose(type, payload); const sha = await sha1Hex(loose);
+    if (!(await this.blobs.exists(this.key(sha)))) await this.blobs.put(this.key(sha), storeZlib(loose));
+    return sha;
+  }
+  async read(sha: string): Promise<{ type: GitObjectType; payload: Uint8Array } | null> {
+    const z = await this.blobs.get(this.key(sha)); if (z === null) return null;
+    return decodeLoose(inflateZlib(z).out);
+  }
+}
+
+// ── codecs ──────────────────────────────────────────────────────────────────────────────
+export type TreeEntry = { mode: string; name: string; sha: string };
+/** git sorts tree entries by name, with a directory's name compared as if it ended in '/'. */
+export function sortTreeEntries(entries: TreeEntry[]): TreeEntry[] {
+  const k = (e: TreeEntry) => (e.mode === '40000' || e.mode === '040000' ? `${e.name}/` : e.name);
+  return [...entries].sort((a, b) => (k(a) < k(b) ? -1 : k(a) > k(b) ? 1 : 0));
+}
+export function encodeTree(entries: TreeEntry[]): Uint8Array {
+  return concat(...sortTreeEntries(entries).map((e) => concat(ENC.encode(`${e.mode.replace(/^0+(?=\d)/, '')} ${e.name}\0`), hexToBytes(e.sha))));
+}
+export function decodeTree(payload: Uint8Array): TreeEntry[] {
+  const out: TreeEntry[] = []; let i = 0;
+  while (i < payload.length) {
+    const sp = payload.indexOf(0x20, i); const nul = payload.indexOf(0, sp);
+    out.push({ mode: DEC.decode(payload.subarray(i, sp)), name: DEC.decode(payload.subarray(sp + 1, nul)), sha: bytesToHex(payload.subarray(nul + 1, nul + 21)) });
+    i = nul + 21;
+  }
+  return out;
+}
+export type Ident = { name: string; email: string; time: number; tz: string };
+export type Commit = { tree: string; parents: string[]; author: Ident; committer: Ident; message: string };
+const ident = (i: Ident) => `${i.name} <${i.email}> ${i.time} ${i.tz}`;
+export function encodeCommit(c: Commit): Uint8Array {
+  return ENC.encode(`tree ${c.tree}\n${c.parents.map((p) => `parent ${p}\n`).join('')}author ${ident(c.author)}\ncommitter ${ident(c.committer)}\n\n${c.message}`);
+}
+function parseIdent(s: string): Ident { const m = /^(.*) <([^>]*)> (\d+) ([+-]\d{4})$/.exec(s); if (!m) throw new Error(`git ident: ${s}`); return { name: m[1]!, email: m[2]!, time: Number(m[3]), tz: m[4]! }; }
+export function decodeCommit(payload: Uint8Array): Commit {
+  const text = DEC.decode(payload); const sep = text.indexOf('\n\n'); const head = text.slice(0, sep); const message = text.slice(sep + 2);
+  const c: Commit = { tree: '', parents: [], author: undefined as never, committer: undefined as never, message };
+  for (const line of head.split('\n')) { const sp = line.indexOf(' '); const k = line.slice(0, sp), v = line.slice(sp + 1); if (k === 'tree') c.tree = v; else if (k === 'parent') c.parents.push(v); else if (k === 'author') c.author = parseIdent(v); else if (k === 'committer') c.committer = parseIdent(v); }
+  return c;
+}
+export type Tag = { object: string; type: GitObjectType; tag: string; tagger?: Ident; message: string };
+export function encodeTag(t: Tag): Uint8Array { return ENC.encode(`object ${t.object}\ntype ${t.type}\ntag ${t.tag}\n${t.tagger ? `tagger ${ident(t.tagger)}\n` : ''}\n${t.message}`); }
+export function decodeTag(payload: Uint8Array): Tag {
+  const text = DEC.decode(payload); const sep = text.indexOf('\n\n'); const t: Tag = { object: '', type: 'commit', tag: '', message: text.slice(sep + 2) };
+  for (const line of text.slice(0, sep).split('\n')) { const sp = line.indexOf(' '); const k = line.slice(0, sp), v = line.slice(sp + 1); if (k === 'object') t.object = v; else if (k === 'type') t.type = v as GitObjectType; else if (k === 'tag') t.tag = v; else if (k === 'tagger') t.tagger = parseIdent(v); }
+  return t;
+}

package/src/git/pack.ts

@@ -0,0 +1,105 @@
+// PACKFILES (gitformat-pack): what a client sends on push and what a server sends on fetch.
+// READ: parse a v2 pack — undeltified objects (zlib at an offset, consumed bytes from the kernel
+// inflater), OFS_DELTA and REF_DELTA resolved against earlier objects in the pack or the object
+// store, the trailing SHA-1 verified — and write every resolved object to the store. WRITE: a pack
+// of undeltified objects with the trailer, which every git accepts (deltas are an optimization a
+// twin does not owe a client).
+import { inflateZlib } from './inflate.ts';
+import { GitObjectStore, bytesToHex, concat, deflateZlib, sha1Hex, type GitObjectType } from './objects.ts';
+
+const TYPE_BY_CODE: Record<number, GitObjectType> = { 1: 'commit', 2: 'tree', 3: 'blob', 4: 'tag' };
+const CODE_BY_TYPE: Record<GitObjectType, number> = { commit: 1, tree: 2, blob: 3, tag: 4 };
+const OFS_DELTA = 6, REF_DELTA = 7;
+
+function readVarSize(input: Uint8Array, at: number): { value: number; type: number; next: number } {
+  let c = input[at]!; const type = (c >> 4) & 7; let value = c & 15; let shift = 4; let i = at + 1;
+  while (c & 0x80) { c = input[i++]!; value += (c & 0x7f) * 2 ** shift; shift += 7; }
+  return { value, type, next: i };
+}
+function readDeltaSize(d: Uint8Array, at: number): { value: number; next: number } {
+  let value = 0, shift = 0, i = at, c: number;
+  do { c = d[i++]!; value += (c & 0x7f) * 2 ** shift; shift += 7; } while (c & 0x80);
+  return { value, next: i };
+}
+/** Apply a git delta (copy / insert ops) to a base payload. */
+export function applyDelta(base: Uint8Array, delta: Uint8Array): Uint8Array {
+  let p = 0; const src = readDeltaSize(delta, p); p = src.next; if (src.value !== base.length) throw new Error(`delta: base size ${src.value} != ${base.length}`);
+  const dst = readDeltaSize(delta, p); p = dst.next; const out = new Uint8Array(dst.value); let o = 0;
+  while (p < delta.length) {
+    const op = delta[p++]!;
+    if (op & 0x80) {
+      let off = 0, len = 0;
+      if (op & 0x01) off |= delta[p++]!; if (op & 0x02) off |= delta[p++]! << 8; if (op & 0x04) off |= delta[p++]! << 16; if (op & 0x08) off |= delta[p++]! * 2 ** 24;
+      if (op & 0x10) len |= delta[p++]!; if (op & 0x20) len |= delta[p++]! << 8; if (op & 0x40) len |= delta[p++]! << 16;
+      if (len === 0) len = 0x10000;
+      out.set(base.subarray(off, off + len), o); o += len;
+    } else if (op > 0) { out.set(delta.subarray(p, p + op), o); o += op; p += op; }
+    else throw new Error('delta: reserved op 0');
+  }
+  if (o !== dst.value) throw new Error(`delta: produced ${o} bytes, expected ${dst.value}`);
+  return out;
+}
+
+export type PackedObject = { type: GitObjectType; sha: string };
+// Delta bases are re-read from the store they were just written to; only this many bytes of
+// resolved payloads stay in memory (git's own core.deltaBaseCacheLimit is 96 MiB). Holding every
+// payload until the pack ends made a full-history push cost the repository's whole inflated size.
+const DELTA_BASE_CACHE_BYTES = 96 * 1024 * 1024;
+/** Read a pack, resolve every object, write them to `store`; returns each object's type and sha in pack order. */
+export async function readPack(pack: Uint8Array, store: GitObjectStore): Promise<PackedObject[]> {
+  const dec = new TextDecoder();
+  if (dec.decode(pack.subarray(0, 4)) !== 'PACK') throw new Error('pack: bad signature');
+  const version = (pack[4]! << 24) | (pack[5]! << 16) | (pack[6]! << 8) | pack[7]!; if (version !== 2 && version !== 3) throw new Error(`pack: version ${version}`);
+  const count = ((pack[8]! << 24) | (pack[9]! << 16) | (pack[10]! << 8) | pack[11]!) >>> 0;
+  const trailer = bytesToHex(pack.subarray(pack.length - 20)); const expected = await sha1Hex(pack.subarray(0, pack.length - 20));
+  if (trailer !== expected) throw new Error('pack: checksum mismatch');
+  type Resolved = { type: GitObjectType; payload: Uint8Array };
+  const cache = new Map<string, Resolved>(); let cached = 0;
+  const remember = (sha: string, obj: Resolved) => {
+    if (obj.payload.length > DELTA_BASE_CACHE_BYTES || cache.has(sha)) return;
+    cache.set(sha, obj); cached += obj.payload.length;
+    for (const [old, { payload }] of cache) { if (cached <= DELTA_BASE_CACHE_BYTES) break; cache.delete(old); cached -= payload.length; }
+  };
+  const payloadOf = async (sha: string): Promise<Resolved | null> => {
+    const hit = cache.get(sha); if (!hit) return store.read(sha);
+    cache.delete(sha); cache.set(sha, hit); return hit;
+  };
+  const byOffset = new Map<number, PackedObject>(); const out: PackedObject[] = []; let at = 12;
+  for (let n = 0; n < count; n++) {
+    const start = at; const h = readVarSize(pack, at); at = h.next;
+    let type: GitObjectType; let payload: Uint8Array;
+    if (h.type === OFS_DELTA || h.type === REF_DELTA) {
+      let baseSha: string;
+      if (h.type === OFS_DELTA) {
+        let c = pack[at++]!; let off = c & 0x7f; while (c & 0x80) { c = pack[at++]!; off = ((off + 1) * 128) + (c & 0x7f); }
+        const entry = byOffset.get(start - off); if (!entry) throw new Error(`pack: ofs-delta base at ${start - off} not found`);
+        baseSha = entry.sha;
+      } else { baseSha = bytesToHex(pack.subarray(at, at + 20)); at += 20; }
+      const base = await payloadOf(baseSha); if (!base) throw new Error(`pack: ${h.type === OFS_DELTA ? 'ofs' : 'ref'}-delta base ${baseSha} not found`);
+      const z = inflateZlib(pack, at); at += z.consumed;
+      type = base.type; payload = applyDelta(base.payload, z.out);
+    } else {
+      const known = TYPE_BY_CODE[h.type]; if (!known) throw new Error(`pack: object type ${h.type}`);
+      const z = inflateZlib(pack, at); at += z.consumed; if (z.out.length !== h.value) throw new Error(`pack: object size ${z.out.length} != ${h.value}`);
+      type = known; payload = z.out;
+    }
+    const obj = { type, sha: await store.write(type, payload) };
+    remember(obj.sha, { type, payload }); byOffset.set(start, obj); out.push(obj);
+  }
+  return out;
+}
+
+function encodeVarSize(type: number, size: number): Uint8Array {
+  const bytes: number[] = []; let c = (type << 4) | (size & 15); size = Math.floor(size / 16);
+  while (size > 0) { bytes.push(c | 0x80); c = size & 0x7f; size = Math.floor(size / 128); }
+  bytes.push(c); return new Uint8Array(bytes);
+}
+/** Write a pack of undeltified objects, trailer included. */
+export async function writePack(objects: Array<{ type: GitObjectType; payload: Uint8Array }>): Promise<Uint8Array> {
+  const header = new Uint8Array(12); header.set(new TextEncoder().encode('PACK'), 0); header[7] = 2;
+  header[8] = (objects.length >>> 24) & 255; header[9] = (objects.length >>> 16) & 255; header[10] = (objects.length >>> 8) & 255; header[11] = objects.length & 255;
+  const parts: Uint8Array[] = [header];
+  for (const o of objects) parts.push(encodeVarSize(CODE_BY_TYPE[o.type], o.payload.length), await deflateZlib(o.payload));
+  const body = concat(...parts); const trailer = await sha1Hex(body);
+  return concat(body, new Uint8Array(trailer.match(/../g)!.map((h) => parseInt(h, 16))));
+}

package/src/git/refs.ts

@@ -0,0 +1,25 @@
+// REFS AS WORLD STATE: a repository's refs live in the string world store under
+// `<prefix>/refs/<name>` (one sha per file) and `<prefix>/HEAD` (a symref), the bare layout —
+// state a snapshot carries, a projection can read, and (through the action log the plane keeps
+// beside it) a push policy can gate. No packed-refs: the store lists directories.
+import type { WorldStore } from '../world-store.ts';
+
+export class GitRefs {
+  constructor(private readonly store: WorldStore, private readonly prefix: string) {}
+  private path(name: string): string { return `${this.prefix}/${name}`; }
+  get(name: string): string | null { const v = this.store.read(this.path(name)); return v === null ? null : v.trim(); }
+  set(name: string, sha: string): void { this.store.write(this.path(name), `${sha}\n`); }
+  delete(name: string): void { if (this.store.exists(this.path(name))) this.store.remove(this.path(name)); }
+  head(): string { const v = this.store.read(this.path('HEAD')); return v === null ? 'refs/heads/main' : v.trim().replace(/^ref: /, ''); }
+  setHead(target: string): void { this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
+  /** Run `fn` holding the repository's ref lock (the world store's exclusive lock). */
+  withLock<T>(fn: () => T): T { return this.store.withLock(this.path('refs.lock'), fn); }
+  /** Every `refs/...` name with its sha, sorted by name. */
+  list(): Array<{ name: string; sha: string }> {
+    const out: Array<{ name: string; sha: string }> = [];
+    // stat before read: on the fs store a directory read throws (EISDIR); the memory store answers null
+    const walk = (dir: string, rel: string): void => { for (const child of this.store.list(dir)) { const p = `${dir}/${child}`; const r = `${rel}/${child}`; if (this.store.stat(p)?.isDirectory) { walk(p, r); continue; } const sha = this.store.read(p); if (sha !== null) out.push({ name: r, sha: sha.trim() }); } };
+    walk(this.path('refs'), 'refs');
+    return out.sort((a, b) => (a.name < b.name ? -1 : 1));
+  }
+}