@volter/twin-github 0.1.2 → 2.0.1

package/src/github-git-plane.ts

@@ -1,47 +1,28 @@
-// GitHub twin git plane — REAL bare git repositories under the twin instance's state dir,
-// driven by the system `git` binary. This is the supabase doctrine applied to GitHub: twin
-// the CONTROL plane (the REST/GraphQL surface), run the REAL engine for the data plane (the
-// git object store). git is its own reference implementation — the object formats, pkt-line
-// framing and smart-HTTP semantics this plane serves are specified by git's own docs
-// (gitformat-pack(5), gitprotocol-common(5), gitprotocol-http(5); recorded in
-// spec-sources.json) and produced/consumed here by real `git` subprocesses, never re-implemented.
+// GITHUB GIT PLANE — the pack half of the kernel's git library (the engine slot,
+// docs/contributing/architecture.md#the-engine-slot). Every repository's git objects live in ONE content-addressed
+// object store per world over the blob seam (R11) — a fork copies refs, never objects; a deleted
+// repository drops its refs — and every repository's refs live in the world store, carried by a
+// snapshot like any other world state. Trees, commits and tags go through the library's codecs;
+// ancestry, merge base and file diffs through its history. No `git` binary anywhere in this module.
 //
-// Layout: one bare repo per twin repository at `<root>/.volter/world/github/git/<owner>/<name>.git`
-// (worldPaths('github').dir — the SAME state dir the kernel event log lives under, so a twin
-// instance's git plane travels with its control-plane state).
-//
-// Reconciliation contract (the heart of the smart-HTTP upgrade — see github-git-http.ts):
-//   • Git Data REST writes (blobs/trees/commits/tags) write REAL git objects here and return
-//     the REAL git sha — so a REST-authored commit chain is byte-for-byte fetchable by any
-//     git client.
-//   • REST ref writes materialize into the bare repo whenever the target object exists
-//     (updateGitRefInPlane); a ref minted against a sha the plane has never seen stays
-//     control-plane-only (the twin's long-standing lenient simulation surface — real GitHub
-//     would 422 "Object does not exist"; the leniency predates this plane and is pinned by
-//     existing capabilities, so it is kept and documented rather than silently changed).
-//   • Pushed refs (git-receive-pack) are folded back into the kernel event log by
-//     reconcileGitPlaneRefs so the REST plane (refs, branches, PR head resolution) sees them.
-//
-// Determinism/offline: every function here shells out to the LOCAL `git` binary over local
-// files — no network, deterministic given the same inputs (commit/tag shas are pinned by the
-// caller-supplied occurredAt). Spawning local git is NOT a live-probe and is outside rate
-// budgets. If `git` itself cannot be spawned we fail LOUDLY with a clear message — never a
-// silent fallback (the gate's absent-capability rule).
-import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+// The names and semantics are the ones the twin's REST plumbing has always called; the calls are
+// async now, because the store is.
 import { join } from 'node:path';
-import { worldPaths } from '@volter/twin';
+import { getActiveBlobStore, getActiveWorldStore, git, worldPaths } from '@volter/world-core';
+const { GitObjectStore, GitRefs, decodeCommit, decodeTag, decodeTree, diffFiles, encodeCommit, encodeTag, encodeTree, isAncestor, mergeBase, mergeText } = git;
+type GitObjectStore = InstanceType<typeof git.GitObjectStore>;
+type GitRefs = InstanceType<typeof git.GitRefs>;
+type Commit = git.Commit; type Ident = git.Ident; type TreeEntry = git.TreeEntry;
 
-// Path-safe owner/name segments (GitHub's own rules are close enough; the point is that a
-// repo name can never traverse out of the plane dir).
 const SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;
+const SHA_RE = /^[0-9a-f]{40}$/i;
 
 /** The git plane root for a twin instance: `<state>/github/git`. */
 export function githubGitPlaneDir(root?: string): string {
   return join(worldPaths('github', root).dir, 'git');
 }
 
-/** The bare repo dir for `owner/name` (validated — a hostile name cannot escape the plane dir). */
+/** A repository's ref prefix in the world store — `<plane>/<owner>/<name>.git` — after validating the name. */
 export function bareRepoDir(repo: string, root?: string): string {
   const [owner, name, extra] = repo.split('/');
   if (!owner || !name || extra !== undefined || !SEGMENT_RE.test(owner) || !SEGMENT_RE.test(name) || owner === '..' || name === '..' || owner === '.' || name === '.') {
@@ -50,134 +31,70 @@ export function bareRepoDir(repo: string, root?: string): string {
   return join(githubGitPlaneDir(root), owner, `${name}.git`);
 }
 
-export function hasBareRepo(repo: string, root?: string): boolean {
-  return existsSync(join(bareRepoDir(repo, root), 'HEAD'));
-}
-
-// Config hygiene: a spawned git must never read the operator's user/system config (hooks
-// paths, transfer knobs, protocol overrides would make the twin's behavior machine-dependent).
-function gitEnv(): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
-  env.GIT_CONFIG_GLOBAL = '/dev/null';
-  env.GIT_CONFIG_SYSTEM = '/dev/null';
-  env.GIT_CONFIG_NOSYSTEM = '1';
-  env.GIT_TERMINAL_PROMPT = '0';
-  env.GIT_ATTR_NOSYSTEM = '1';
-  return env;
-}
-
-export type RunGitResult = { code: number; stdout: Buffer; stderr: string };
-
-/**
- * Run `git <args>` in `dir` (synchronous — the twin's read path is synchronous). Non-zero
- * exit is returned to the caller (many probes are expected to fail, e.g. cat-file -e); a
- * FAILED SPAWN (git missing/broken) throws loudly — the git plane cannot exist without git.
- */
-export function runGit(dir: string, args: string[], opts: { stdin?: Uint8Array; env?: Record<string, string> } = {}): RunGitResult {
-  let proc: ReturnType<typeof Bun.spawnSync>;
-  // A large stdin (a push's packfile) goes through a file, not a pipe: with a pipe, a child that fills its
-  // own stdout before draining stdin deadlocks the synchronous spawn — a push of a real repository hung the
-  // twin for good. A file has no such back-pressure.
-  let stdinFile: string | undefined;
-  let stdin: Uint8Array | ReturnType<typeof Bun.file> | undefined = opts.stdin;
-  if (opts.stdin !== undefined && opts.stdin.length > 65_536) {
-    stdinFile = join(tmpdir(), `twin-git-stdin-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    writeFileSync(stdinFile, opts.stdin);
-    stdin = Bun.file(stdinFile);
-  }
-  try {
-    proc = Bun.spawnSync({
-      cmd: ['git', ...args],
-      cwd: dir,
-      stdin,
-      stdout: 'pipe',
-      stderr: 'pipe',
-      env: { ...gitEnv(), ...(opts.env ?? {}) },
-    });
-  } catch (e) {
-    throw new Error(`github twin git plane: failed to spawn \`git ${args[0] ?? ''}\` — is the git binary on PATH? (${e instanceof Error ? e.message : String(e)})`);
-  } finally {
-    if (stdinFile) rmSync(stdinFile, { force: true });
-  }
-  if (proc.exitCode === null) {
-    throw new Error(`github twin git plane: \`git ${args.join(' ')}\` did not run (killed before exit) — cannot serve the git plane without a working git binary`);
-  }
-  return { code: proc.exitCode, stdout: Buffer.from(proc.stdout ?? new Uint8Array()), stderr: new TextDecoder().decode(proc.stderr ?? new Uint8Array()) };
+/** ONE object store per world: content-addressed, shared by every repository of the world. */
+function objectStore(root?: string): GitObjectStore {
+  return new GitObjectStore(getActiveBlobStore(), join(githubGitPlaneDir(root), 'objects'));
+}
+function refsOf(repo: string, root?: string): GitRefs {
+  return new GitRefs(getActiveWorldStore(), bareRepoDir(repo, root));
 }
 
-/** Run git and THROW (loudly, with stderr) on a non-zero exit — for calls that must succeed. */
-function mustGit(dir: string, args: string[], opts: { stdin?: Uint8Array } = {}): RunGitResult {
-  const res = runGit(dir, args, opts);
-  if (res.code !== 0) {
-    throw new Error(`github twin git plane: \`git ${args.join(' ')}\` failed (exit ${res.code}): ${res.stderr.trim() || res.stdout.toString('utf8').trim()}`);
-  }
-  return res;
+export function hasBareRepo(repo: string, root?: string): boolean {
+  return getActiveWorldStore().exists(join(bareRepoDir(repo, root), 'HEAD'));
 }
 
-/** Idempotently create the bare repo for `repo` (HEAD → refs/heads/<defaultBranch>). */
+/** Create the repository's refs (HEAD → the default branch) when absent; answers its prefix. */
 export function ensureBareRepo(repo: string, root?: string, defaultBranch = 'main'): string {
   const dir = bareRepoDir(repo, root);
-  if (existsSync(join(dir, 'HEAD'))) return dir;
-  mkdirSync(dir, { recursive: true });
-  mustGit(dir, ['init', '--bare', '--quiet']);
-  // Not `init -b`: symbolic-ref works on every git ≥ 2.x and re-pointing is idempotent.
-  mustGit(dir, ['symbolic-ref', 'HEAD', `refs/heads/${defaultBranch}`]);
+  if (!hasBareRepo(repo, root)) refsOf(repo, root).setHead(`refs/heads/${defaultBranch}`);
   return dir;
 }
 
-export function objectExistsInPlane(repo: string, sha: string, root?: string): boolean {
-  if (!hasBareRepo(repo, root)) return false;
-  if (!/^[0-9a-f]{40}$/i.test(sha)) return false;
-  return runGit(bareRepoDir(repo, root), ['cat-file', '-e', sha]).code === 0;
+export async function objectExistsInPlane(repo: string, sha: string, root?: string): Promise<boolean> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return false;
+  return objectStore(root).has(sha.toLowerCase());
 }
 
-export function objectTypeInPlane(repo: string, sha: string, root?: string): string | null {
-  if (!hasBareRepo(repo, root) || !/^[0-9a-f]{40}$/i.test(sha)) return null;
-  const res = runGit(bareRepoDir(repo, root), ['cat-file', '-t', sha]);
-  return res.code === 0 ? res.stdout.toString('utf8').trim() : null;
+export async function objectTypeInPlane(repo: string, sha: string, root?: string): Promise<string | null> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return null;
+  const obj = await objectStore(root).read(sha.toLowerCase());
+  return obj?.type ?? null;
 }
 
-// ── Objects: blobs ─────────────────────────────────────────────────────────────────────────
-/** Write a REAL blob object; returns the real git sha. */
-export function writeGitBlobToPlane(repo: string, contentB64: string, root?: string): string {
-  const dir = ensureBareRepo(repo, root);
-  const res = mustGit(dir, ['hash-object', '-w', '--stdin'], { stdin: Buffer.from(contentB64, 'base64') });
-  return res.stdout.toString('utf8').trim();
+export async function writeGitBlobToPlane(repo: string, contentB64: string, root?: string): Promise<string> {
+  ensureBareRepo(repo, root);
+  return objectStore(root).write('blob', new Uint8Array(Buffer.from(contentB64, 'base64')));
 }
 
-export function readGitBlobFromPlane(repo: string, sha: string, root?: string): { content_b64: string; size: number } | null {
-  if (objectTypeInPlane(repo, sha, root) !== 'blob') return null;
-  const res = mustGit(bareRepoDir(repo, root), ['cat-file', 'blob', sha]);
-  return { content_b64: res.stdout.toString('base64'), size: res.stdout.length };
+export async function readGitBlobFromPlane(repo: string, sha: string, root?: string): Promise<{ content_b64: string; size: number } | null> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return null;
+  const obj = await objectStore(root).read(sha.toLowerCase());
+  if (!obj || obj.type !== 'blob') return null;
+  return { content_b64: Buffer.from(obj.payload).toString('base64'), size: obj.payload.length };
 }
 
-// ── Objects: trees ─────────────────────────────────────────────────────────────────────────
 export type PlaneTreeEntry = { path: string; mode: string; type: string; sha: string; size?: number };
 
-function lsTreeRecursive(dir: string, sha: string): Map<string, { mode: string; type: string; sha: string }> {
-  // `-r -t` lists blobs AND the intermediate trees; we keep only the LEAF entries (blob /
-  // commit(submodule)) — subtrees are rebuilt from the leaf paths on write.
-  const res = mustGit(dir, ['ls-tree', '-r', '-z', sha]);
+const isTreeMode = (mode: string): boolean => mode.replace(/^0+(?=\d)/, '') === '40000';
+const modeOut = (mode: string): string => (isTreeMode(mode) ? '040000' : mode);
+const typeOfMode = (mode: string): string => (isTreeMode(mode) ? 'tree' : mode.replace(/^0+/, '') === '160000' ? 'commit' : 'blob');
+
+/** `ls-tree -r`: every blob under `sha`, keyed by its full path. */
+async function lsTreeRecursive(store: GitObjectStore, sha: string, prefix = ''): Promise<Map<string, { mode: string; type: string; sha: string }>> {
   const out = new Map<string, { mode: string; type: string; sha: string }>();
-  for (const rec of res.stdout.toString('utf8').split('\0')) {
-    if (!rec) continue;
-    const m = /^(\d+) (\w+) ([0-9a-f]{40})\t(.+)$/s.exec(rec);
-    if (m) out.set(m[4]!, { mode: m[1]!, type: m[2]!, sha: m[3]! });
+  const obj = await store.read(sha);
+  if (!obj || obj.type !== 'tree') return out;
+  for (const e of decodeTree(obj.payload)) {
+    const path = prefix ? `${prefix}/${e.name}` : e.name;
+    if (isTreeMode(e.mode)) { for (const [p, v] of await lsTreeRecursive(store, e.sha, path)) out.set(p, v); }
+    else out.set(path, { mode: e.mode, type: typeOfMode(e.mode), sha: e.sha });
   }
   return out;
 }
 
-/** mktree (with `--missing`, matching the twin's lenient legacy surface) one LEVEL of entries. */
-function mktreeLevel(dir: string, entries: Array<{ name: string; mode: string; type: string; sha: string }>): string {
-  const input = entries.map((e) => `${e.mode} ${e.type} ${e.sha}\t${e.name}`).join('\n');
-  const res = mustGit(dir, ['mktree', '--missing'], { stdin: Buffer.from(input.length ? `${input}\n` : '', 'utf8') });
-  return res.stdout.toString('utf8').trim();
-}
-
-/** Build a REAL (possibly nested) tree from flat API entries; returns the real root-tree sha. */
-function buildTreeFromFlat(dir: string, flat: Map<string, { mode: string; type: string; sha: string }>): string {
-  type Node = { entries: Map<string, { mode: string; type: string; sha: string }>; children: Map<string, Node> };
+/** `mktree`, level by level, from a flat path → entry map. */
+async function buildTreeFromFlat(store: GitObjectStore, flat: Map<string, { mode: string; type: string; sha: string }>): Promise<string> {
+  type Node = { entries: Map<string, { mode: string; sha: string }>; children: Map<string, Node> };
   const rootNode: Node = { entries: new Map(), children: new Map() };
   for (const [path, e] of flat) {
     const parts = path.split('/');
@@ -187,272 +104,184 @@ function buildTreeFromFlat(dir: string, flat: Map<string, { mode: string; type:
       if (!node.children.has(seg)) node.children.set(seg, { entries: new Map(), children: new Map() });
       node = node.children.get(seg)!;
     }
-    node.entries.set(parts[parts.length - 1]!, e);
+    node.entries.set(parts[parts.length - 1]!, { mode: e.mode, sha: e.sha });
   }
-  const write = (node: Node): string => {
-    const level: Array<{ name: string; mode: string; type: string; sha: string }> = [];
-    for (const [name, child] of node.children) level.push({ name, mode: '040000', type: 'tree', sha: write(child) });
-    for (const [name, e] of node.entries) level.push({ name, mode: e.mode, type: e.type, sha: e.sha });
-    return mktreeLevel(dir, level);
+  const write = async (node: Node): Promise<string> => {
+    const level: TreeEntry[] = [];
+    for (const [name, child] of node.children) level.push({ name, mode: '40000', sha: await write(child) });
+    for (const [name, e] of node.entries) level.push({ name, mode: e.mode.replace(/^0+(?=\d)/, ''), sha: e.sha });
+    return store.write('tree', encodeTree(level));
   };
   return write(rootNode);
 }
 
-/**
- * Write a REAL tree object from GitHub-API-shaped entries (nested `a/b/c` paths supported,
- * as real GitHub supports). With `baseTreeSha` (and the base present in the plane), the
- * entries OVERLAY the base's recursive listing — an entry with an empty/missing sha deletes
- * its path (GitHub's tree-deletion convention, `sha: null`).
- */
-export function writeGitTreeToPlane(repo: string, entries: PlaneTreeEntry[], baseTreeSha: string | undefined, root?: string): string {
-  const dir = ensureBareRepo(repo, root);
-  const flat = baseTreeSha && objectTypeInPlane(repo, baseTreeSha, root) === 'tree'
-    ? lsTreeRecursive(dir, baseTreeSha)
+/** A tree from `entries` over `baseTreeSha` (an entry with no sha deletes its path). */
+export async function writeGitTreeToPlane(repo: string, entries: PlaneTreeEntry[], baseTreeSha: string | undefined, root?: string): Promise<string> {
+  ensureBareRepo(repo, root);
+  const store = objectStore(root);
+  const flat = baseTreeSha && (await objectTypeInPlane(repo, baseTreeSha, root)) === 'tree'
+    ? await lsTreeRecursive(store, baseTreeSha.toLowerCase())
     : new Map<string, { mode: string; type: string; sha: string }>();
   for (const e of entries) {
     if (!e.sha) { flat.delete(e.path); continue; }
     flat.set(e.path, { mode: e.mode, type: e.type, sha: e.sha });
   }
-  return buildTreeFromFlat(dir, flat);
+  return buildTreeFromFlat(store, flat);
 }
 
-export function readGitTreeFromPlane(repo: string, sha: string, root?: string): PlaneTreeEntry[] | null {
-  if (objectTypeInPlane(repo, sha, root) !== 'tree') return null;
-  const res = mustGit(bareRepoDir(repo, root), ['ls-tree', '-l', '-z', sha]);
+/** `ls-tree -l`: one level, blob sizes measured. */
+export async function readGitTreeFromPlane(repo: string, sha: string, root?: string): Promise<PlaneTreeEntry[] | null> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return null;
+  const store = objectStore(root);
+  const obj = await store.read(sha.toLowerCase());
+  if (!obj || obj.type !== 'tree') return null;
   const out: PlaneTreeEntry[] = [];
-  for (const rec of res.stdout.toString('utf8').split('\0')) {
-    if (!rec) continue;
-    // size column: bytes for a present blob, `-` for trees, `BAD` for a missing object
-    // (the lenient legacy surface permits tree entries naming unwritten blobs).
-    const m = /^(\d+) (\w+) ([0-9a-f]{40}) +(\S+)\t(.+)$/s.exec(rec);
-    if (!m) continue;
-    const entry: PlaneTreeEntry = { path: m[5]!, mode: m[1]!, type: m[2]!, sha: m[3]! };
-    if (/^\d+$/.test(m[4]!)) entry.size = Number(m[4]);
+  for (const e of decodeTree(obj.payload)) {
+    const entry: PlaneTreeEntry = { path: e.name, mode: modeOut(e.mode), type: typeOfMode(e.mode), sha: e.sha };
+    if (entry.type === 'blob') { const b = await store.read(e.sha); if (b) entry.size = b.payload.length; }
     out.push(entry);
   }
   return out;
 }
 
-// ── Objects: commits + annotated tags ──────────────────────────────────────────────────────
-export type PlaneIdent = { name: string; email: string };
+export type PlaneIdent = { name: string; email: string; date?: string };
 const TWIN_IDENT: PlaneIdent = { name: 'github-twin', email: 'github-twin@localhost' };
-
-function identLine(kind: 'author' | 'committer' | 'tagger', ident: PlaneIdent | undefined, occurredAt: string): string {
+const identOf = (ident: PlaneIdent | undefined, occurredAt: string): Ident => {
   const who = ident ?? TWIN_IDENT;
-  const when = Math.floor((Date.parse(occurredAt) || 0) / 1000);
-  return `${kind} ${who.name} <${who.email}> ${when} +0000`;
-}
-
-/**
- * Write a REAL commit object (hand-framed per gitformat-commit, hashed+stored by git itself
- * via `hash-object -t commit -w`); returns the real sha. hash-object validates the object's
- * FORMAT but not connectivity, so the twin's legacy lenient surface (a commit naming a tree
- * sha nobody has written) still produces a real, addressable object — exactly the dangling
- * objects git itself permits.
- */
-export function writeGitCommitToPlane(
+  return { name: who.name, email: who.email, time: Math.floor((Date.parse(who.date ?? occurredAt) || 0) / 1000), tz: '+0000' };
+};
+
+export async function writeGitCommitToPlane(
   repo: string,
   commit: { message: string; treeSha: string; parents: string[]; author?: PlaneIdent; committer?: PlaneIdent; occurredAt: string },
   root?: string,
-): string {
-  const dir = ensureBareRepo(repo, root);
-  const lines = [
-    `tree ${commit.treeSha}`,
-    ...commit.parents.map((p) => `parent ${p}`),
-    identLine('author', commit.author, commit.occurredAt),
-    identLine('committer', commit.committer ?? commit.author, commit.occurredAt),
-    '',
-    commit.message,
-  ];
-  const res = mustGit(dir, ['hash-object', '-t', 'commit', '-w', '--stdin'], { stdin: Buffer.from(`${lines.join('\n')}\n`, 'utf8') });
-  return res.stdout.toString('utf8').trim();
+): Promise<string> {
+  ensureBareRepo(repo, root);
+  const c: Commit = { tree: commit.treeSha, parents: commit.parents, author: identOf(commit.author, commit.occurredAt), committer: identOf(commit.committer ?? commit.author, commit.occurredAt), message: commit.message };
+  return objectStore(root).write('commit', encodeCommit(c));
 }
 
 export type PlaneCommit = { sha: string; message: string; tree_sha: string; parents: string[]; author_name?: string; author_email?: string; created_at?: string };
 
-export function readGitCommitFromPlane(repo: string, sha: string, root?: string): PlaneCommit | null {
-  if (objectTypeInPlane(repo, sha, root) !== 'commit') return null;
-  const raw = mustGit(bareRepoDir(repo, root), ['cat-file', 'commit', sha]).stdout.toString('utf8');
-  const sep = raw.indexOf('\n\n');
-  const header = sep >= 0 ? raw.slice(0, sep) : raw;
-  const message = sep >= 0 ? raw.slice(sep + 2).replace(/\n$/, '') : '';
-  const tree = /^tree ([0-9a-f]{40})$/m.exec(header)?.[1] ?? '';
-  const parents = [...header.matchAll(/^parent ([0-9a-f]{40})$/gm)].map((m) => m[1]!);
-  const author = /^author (.*) <(.*)> (\d+) ([+-]\d{4})$/m.exec(header);
-  const out: PlaneCommit = { sha, message, tree_sha: tree, parents };
-  if (author) {
-    out.author_name = author[1]!;
-    out.author_email = author[2]!;
-    out.created_at = new Date(Number(author[3]) * 1000).toISOString();
-  }
-  return out;
+export async function readGitCommitFromPlane(repo: string, sha: string, root?: string): Promise<PlaneCommit | null> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return null;
+  const obj = await objectStore(root).read(sha.toLowerCase());
+  if (!obj || obj.type !== 'commit') return null;
+  const c = decodeCommit(obj.payload);
+  return { sha: sha.toLowerCase(), message: c.message.replace(/\n$/, ''), tree_sha: c.tree, parents: c.parents, author_name: c.author.name, author_email: c.author.email, created_at: new Date(c.author.time * 1000).toISOString() };
 }
 
-/** Write a REAL annotated-tag object; returns the real sha. */
-export function writeGitTagToPlane(
+export async function writeGitTagToPlane(
   repo: string,
   tag: { tag: string; message: string; objectSha: string; objectType: string; tagger?: PlaneIdent; occurredAt: string },
   root?: string,
-): string {
-  const dir = ensureBareRepo(repo, root);
-  const lines = [
-    `object ${tag.objectSha}`,
-    `type ${tag.objectType}`,
-    `tag ${tag.tag}`,
-    identLine('tagger', tag.tagger, tag.occurredAt),
-    '',
-    tag.message,
-  ];
-  const res = mustGit(dir, ['hash-object', '-t', 'tag', '-w', '--stdin'], { stdin: Buffer.from(`${lines.join('\n')}\n`, 'utf8') });
-  return res.stdout.toString('utf8').trim();
+): Promise<string> {
+  ensureBareRepo(repo, root);
+  return objectStore(root).write('tag', encodeTag({ object: tag.objectSha, type: tag.objectType as 'commit', tag: tag.tag, tagger: identOf(tag.tagger, tag.occurredAt), message: tag.message }));
 }
 
 export type PlaneTag = { sha: string; tag: string; message: string; object_sha: string; object_type: string; tagger_name?: string; created_at?: string };
 
-export function readGitTagFromPlane(repo: string, sha: string, root?: string): PlaneTag | null {
-  if (objectTypeInPlane(repo, sha, root) !== 'tag') return null;
-  const raw = mustGit(bareRepoDir(repo, root), ['cat-file', 'tag', sha]).stdout.toString('utf8');
-  const sep = raw.indexOf('\n\n');
-  const header = sep >= 0 ? raw.slice(0, sep) : raw;
-  const message = sep >= 0 ? raw.slice(sep + 2).replace(/\n$/, '') : '';
-  const out: PlaneTag = {
-    sha,
-    tag: /^tag (.*)$/m.exec(header)?.[1] ?? '',
-    message,
-    object_sha: /^object ([0-9a-f]{40})$/m.exec(header)?.[1] ?? '',
-    object_type: /^type (\w+)$/m.exec(header)?.[1] ?? 'commit',
-  };
-  const tagger = /^tagger (.*) <.*> (\d+) ([+-]\d{4})$/m.exec(header);
-  if (tagger) {
-    out.tagger_name = tagger[1]!;
-    out.created_at = new Date(Number(tagger[2]) * 1000).toISOString();
-  }
+export async function readGitTagFromPlane(repo: string, sha: string, root?: string): Promise<PlaneTag | null> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return null;
+  const obj = await objectStore(root).read(sha.toLowerCase());
+  return !obj || obj.type !== 'tag' ? null : annotatedTag(sha, obj.payload);
+}
+/** An annotated tag object's fields. */
+function annotatedTag(sha: string, payload: Uint8Array): PlaneTag {
+  const t = decodeTag(payload);
+  const out: PlaneTag = { sha: sha.toLowerCase(), tag: t.tag, message: t.message.replace(/\n$/, ''), object_sha: t.object, object_type: t.type };
+  if (t.tagger) { out.tagger_name = t.tagger.name; out.created_at = new Date(t.tagger.time * 1000).toISOString(); }
   return out;
 }
 
-// ── Refs ───────────────────────────────────────────────────────────────────────────────────
-/**
- * Materialize a control-plane ref write into the bare repo. Returns true when the ref now
- * exists in the plane; false when the target object does not exist there OR is not fully
- * CONNECTED (`rev-list --objects` walks every reachable object) — a ref to a dangling
- * commit (the twin's lenient legacy surface permits commits naming trees nobody wrote)
- * stays control-plane-only, so an advertised ref is always actually clonable.
- */
-export function updateGitRefInPlane(repo: string, ref: string, sha: string, root?: string): boolean {
-  if (!hasBareRepo(repo, root)) return false;
-  if (!objectExistsInPlane(repo, sha, root)) return false;
-  const dir = bareRepoDir(repo, root);
-  if (runGit(dir, ['rev-list', '--objects', sha]).code !== 0) return false; // dangling chain — not clonable
-  return runGit(dir, ['update-ref', ref, sha]).code === 0;
+// Objects are immutable, so a chain once found whole stays whole while its objects are kept: the walk stops at
+// an object an earlier walk proved (still present), as git's connectivity check stops at what it already has.
+// Without it every ref update re-read the repository's whole history.
+const provenWhole = new WeakMap<object, Map<string, Set<string>>>();
+
+/** Every object `sha` reaches (commits through parents and trees, trees through entries) is present. */
+async function chainComplete(store: GitObjectStore, sha: string, root?: string, limit = 20000): Promise<boolean> {
+  const blobs = getActiveBlobStore(); const planes = provenWhole.get(blobs) ?? provenWhole.set(blobs, new Map()).get(blobs)!;
+  const plane = githubGitPlaneDir(root); const proven = planes.get(plane) ?? planes.set(plane, new Set()).get(plane)!;
+  const seen = new Set<string>(); const stack = [sha];
+  while (stack.length) {
+    const s = stack.pop()!;
+    if (seen.has(s)) continue; seen.add(s);
+    if (seen.size > limit) return true; // bounded: a huge history is not a dangling one
+    if (proven.has(s)) { if (await store.has(s)) continue; proven.clear(); return false; }
+    const obj = await store.read(s);
+    if (!obj) return false;
+    if (obj.type === 'commit') { const c = decodeCommit(obj.payload); stack.push(c.tree, ...c.parents); }
+    else if (obj.type === 'tree') { for (const e of decodeTree(obj.payload)) if (!/^160000$/.test(e.mode.replace(/^0+/, ''))) stack.push(e.sha); }
+    else if (obj.type === 'tag') stack.push(decodeTag(obj.payload).object);
+  }
+  for (const s of seen) proven.add(s);
+  return true;
 }
 
-export function deleteGitRefInPlane(repo: string, ref: string, root?: string): void {
+/** Point `ref` at `sha` — only at an object the plane holds whole (a dangling chain is not clonable). */
+export async function updateGitRefInPlane(repo: string, ref: string, sha: string, root?: string, expected?: string | null): Promise<boolean> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(sha)) return false;
+  const store = objectStore(root);
+  if (!(await store.has(sha.toLowerCase())) || !(await chainComplete(store, sha.toLowerCase(), root))) return false;
+  const refs = refsOf(repo, root);
+  return refs.withLock(() => {
+    if (expected !== undefined && refs.get(ref) !== expected) return false;
+    refs.set(ref, sha.toLowerCase());
+    return true;
+  });
+}
+
+export async function deleteGitRefInPlane(repo: string, ref: string, root?: string): Promise<void> {
   if (!hasBareRepo(repo, root)) return;
-  runGit(bareRepoDir(repo, root), ['update-ref', '-d', ref]); // non-existence is fine
+  refsOf(repo, root).delete(ref);
 }
 
 export type PlaneRef = { ref: string; object_sha: string; object_type: string };
 
-// ── Repo lifecycle + diffs (REST ↔ plane convergence) ──────────────────────────────────────
-/** Re-point the bare repo's HEAD symref (a REST default_branch change IS this operation). */
 export function setBareRepoHead(repo: string, branch: string, root?: string): void {
   if (!hasBareRepo(repo, root)) return;
-  mustGit(bareRepoDir(repo, root), ['symbolic-ref', 'HEAD', `refs/heads/${branch}`]);
+  refsOf(repo, root).setHead(`refs/heads/${branch}`);
 }
 
-/** Remove a deleted repo's bare repo — a later re-create must NOT inherit its history. */
+/** Drop the repository's refs; its objects stay in the world's store (content-addressed, shared). */
 export function deleteBareRepo(repo: string, root?: string): void {
   if (!hasBareRepo(repo, root)) return;
-  rmSync(bareRepoDir(repo, root), { recursive: true, force: true });
+  const refs = refsOf(repo, root);
+  for (const r of refs.list()) refs.delete(r.name);
+  getActiveWorldStore().remove(join(bareRepoDir(repo, root), 'HEAD'));
 }
 
-/**
- * Fork = copy the parent's object store + refs (what real GitHub does server-side). A file
- * copy of a bare repo is a valid bare repo; `cpSync` keeps this synchronous like the rest of
- * the plane. No parent bare repo → an empty bare repo (the twin's lenient surface).
- */
+/** A fork shares the world's object store: copy the refs and HEAD, nothing else. */
 export function forkBareRepo(parentRepo: string, forkRepo: string, root?: string, defaultBranch = 'main'): void {
-  const dst = bareRepoDir(forkRepo, root); // validates the fork name before any copy
+  bareRepoDir(forkRepo, root); // validates the fork name before any copy
   if (hasBareRepo(forkRepo, root)) return;
   if (!hasBareRepo(parentRepo, root)) { ensureBareRepo(forkRepo, root, defaultBranch); return; }
-  mkdirSync(dst, { recursive: true });
-  cpSync(bareRepoDir(parentRepo, root), dst, { recursive: true });
-}
-
-/** True when `ancestor` is an ancestor of `descendant` (the fast-forward test). */
-export function isAncestorInPlane(repo: string, ancestor: string, descendant: string, root?: string): boolean {
-  if (!hasBareRepo(repo, root)) return false;
-  return runGit(bareRepoDir(repo, root), ['merge-base', '--is-ancestor', ancestor, descendant]).code === 0;
-}
-
-export type PlaneDiffFile = { filename: string; status: string; additions: number; deletions: number; sha?: string };
-
-/** The merge base of two commits, or null when none exists / either is absent. */
-export function mergeBaseInPlane(repo: string, a: string, b: string, root?: string): string | null {
-  if (!objectExistsInPlane(repo, a, root) || !objectExistsInPlane(repo, b, root)) return null;
-  const res = runGit(bareRepoDir(repo, root), ['merge-base', a, b]);
-  return res.code === 0 ? res.stdout.toString('utf8').trim() : null;
-}
-
-/**
- * The changed-file list between two commits, from the REAL object store (`diff-tree -r`) —
- * what backs GET /pulls/:n/files and compare when both sides exist in the plane. THREE-DOT
- * semantics like real GitHub: the diff runs from merge-base(base,head) to head, so a base
- * branch that advanced past the PR's branch point never leaks ITS OWN changes into the PR's
- * file list (merge-gate scope classification depends on exactly this). Unrelated histories
- * (no merge base) fall back to the plain two-commit diff. Binary files report 0/0 (git
- * prints `-`) rather than fabricated counts; renames are declared scope (no -M — plumbing
- * reports adds+deletes, which is honest, never a mis-paired record). `sha` is the REAL
- * post-image blob sha from --raw (absent for deletions).
- */
-export function diffFilesInPlane(repo: string, baseSha: string, headSha: string, root?: string): PlaneDiffFile[] | null {
-  if (!objectExistsInPlane(repo, baseSha, root) || !objectExistsInPlane(repo, headSha, root)) return null;
-  const from = mergeBaseInPlane(repo, baseSha, headSha, root) ?? baseSha;
-  const dir = bareRepoDir(repo, root);
-  const num = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--numstat', '-z', from, headSha]);
-  const nam = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--name-status', '-z', from, headSha]);
-  const raw = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--raw', '-z', from, headSha]);
-  if (num.code !== 0 || nam.code !== 0 || raw.code !== 0) return null;
-  const statusByPath = new Map<string, string>();
-  const namParts = nam.stdout.toString('utf8').split('\0');
-  for (let i = 0; i + 1 < namParts.length; i += 2) {
-    const s = namParts[i]!; const p = namParts[i + 1]!;
-    if (!s || !p) continue;
-    const code = s[0];
-    statusByPath.set(p, code === 'A' ? 'added' : code === 'D' ? 'removed' : 'modified');
-  }
-  // --raw -z records: ":oldmode newmode oldsha newsha status\0path\0" — the post-image blob
-  // sha is the REAL object id (all-zeros for a deletion).
-  const shaByPath = new Map<string, string>();
-  const rawParts = raw.stdout.toString('utf8').split('\0');
-  for (let i = 0; i + 1 < rawParts.length; i += 2) {
-    const meta = rawParts[i]!; const p = rawParts[i + 1]!;
-    const m = /^:\d+ \d+ [0-9a-f]{40} ([0-9a-f]{40}) \w+$/.exec(meta);
-    if (m && p && m[1] !== '0'.repeat(40)) shaByPath.set(p, m[1]!);
-  }
-  const out: PlaneDiffFile[] = [];
-  for (const rec of num.stdout.toString('utf8').split('\0')) {
-    if (!rec) continue;
-    const m = /^([0-9-]+)\t([0-9-]+)\t(.*)$/s.exec(rec);
-    if (!m || !m[3]) continue;
-    const filename = m[3];
-    const sha = shaByPath.get(filename);
-    out.push({
-      filename,
-      status: statusByPath.get(filename) ?? 'modified',
-      additions: m[1] === '-' ? 0 : Number(m[1]),
-      deletions: m[2] === '-' ? 0 : Number(m[2]),
-      ...(sha !== undefined ? { sha } : {}),
-    });
-  }
-  return out;
+  const from = refsOf(parentRepo, root); const to = refsOf(forkRepo, root);
+  to.setHead(from.head());
+  for (const r of from.list()) to.set(r.name, r.sha);
+}
+
+export async function isAncestorInPlane(repo: string, ancestor: string, descendant: string, root?: string): Promise<boolean> {
+  if (!hasBareRepo(repo, root) || !SHA_RE.test(ancestor) || !SHA_RE.test(descendant)) return false;
+  return isAncestor(objectStore(root), ancestor.toLowerCase(), descendant.toLowerCase());
+}
+
+export type PlaneDiffFile = { filename: string; status: string; additions: number; deletions: number; sha?: string; patch?: string };
+
+export async function mergeBaseInPlane(repo: string, a: string, b: string, root?: string): Promise<string | null> {
+  if (!(await objectExistsInPlane(repo, a, root)) || !(await objectExistsInPlane(repo, b, root))) return null;
+  return mergeBase(objectStore(root), a.toLowerCase(), b.toLowerCase());
+}
+
+/** GitHub's compare: merge-base(base, head)..head, as the library's `diffFiles` computes it. */
+export async function diffFilesInPlane(repo: string, baseSha: string, headSha: string, root?: string, opts: { patch?: boolean } = {}): Promise<PlaneDiffFile[] | null> {
+  if (!(await objectExistsInPlane(repo, baseSha, root)) || !(await objectExistsInPlane(repo, headSha, root))) return null;
+  const files = await diffFiles(objectStore(root), baseSha.toLowerCase(), headSha.toLowerCase(), opts);
+  return files === null ? null : files.map((f: git.DiffFile) => ({ filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, ...(f.sha !== undefined ? { sha: f.sha } : {}), ...(f.patch !== undefined ? { patch: f.patch } : {}) }));
 }
 
-/**
- * Conservative git branch-name validation (the load-bearing subset of
- * git-check-ref-format(1)) — a name this rejects would make `symbolic-ref`/`update-ref`
- * throw, so callers 422 instead of surfacing a 500.
- */
 export function isValidBranchName(name: string): boolean {
   if (!name || name.length > 250) return false;
   if (/[\s~^:?*[\\\x00-\x1f\x7f]/.test(name)) return false;
@@ -461,51 +290,84 @@ export function isValidBranchName(name: string): boolean {
   return true;
 }
 
-/** All refs in the bare repo (`for-each-ref`) — the protocol-visible ref set. */
-export function listGitPlaneRefs(repo: string, root?: string): PlaneRef[] {
+/** `for-each-ref`: every ref with its object's sha and type. */
+export async function listGitPlaneRefs(repo: string, root?: string): Promise<PlaneRef[]> {
   if (!hasBareRepo(repo, root)) return [];
-  const res = mustGit(bareRepoDir(repo, root), ['for-each-ref', '--format=%(objectname) %(objecttype) %(refname)']);
+  const store = objectStore(root);
   const out: PlaneRef[] = [];
-  for (const line of res.stdout.toString('utf8').split('\n')) {
-    if (!line) continue;
-    const m = /^([0-9a-f]{40}) (\w+) (.+)$/.exec(line);
-    if (m) out.push({ object_sha: m[1]!, object_type: m[2]!, ref: m[3]! });
+  for (const r of refsOf(repo, root).list()) {
+    const obj = await store.read(r.sha);
+    out.push({ ref: r.name, object_sha: r.sha, object_type: obj?.type ?? 'commit' });
   }
   return out;
 }
 
-// ── Pull-request landing (REST merge ↔ plane convergence) ──────────────────────────────────
-const GITHUB_IDENT: PlaneIdent = { name: 'GitHub', email: 'noreply@github.com' };
-
-/**
- * Land `headSha` on branch `baseBranch` the way GitHub's merge button does: a REAL merge commit
- * (git merge-tree, no worktree) whose first parent is the base tip, or a single-parent commit of the
- * merged tree for the squash/rebase methods (declared deviation: rebase is folded to one commit).
- * Returns the base branch's new tip; `{ conflict }` when the trees do not merge cleanly; null when
- * the repository has no git plane or the base branch does not exist there. The base tip moves
- * atomically (update-ref with the expected old value), so a concurrent push loses to nobody.
- */
-export function mergeIntoBranchInPlane(
-  repo: string,
-  baseBranch: string,
-  headSha: string,
-  message: string,
-  method: 'merge' | 'squash' | 'rebase',
-  occurredAt: string,
-  root?: string,
-): { sha: string } | { conflict: true } | null {
+/** The library's view of a repository, for smart HTTP. */
+export function planeRepo(repo: string, root?: string): { store: GitObjectStore; refs: GitRefs } {
+  return { store: objectStore(root), refs: refsOf(repo, root) };
+}
+
+type FlatEntry = { mode: string; type: string; sha: string };
+/** A file both sides of a merge changed: its three texts merged into one blob, or nothing when they conflict (a side
+ *  that is not a text blob, modes that disagree, or edits that overlap). */
+async function mergeBothSides(store: GitObjectStore, original: FlatEntry | undefined, ours: FlatEntry | undefined, theirs: FlatEntry | undefined): Promise<FlatEntry | null> {
+  if (!ours || !theirs || !original || ours.type !== 'blob' || theirs.type !== 'blob' || original.type !== 'blob') return null;
+  const mode = ours.mode === theirs.mode ? ours.mode : ours.mode === original.mode ? theirs.mode : theirs.mode === original.mode ? ours.mode : null;
+  if (!mode || !mode.startsWith('100')) return null;
+  const objects = await Promise.all([original, ours, theirs].map(entry => store.read(entry.sha)));
+  if (objects.some(obj => !obj || obj.type !== 'blob' || obj.payload.includes(0))) return null;
+  let contents: string[];
+  try { contents = objects.map(obj => new TextDecoder('utf-8', { fatal: true }).decode(obj!.payload)); }
+  catch { return null; }
+  const content = mergeText(contents[0]!, contents[1]!, contents[2]!);
+  return content === null ? null : { mode, type: 'blob', sha: await store.write('blob', new TextEncoder().encode(content)) };
+}
+
+/** Merge three trees, publishing the resulting ref only if its original tip still holds.
+ * Text edits merge against the common ancestor; no conflicted tree is published. A dry run answers
+ * the merged tree without writing a commit or moving the branch (a pull request's mergeability). */
+export async function mergeIntoBranchInPlane(
+  repo: string, baseBranch: string, headSha: string, message: string,
+  method: 'merge' | 'squash' | 'rebase', occurredAt: string, root?: string, merger?: PlaneIdent, dryRun = false,
+): Promise<{ sha: string } | { conflict: string } | null> {
   if (!hasBareRepo(repo, root)) return null;
-  const dir = bareRepoDir(repo, root);
-  const base = runGit(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${baseBranch}^{commit}`]);
-  if (base.code !== 0) return null;
-  const baseSha = base.stdout.toString('utf8').trim();
-  if (runGit(dir, ['merge-base', '--is-ancestor', headSha, baseSha]).code === 0) return { sha: baseSha };
-  const merged = runGit(dir, ['merge-tree', '--write-tree', baseSha, headSha]);
-  if (merged.code === 1) return { conflict: true };
-  if (merged.code !== 0) throw new Error(`github twin git plane: merge-tree failed (exit ${merged.code}): ${merged.stderr.trim()}`);
-  const treeSha = merged.stdout.toString('utf8').split('\n')[0]!.trim();
-  const parents = method === 'merge' ? [baseSha, headSha] : [baseSha];
-  const sha = writeGitCommitToPlane(repo, { message, treeSha, parents, author: GITHUB_IDENT, committer: GITHUB_IDENT, occurredAt }, root);
-  if (runGit(dir, ['update-ref', `refs/heads/${baseBranch}`, sha, baseSha]).code !== 0) return null;
-  return { sha };
+  const refs = refsOf(repo, root);
+  const ref = `refs/heads/${baseBranch}`;
+  const baseSha = refs.get(ref);
+  if (!baseSha) return null;
+  const store = objectStore(root);
+  const base = await readGitCommitFromPlane(repo, baseSha, root);
+  const head = await readGitCommitFromPlane(repo, headSha, root);
+  if (!base || !head) return { conflict: 'missing commit' };
+  if (await isAncestor(store, headSha, baseSha)) return { sha: baseSha };
+  const ancestorSha = await mergeBase(store, baseSha, headSha);
+  if (!ancestorSha) return { conflict: 'unrelated histories' };
+  const ancestor = ancestorSha ? await readGitCommitFromPlane(repo, ancestorSha, root) : null;
+  const before = ancestor ? await lsTreeRecursive(store, ancestor.tree_sha) : new Map<string, { mode: string; type: string; sha: string }>();
+  const left = await lsTreeRecursive(store, base.tree_sha);
+  const right = await lsTreeRecursive(store, head.tree_sha);
+  const merged = new Map(left);
+  const same = (a: { mode: string; sha: string } | undefined, b: { mode: string; sha: string } | undefined) => a?.mode === b?.mode && a?.sha === b?.sha;
+  for (const path of new Set([...before.keys(), ...left.keys(), ...right.keys()])) {
+    const original = before.get(path), ours = left.get(path), theirs = right.get(path);
+    if (same(ours, theirs) || same(theirs, original)) continue;
+    // both sides changed the file: its texts merge against the ancestor's, or the merge conflicts
+    if (!same(ours, original)) { const both = await mergeBothSides(store, original, ours, theirs); if (!both) return { conflict: path }; merged.set(path, both); continue; }
+    if (theirs) merged.set(path, theirs); else merged.delete(path);
+  }
+  // A file/directory collision must not produce a tree containing both names.
+  for (const path of merged.keys()) {
+    const parts = path.split('/');
+    for (let i = 1; i < parts.length; i++) if (merged.has(parts.slice(0, i).join('/'))) return { conflict: path };
+  }
+  const treeSha = await buildTreeFromFlat(store, merged);
+  if (dryRun) return { sha: treeSha };
+  // GitHub authors a merge made through the API or the web as the person who merged, committed by GitHub itself.
+  const sha = await writeGitCommitToPlane(repo, { message, treeSha, parents: method === 'merge' ? [baseSha, headSha] : [baseSha], occurredAt,
+    ...(merger ? { author: merger, committer: { name: 'GitHub', email: 'noreply@github.com' } } : {}) }, root);
+  return refs.withLock(() => {
+    if (refs.get(ref) !== baseSha) return { conflict: 'base moved' };
+    refs.set(ref, sha);
+    return { sha };
+  });
 }