@volter/twin-github 0.1.2 → 2.0.0

package/src/github-events.ts

@@ -1,105 +1,233 @@
-// GitHub webhook emission (scorecard R17). Real GitHub fires webhooks on PR/review/
-// comment activity AND across the rest of the surface (release/repository/fork/member/
-// push/discussion/…) — `pull_request` (opened/edited/closed), `pull_request_review`
-// (submitted), `issue_comment` (created), and many more — so an app's webhook handler
-// runs. The twin builds the real GitHub webhook envelope (with the X-GitHub-Event header
-// + the HMAC X-Hub-Signature-256 when a secret is configured), delivers it to registered
-// endpoints (injected delivery: fake in tests, HTTP POST live), and LOGS each delivery so
-// it can be listed + redelivered (real GitHub's deliveries log). Deterministic: caller
-// supplies occurredAt; ids are derived from a stable per-process sequence.
-import { createHmac } from 'node:crypto';
-import type { GithubWriteEvent } from './github-twin.ts';
-
-export type GithubWebhook = { event: string; action: string; number: number; repository: { full_name: string }; pull_request?: Record<string, unknown>; issue?: { number: number }; comment?: { body: string }; review?: { body: string }; ref?: string; before?: string; after?: string; created?: boolean; deleted?: boolean };
-// Delivery receives the resolved headers too (X-GitHub-Event, X-GitHub-Delivery,
-// X-Hub-Signature-256) so a faithful consumer can verify the signature.
-export type GithubWebhookDelivery = (url: string, headerEvent: string, payload: GithubWebhook, headers: Record<string, string>) => Promise<void> | void;
-
-// A registered endpoint + its (optional) signing secret.
-type Endpoint = { url: string; secret?: string };
-const registry: Endpoint[] = [];
-export function registerGithubWebhook(url: string, secret?: string): void {
-  const existing = registry.find((e) => e.url === url);
-  if (existing) existing.secret = secret;
-  else registry.push({ url, secret });
-}
-export function clearGithubWebhooks(): void { registry.length = 0; deliveries.length = 0; deliverySeq = 0; }
-export function listGithubWebhooks(): string[] { return registry.map((e) => e.url); }
-
-// The deliveries log — one entry per (endpoint, event) delivery, with the exact payload
-// JSON so a redelivery replays it byte-for-byte (real GitHub keeps deliveries for redelivery).
-export type GithubDelivery = { id: string; url: string; event: string; action: string; payloadJson: string; deliveredAt?: string; secret?: string };
-const deliveries: GithubDelivery[] = [];
-let deliverySeq = 0;
-export function listGithubDeliveries(): GithubDelivery[] { return deliveries.map((d) => ({ ...d })); }
-
-/** The HMAC-SHA256 signature GitHub sends in X-Hub-Signature-256 (sha256=<hex>). */
-export function signGithubPayload(secret: string, payloadJson: string): string {
-  return `sha256=${createHmac('sha256', secret).update(payloadJson).digest('hex')}`;
-}
-
-const httpDelivery: GithubWebhookDelivery = async (url, _headerEvent, payload, headers) => {
-  try { await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(payload) }); }
-  catch { /* fire-and-forget, like real GitHub */ }
+// Native repository hooks and delivery history live in the World's existing state.
+// Callback HTTP is the caller's webhook sink, never a credentialed GitHub API call.
+import { createHash, createHmac } from 'node:crypto';
+import { applyTwinWrite, applyTwinWriteAtomic, ownFields, twinResources, worldNow } from '@volter/world-core';
+import { GITHUB_WORLD_USER, githubApps, githubState, handleGithubRequest, toGithubWebhook } from './github-twin.ts';
+import type { GithubWebhook as Hook, GithubWriteEvent } from './github-twin.ts';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+
+export type GithubWebhook = Record<string, unknown>;
+export type GithubWebhookResponse = { status: number; headers?: Record<string, string>; body?: string };
+export type GithubWebhookDelivery = (url: string, event: string, payload: GithubWebhook, headers: Record<string, string>, body: string) => Promise<GithubWebhookResponse> | GithubWebhookResponse;
+type Options = { root?: string; occurredAt?: string; deliver?: GithubWebhookDelivery };
+type Delivery = {
+  id: number; guid: string; repository: string; hookId: number; event: string; action?: string;
+  url: string; payloadJson: string; requestBody: string; requestHeaders: Record<string, string>;
+  deliveredAt: string; redelivery: boolean; statusCode: number | null; error?: string;
+  responseHeaders?: Record<string, string>; responseBody?: string;
 };
+const TYPE = 'webhook_delivery';
 
-function buildPayload(write: GithubWriteEvent): GithubWebhook {
-  return {
-    event: write.event,
-    action: write.action,
-    number: write.number,
-    repository: { full_name: write.repository },
-    ...(write.event === 'pull_request' ? { pull_request: write.pr ?? { number: write.number } } : {}),
-    ...(write.event === 'issues' ? { issue: { number: write.number } } : {}),
-    ...(write.event === 'pull_request_review' ? { review: { body: write.body ?? '' }, pull_request: { number: write.number } } : {}),
-    ...(write.event === 'issue_comment' ? { comment: { body: write.body ?? '' } } : {}),
-    // push events (git-receive-pack / contents writes): GitHub's ref/before/after triple
-    // plus the created/deleted flags consumers branch on (derived exactly as GitHub derives
-    // them: created ⇔ before is the zero sha, deleted ⇔ after is). `forced` would need
-    // ancestry knowledge the event does not carry — omitted rather than fabricated.
-    ...(write.event === 'push' && write.ref !== undefined
-      ? {
-          ref: write.ref, before: write.before ?? '', after: write.after ?? '',
-          created: write.before === '0'.repeat(40), deleted: write.after === '0'.repeat(40),
-        }
-      : {}),
-  };
+export function signGithubPayload(secret: string, body: string): string {
+  return `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+}
+
+const httpDelivery: GithubWebhookDelivery = async (url, _event, _payload, headers, body) => {
+  // the World's egress rule: a refused hook URL fails as a transport failure, recorded on the delivery
+  const refusal = worldEgressRefusal(url);
+  if (refusal !== null) throw new Error(refusal);
+  const response = await fetch(url, { method: 'POST', headers, body, redirect: 'manual', signal: AbortSignal.timeout(10_000) });
+  return { status: response.status, headers: Object.fromEntries(response.headers), body: await response.text() };
+};
+
+async function nativeObject(path: string, root?: string): Promise<Record<string, unknown> | undefined> {
+  const response = await handleGithubRequest({ method: 'GET', path, root });
+  return response.status === 200 && response.body && !Array.isArray(response.body)
+    ? response.body as Record<string, unknown> : undefined;
+}
+
+async function buildPayload(write: GithubWriteEvent, root?: string): Promise<GithubWebhook> {
+  const payload: GithubWebhook = { action: write.action, repository: { full_name: write.repository }, sender: { login: GITHUB_WORLD_USER, type: 'User' } };
+  const path = `/repos/${write.repository}`;
+  if (['pull_request', 'pull_request_review', 'pull_request_review_comment'].includes(write.event)) {
+    payload.pull_request = write.pr ?? await nativeObject(`${path}/pulls/${write.number}`, root) ?? { number: write.number };
+  }
+  if (write.event === 'pull_request') payload.number = write.number;
+  if (write.event === 'issues' || write.event === 'issue_comment') payload.issue = await issuePayload(write, path, root);
+  if (write.event === 'pull_request_review') payload.review = reviewPayload(write);
+  if (write.event === 'issue_comment' || write.event === 'pull_request_review_comment') payload.comment = write.comment ?? { body: write.body ?? '' };
+  if (write.event === 'discussion' || write.event === 'discussion_comment') payload.number = write.number;
+  if (write.event === 'push' && write.ref !== undefined) pushPayload(payload, write);
+  return payload;
+}
+/** An issue event's issue: the one the write carried, or as the API reads it. */
+async function issuePayload(write: GithubWriteEvent, path: string, root?: string): Promise<unknown> {
+  return write.issue ?? await nativeObject(`${path}/issues/${write.number}`, root) ?? { number: write.number };
+}
+/** A review event's review, its state lower-cased as webhooks send it. */
+function reviewPayload(write: GithubWriteEvent): Record<string, unknown> {
+  const review = write.review ?? { body: write.body ?? '' };
+  return { ...review, ...(typeof review.state === 'string' ? { state: review.state.toLowerCase() } : {}) };
+}
+/** A push event names its ref and the commits before and after it, and carries no action. */
+function pushPayload(payload: GithubWebhook, write: GithubWriteEvent): void {
+  delete payload.action;
+  Object.assign(payload, { ref: write.ref, before: write.before ?? '', after: write.after ?? '', created: write.before === '0'.repeat(40), deleted: write.after === '0'.repeat(40) });
+}
+
+function records(root?: string): Delivery[] {
+  return twinResources('github', root).filter(r => r.type === TYPE).map(r => ownFields(r) as unknown as Delivery);
+}
+
+function hookFor(repository: string, id: number, root?: string): Hook | undefined {
+  return githubState(root).webhooks.find(h => h.repository === repository && h.id === id);
 }
 
-function headersFor(event: string, deliveryId: string, payloadJson: string, secret?: string): Record<string, string> {
-  const headers: Record<string, string> = { 'x-github-event': event, 'x-github-delivery': deliveryId };
-  if (secret) headers['x-hub-signature-256'] = signGithubPayload(secret, payloadJson);
+function headersFor(hook: Hook, event: string, guid: string, body: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': hook.content_type !== 'json' ? 'application/x-www-form-urlencoded' : 'application/json',
+    'x-github-event': event, 'x-github-delivery': guid, 'x-github-hook-id': String(hook.id),
+  };
+  if (hook.secret) headers['x-hub-signature-256'] = signGithubPayload(hook.secret, body);
   return headers;
 }
 
-/** Emit a GitHub webhook for a twin write to registered endpoints. No-op when none registered. */
-export async function emitGithubEvent(
-  write: GithubWriteEvent,
-  opts: { occurredAt?: string; deliver?: GithubWebhookDelivery } = {},
-): Promise<GithubWebhook[]> {
-  if (registry.length === 0) return [];
-  const deliver = opts.deliver ?? httpDelivery;
-  const payload = buildPayload(write);
-  const payloadJson = JSON.stringify(payload);
-  const out: GithubWebhook[] = [];
-  for (const ep of registry) {
-    const id = `${++deliverySeq}`;
-    deliveries.push({ id, url: ep.url, event: write.event, action: write.action, payloadJson, deliveredAt: opts.occurredAt, secret: ep.secret });
-    const headers = headersFor(write.event, id, payloadJson, ep.secret);
-    await deliver(ep.url, write.event, payload, headers);
-    out.push(payload);
+async function dispatch(hook: Hook, event: string, payload: GithubWebhook, opts: Options, original?: Delivery): Promise<Delivery> {
+  const payloadJson = original?.payloadJson ?? JSON.stringify(payload);
+  const requestBody = hook.content_type !== 'json' ? new URLSearchParams({ payload: payloadJson }).toString() : payloadJson;
+  const occurredAt = opts.occurredAt ?? worldNow();
+  // Allocation and append share the kernel lock; two callbacks cannot claim the same id.
+  const { value: pending } = await applyTwinWriteAtomic<Delivery>('github', resources => {
+    const id = resources.filter(r => r.type === TYPE).reduce((max, r) => Math.max(max, Number(ownFields(r).id) || 0), 0) + 1;
+    // from the World's history alone (never its directory): a replay of the same history delivers the same ids
+    const hex = createHash('sha256').update(`${occurredAt}\0${hook.repository}\0${hook.id}\0${id}\0${payloadJson}`).digest('hex');
+    const guid = original?.guid ?? `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    const value: Delivery = {
+      id, guid, repository: hook.repository, hookId: hook.id, event,
+      ...(typeof payload.action === 'string' ? { action: payload.action } : {}),
+      url: hook.url!, payloadJson, requestBody, requestHeaders: headersFor(hook, event, guid, requestBody),
+      deliveredAt: occurredAt, redelivery: original !== undefined, statusCode: null,
+    };
+    return { kind: 'write', value, write: { operation: 'webhook_delivery.create', subjectType: TYPE, subjectId: `webhook-delivery:${id}`, fields: value, occurredAt, actor: { kind: 'system' } } };
+  }, opts.root);
+  let result: Partial<Delivery>;
+  try {
+    const response = await (opts.deliver ?? httpDelivery)(pending.url, event, JSON.parse(payloadJson), pending.requestHeaders, requestBody);
+    result = { statusCode: response.status, responseHeaders: response.headers ?? {}, responseBody: response.body ?? '' };
+  } catch {
+    // Persist failure without exposing signing keys, URL credentials or a thrown transport stack.
+    result = { statusCode: 0, error: 'Webhook transport failed' };
+  }
+  await applyTwinWrite('github', { operation: 'webhook_delivery.update', subjectType: TYPE, subjectId: `webhook-delivery:${pending.id}`, fields: result, occurredAt, actor: { kind: 'system' } }, opts.root);
+  return { ...pending, ...result };
+}
+
+/** Current persisted hook settings are resolved per event and World, including after restart. */
+export async function emitGithubEvent(write: GithubWriteEvent, opts: Options = {}): Promise<GithubWebhook[]> {
+  const hooks = githubState(opts.root).webhooks.filter(h => h.repository === write.repository && h.active && h.url && (h.events.includes('*') || h.events.includes(write.event)));
+  return hooks.length ? deliverToHooks(hooks, write, opts) : [];
+}
+/** Each subscribed repository hook gets the event's payload. */
+async function deliverToHooks(hooks: Hook[], write: GithubWriteEvent, opts: Options): Promise<GithubWebhook[]> {
+  const payload = await buildPayload(write, opts.root);
+  for (const hook of hooks) await dispatch(hook, write.event, payload, opts);
+  return hooks.map(() => payload);
+}
+
+/** A repository's event, delivered as well to each GitHub App installed on the repository whose app subscribes to it,
+ *  with the installation it is for, so the app knows which installation token to mint
+ *  (docs.github.com/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps,
+ *  docs.github.com/webhooks/webhook-events-and-payloads: `installation` is present when the event is for an app's
+ *  installation). Answers how many apps it was delivered to. */
+export async function emitGithubInstallationEvents(write: GithubWriteEvent, opts: Options = {}): Promise<number> {
+  const st = githubState(opts.root);
+  const [owner] = write.repository.split('/');
+  const covering = st.appInstallations.filter((i) => i.account_login === owner && (i.repository_selection === 'all' || (i.repositories ?? []).includes(write.repository)));
+  let delivered = 0;
+  for (const installation of covering) {
+    const app = githubApps(opts.root).find((a) => a.slug === installation.app_slug);
+    if (!app?.hook_url || !app.events.includes(write.event)) continue;
+    const payload = { ...(await buildPayload(write, opts.root)), installation: { id: installation.id, node_id: nodeIdOf('Integration::Installation', installation.id) } };
+    if (await emitGithubAppEvent(app, write.event, payload, opts)) delivered += 1;
   }
-  return out;
-}
-
-/** Redeliver a logged delivery by id — replays the EXACT payload to its endpoint. */
-export async function redeliverGithubDelivery(id: string, opts: { deliver?: GithubWebhookDelivery } = {}): Promise<boolean> {
-  const d = deliveries.find((x) => x.id === id);
-  if (!d) return false;
-  const deliver = opts.deliver ?? httpDelivery;
-  const newId = `${++deliverySeq}`;
-  deliveries.push({ ...d, id: newId });
-  const headers = headersFor(d.event, newId, d.payloadJson, d.secret);
-  await deliver(d.url, d.event, JSON.parse(d.payloadJson) as GithubWebhook, headers);
+  return delivered;
+}
+const nodeIdOf = (type: string, id: number): string => Buffer.from(`${String(type.length).padStart(2, '0')}:${type}${id}`).toString('base64');
+
+/** An event for a GitHub App's own webhook (installation, …), delivered to the URL its registration names
+ *  and recorded as any delivery is; an app with no webhook URL gets none, as on GitHub. */
+export async function emitGithubAppEvent(app: { id: number; hook_url?: string; webhook_secret?: string }, event: string, payload: GithubWebhook, opts: Options = {}): Promise<boolean> {
+  if (!app.hook_url) return false;
+  const hook = { id: app.id, repository: '', name: 'web', active: true, url: app.hook_url, content_type: 'json', secret: app.webhook_secret ?? '', events: [event] } as unknown as Hook;
+  await dispatch(hook, event, payload, opts);
   return true;
 }
+
+export async function pingGithubHook(repository: string, hookId: number, opts: Options = {}): Promise<boolean> {
+  const hook = hookFor(repository, hookId, opts.root);
+  if (!hook?.url) return false;
+  await dispatch(hook, 'ping', { hook_id: hook.id, hook: toGithubWebhook(hook), repository: { full_name: repository } }, opts);
+  return true;
+}
+
+/** A hook's last delivery as GitHub reports it on the hook (`last_response`): unused until one is made. */
+export function hookLastResponse(repository: string, hookId: number, root?: string): Record<string, unknown> {
+  const last = records(root).filter((d) => d.repository === repository && d.hookId === hookId).sort((a, b) => b.id - a.id)[0];
+  if (!last || last.statusCode === null) return { code: null, status: 'unused', message: null };
+  const ok = last.statusCode >= 200 && last.statusCode < 300;
+  return { code: last.statusCode || null, status: ok ? 'active' : 'failed', message: ok ? 'OK' : (last.error ?? `Invalid HTTP Response: ${last.statusCode}`) };
+}
+
+// a delivery takes no World time, so its duration is 0; a repository's hook belongs to no installation
+function deliveryJson(d: Delivery, detail: boolean, repositoryId: number | null): Record<string, unknown> {
+  return {
+    id: d.id, guid: d.guid, delivered_at: d.deliveredAt, redelivery: d.redelivery, duration: 0, installation_id: null, repository_id: repositoryId,
+    status: d.statusCode === null ? 'Pending' : d.statusCode >= 200 && d.statusCode < 300 ? 'OK' : d.error ?? 'Failed',
+    status_code: d.statusCode, event: d.event, action: d.action ?? null,
+    ...(detail ? { url: d.url, request: { headers: d.requestHeaders, payload: JSON.parse(d.payloadJson) }, response: { headers: d.responseHeaders ?? {}, payload: d.responseBody ?? null } } : {}),
+  };
+}
+
+/** A GitHub App's own webhook deliveries, newest first (docs.github.com/rest/apps/webhooks#list-deliveries-for-an-app-webhook):
+ *  each names the installation its payload was for; one delivery in detail carries its request and response. */
+export function githubAppDeliveries(appId: number, root?: string): Record<string, unknown>[] {
+  return records(root).filter((d) => d.repository === '' && d.hookId === appId).sort((a, b) => b.id - a.id).map((d) => appDeliveryJson(d, false));
+}
+export function githubAppDelivery(appId: number, id: number, root?: string): Record<string, unknown> | undefined {
+  const d = records(root).find((x) => x.repository === '' && x.hookId === appId && x.id === id);
+  return d && appDeliveryJson(d, true);
+}
+function appDeliveryJson(d: Delivery, detail: boolean): Record<string, unknown> {
+  const payload = JSON.parse(d.payloadJson) as { installation?: { id?: number }; repository?: { id?: number } };
+  return { ...deliveryJson(d, detail, typeof payload.repository?.id === 'number' ? payload.repository.id : null), installation_id: payload.installation?.id ?? null };
+}
+
+/** Native delivery/ping routes, shared by CLI serve and in-process callers. */
+export async function handleGithubWebhookRequest(request: Request, opts: Options & { readOnly?: boolean }): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const match = /^\/repos\/([^/]+)\/([^/]+)\/hooks\/(\d+)\/(deliveries(?:\/(\d+)(?:\/(attempts))?)?|pings)\/?$/.exec(url.pathname);
+  if (!match) return;
+  const repository = `${decodeURIComponent(match[1]!)}/${decodeURIComponent(match[2]!)}`;
+  const hook = hookFor(repository, Number(match[3]), opts.root);
+  const missing = () => Response.json({ message: 'Not Found' }, { status: 404 });
+  if (!hook) return missing();
+  if (request.method === 'POST' && opts.readOnly) return Response.json({ message: 'Read-only mirror' }, { status: 403 });
+  if (match[4] === 'pings') {
+    if (request.method !== 'POST') return missing();
+    await pingGithubHook(repository, hook.id, opts);
+    return new Response(null, { status: 204 });
+  }
+  const all = records(opts.root).filter(d => d.repository === repository && d.hookId === hook.id).sort((a, b) => b.id - a.id);
+  const repoId = githubState(opts.root).repos.find((r) => r.full_name === repository)?.id ?? null;
+  if (!match[5]) {
+    if (request.method !== 'GET') return missing();
+    const perPage = Number(url.searchParams.get('per_page') ?? 30);
+    const cursor = url.searchParams.get('cursor');
+    const status = url.searchParams.get('status');
+    if (!Number.isInteger(perPage) || perPage < 1 || perPage > 100 || cursor !== null && !/^\d+$/.test(cursor) || status !== null && !['success', 'failure'].includes(status)) return Response.json({ message: 'Validation Failed' }, { status: 422 });
+    const eligible = all.filter(d => (cursor === null || d.id < Number(cursor)) && (status === null || (status === 'success'
+      ? d.statusCode !== null && d.statusCode >= 200 && d.statusCode <= 399
+      : d.statusCode !== null && d.statusCode >= 400 && d.statusCode <= 599)));
+    const page = eligible.slice(0, perPage);
+    const headers: Record<string, string> = {};
+    if (eligible.length > page.length) { url.searchParams.set('cursor', String(page.at(-1)!.id)); headers.link = `<${url.href}>; rel="next"`; }
+    return Response.json(page.map(d => deliveryJson(d, false, repoId)), { headers });
+  }
+  const delivery = all.find(d => d.id === Number(match[5]));
+  if (!delivery) return missing();
+  if (match[6] === 'attempts' && request.method === 'POST') {
+    await dispatch(hook, delivery.event, JSON.parse(delivery.payloadJson), opts, delivery);
+    return new Response(null, { status: 202 });
+  }
+  return !match[6] && request.method === 'GET' ? Response.json(deliveryJson(delivery, true, repoId)) : missing();
+}

package/src/github-git-http.ts

@@ -26,17 +26,15 @@
 // Data REST reads fall back to it (github-twin.ts).
 //
 // Each branch-ref change also yields a `push` webhook event (ref/before/after), which the
-// server emits through the pack's EXISTING emitGithubEvent pipeline — a git push fires the
-// same webhook machinery a REST contents write does.
+// server announces as a REST contents write's is — GitHub's push reactions and the webhook.
 //
-// Offline + deterministic: everything here is local files + local `git` subprocesses (no
-// network, no rate budget). Failure to spawn git throws loudly (github-git-plane.ts).
-import { gunzipSync } from 'node:zlib';
-import { applyTwinWrite } from '@volter/twin';
-import {
-  bareRepoDir, ensureBareRepo, hasBareRepo, listGitPlaneRefs, runGit, type PlaneRef,
-} from './github-git-plane.ts';
-import { closePrsForDeletedBranch, githubState, syncPrHeadsToBranchTip, type GithubWriteEvent } from './github-twin.ts';
+// Offline + deterministic: everything here is the kernel's git library over the World's
+// blob store (no network, no rate budget, no `git` binary).
+import { applyTwinWrite, git } from '@volter/world-core';
+const { serveSmartHttp, serveSmartHttpPost } = git;
+import { ensureBareRepo, hasBareRepo, listGitPlaneRefs, planeRepo, type PlaneRef } from './github-git-plane.ts';
+import { closePrsForDeletedBranch, githubState, kernelAtomic, syncPrHeadsToBranchTip, type GithubWriteEvent } from './github-twin.ts';
+import { directPushRules } from './semantics/push-reactions.ts';
 
 const SERVICE = 'github';
 
@@ -65,17 +63,10 @@ export type GitSmartHttpResponse = {
   status: number;
   contentType: string;
   body: Uint8Array;
-  /** push webhook events (receive-pack only) — the caller emits them via emitGithubEvent. */
+  /** push webhook events (receive-pack only) — the server announces them. */
   webhooks: GithubWriteEvent[];
 };
 
-// One pkt-line: 4-byte hex length (including the length itself) + payload (gitprotocol-common(5)).
-function pktLine(payload: string): Buffer {
-  const data = Buffer.from(payload, 'utf8');
-  return Buffer.concat([Buffer.from((data.length + 4).toString(16).padStart(4, '0'), 'utf8'), data]);
-}
-const FLUSH_PKT = Buffer.from('0000', 'utf8');
-
 function plain(status: number, message: string): GitSmartHttpResponse {
   return { status, contentType: 'text/plain; charset=utf-8', body: Buffer.from(`${message}\n`, 'utf8'), webhooks: [] };
 }
@@ -88,22 +79,19 @@ function repoNotFound(): GitSmartHttpResponse {
 // The bare repo must exist to be served. A repo the CONTROL plane knows (created via REST
 // before the git plane existed, or pulled from real GitHub) is materialized on first
 // protocol contact — creating a repo via REST initializes its bare repo either way.
-function resolveRepoDir(repo: string, root?: string): string | null {
-  if (hasBareRepo(repo, root)) return bareRepoDir(repo, root);
+/** The repository's refs exist, or are created for a repository the twin knows (its default branch). */
+function resolvePlaneRepo(repo: string, root?: string): boolean {
+  if (hasBareRepo(repo, root)) return true;
   const known = githubState(root).repos.find((r) => r.full_name === repo);
-  if (!known) return null;
-  return ensureBareRepo(repo, root, known.default_branch ?? 'main');
-}
-
-function serviceEnv(gitProtocol?: string): Record<string, string> | undefined {
-  // Protocol v2 negotiation rides the Git-Protocol header end-to-end (gitprotocol-http(5)).
-  return gitProtocol ? { GIT_PROTOCOL: gitProtocol } : undefined;
+  if (!known) return false;
+  ensureBareRepo(repo, root, known.default_branch ?? 'main');
+  return true;
 }
 
 /**
- * Handle one git smart-HTTP request. Transport-agnostic (the Bun server bridges Request →
- * this) so tests and saboteurs hit the same seam the wire does. Returns null for non-git
- * routes (the caller falls through to the REST handler).
+ * Smart HTTP over the kernel library (`serveSmartHttp`): the advertisement, upload-pack and
+ * receive-pack — no `git` binary. A push's applied ref commands reach the twin through the
+ * reconciliation below (git_ref / branch rows, PR heads, the push webhooks).
  */
 export async function handleGithubGitSmartHttp(req: {
   method: string;
@@ -114,72 +102,52 @@ export async function handleGithubGitSmartHttp(req: {
   readOnly?: boolean;
   /** request Content-Encoding (git clients gzip large POST bodies) */
   contentEncoding?: string;
-  /** request Git-Protocol header (protocol v2 negotiation) */
+  /** request Git-Protocol header (protocol v2 negotiation — the library answers v0, as git falls back to) */
   gitProtocol?: string;
   occurredAt?: string;
 }): Promise<GitSmartHttpResponse | null> {
   const route = parseGitSmartHttpPath(req.method, req.pathname);
   if (!route) return null;
-
-  // ── GET info/refs — the smart service advertisement ─────────────────────────────────────
+  const tail = route.kind === 'info-refs' ? 'info/refs' : route.kind === 'upload-pack' ? 'git-upload-pack' : 'git-receive-pack';
   if (route.kind === 'info-refs') {
     const service = req.query?.get('service') ?? '';
     if (service !== 'git-upload-pack' && service !== 'git-receive-pack') {
-      // Only the smart protocol is served. 403 is the FIRST-PARTY refusal status: git's own
-      // http-backend answers "403 Forbidden — Dumb HTTP protocol not supported" when dumb
-      // HTTP is disabled (http-backend.c), and GitHub refuses dumb clients the same way.
       return plain(403, 'Dumb HTTP protocol is not supported: pass ?service=git-upload-pack or ?service=git-receive-pack.');
     }
     if (service === 'git-receive-pack' && req.readOnly) return plain(403, 'twin is read-only (mirror mode); pushes are rejected');
-    const dir = resolveRepoDir(route.repo, req.root);
-    if (!dir) return repoNotFound();
-    const cmd = service === 'git-upload-pack' ? 'upload-pack' : 'receive-pack';
-    const res = runGit(dir, [cmd, '--stateless-rpc', '--advertise-refs', '.'], { env: serviceEnv(req.gitProtocol) });
-    if (res.code !== 0) throw new Error(`github twin git plane: \`git ${cmd} --advertise-refs\` failed (exit ${res.code}): ${res.stderr.trim()}`);
-    return {
-      status: 200,
-      contentType: `application/x-${service}-advertisement`,
-      body: Buffer.concat([pktLine(`# service=${service}\n`), FLUSH_PKT, res.stdout]),
-      webhooks: [],
-    };
   }
-
-  // ── POST git-upload-pack / git-receive-pack — the stateless RPC ─────────────────────────
-  // Read-only refusal comes FIRST on both routes (same ordering as the advertisement): a
-  // mirror answers 403 to a push whether or not the repo exists.
   if (route.kind === 'receive-pack' && req.readOnly) return plain(403, 'twin is read-only (mirror mode); pushes are rejected');
-  const dir = resolveRepoDir(route.repo, req.root);
-  if (!dir) return repoNotFound();
-  let input: Uint8Array = req.body ?? new Uint8Array();
-  if ((req.contentEncoding ?? '').includes('gzip')) {
-    // Bounded + non-throwing: a malformed or bomb-sized body is the CLIENT's protocol error
-    // (400), never an unhandled 500. 256 MiB comfortably covers any local twin push.
-    try { input = gunzipSync(input, { maxOutputLength: 256 * 1024 * 1024 }); }
-    catch { return plain(400, 'Invalid or oversized gzip request body.'); }
-  }
-  const cmd = route.kind === 'upload-pack' ? 'upload-pack' : 'receive-pack';
-  const before = route.kind === 'receive-pack' ? listGitPlaneRefs(route.repo, req.root) : [];
-  const res = runGit(dir, [cmd, '--stateless-rpc', '.'], { stdin: input, env: serviceEnv(req.gitProtocol) });
-  if (res.code !== 0) {
-    // A garbage/aborted request makes the service exit non-zero. Whatever it managed to say
-    // rides back IN-BAND (that is how the wire reports protocol errors — the client renders
-    // it); with nothing on stdout, answer a 400 naming the failure. Never an unhandled 500.
-    if (res.stdout.length === 0) return plain(400, `git ${cmd} rejected the request: ${res.stderr.trim() || 'protocol error'}`);
-  }
-  const webhooks = route.kind === 'receive-pack'
+  if (!resolvePlaneRepo(route.repo, req.root)) return repoNotFound();
+  const before = route.kind === 'receive-pack' ? await listGitPlaneRefs(route.repo, req.root) : [];
+  // POST hands the kernel the body already in hand; a Request round-trip would copy the whole pack.
+  const answer = route.kind === 'info-refs'
+    ? await serveSmartHttp(new Request(`http://twin/${route.repo}.git/info/refs?service=${req.query?.get('service') ?? ''}`), planeRepo(route.repo, req.root), tail)
+    : await serveSmartHttpPost(req.body ?? new Uint8Array(), req.contentEncoding ?? '', { ...planeRepo(route.repo, req.root), policy: rulesPolicy(route.repo, req.root) }, tail as 'git-upload-pack' | 'git-receive-pack');
+  if (!answer) return null;
+  const body = new Uint8Array(await answer.arrayBuffer());
+  const webhooks = route.kind === 'receive-pack' && answer.status === 200
     ? await reconcileGitPlaneRefs(route.repo, before, { ...(req.root !== undefined ? { root: req.root } : {}), ...(req.occurredAt !== undefined ? { occurredAt: req.occurredAt } : {}) })
     : [];
-  return { status: 200, contentType: `application/x-git-${cmd}-result`, body: res.stdout, webhooks };
+  return { status: answer.status, contentType: answer.headers.get('content-type') ?? 'application/octet-stream', body, webhooks };
 }
 
 const ZERO_SHA = '0'.repeat(40);
 
+/** An active ruleset requiring pull requests refuses a direct push to its branch, as it refuses an API commit
+ *  (semantics/push-reactions.ts directPushRules); git reports the ref `ng` with GitHub's reason. */
+function rulesPolicy(repo: string, root?: string): (cmd: { name: string; new: string }) => string | null {
+  return (cmd) => {
+    if (!cmd.name.startsWith('refs/heads/') || cmd.new === ZERO_SHA) return null;
+    return directPushRules(githubState(root), repo, cmd.name.slice('refs/heads/'.length)).refused ? 'push declined due to repository rule violations' : null;
+  };
+}
+
 // Per-write ordinal folded into every reconcile write's fields: the kernel dedupes actions
 // by content + occurredAt millisecond, so a ref REVISITING a value under a pinned clock
 // (force-push A→B→A replayed in one ms) would silently collide with its own earlier action
-// and leave the projection at B while the bare repo says A (docs/ADDING_A_TWIN.md §5 — the
-// upstashredis `rev` pattern). Strictly increasing within the process; harmless extra field.
-let reconcileSeq = 0;
+// and leave the projection at B while the bare repo says A (docs/contributing/adding-a-twin.md §5 — the
+// upstash `rev` pattern). Strictly increasing within the process; harmless extra field.
+let reconcileSeq = 0; // counter: strictly increasing within the process; never state
 
 /**
  * Fold the bare repo's ref changes since `before` into the kernel event log — the SAME
@@ -194,7 +162,7 @@ export async function reconcileGitPlaneRefs(
 ): Promise<GithubWriteEvent[]> {
   const root = opts.root;
   const occurredAt = opts.occurredAt ?? new Date().toISOString();
-  const after = listGitPlaneRefs(repo, root);
+  const after = await listGitPlaneRefs(repo, root);
   const beforeBy = new Map(before.map((r) => [r.ref, r]));
   const afterBy = new Map(after.map((r) => [r.ref, r]));
   const events: GithubWriteEvent[] = [];
@@ -218,9 +186,7 @@ export async function reconcileGitPlaneRefs(
       }, root);
       // GitHub's `synchronize`: a push to a PR's head branch moves the PR head — the old
       // head's statuses/reviews stop matching (exact-head re-earn).
-      for (const n of await syncPrHeadsToBranchTip(repo, name, r.object_sha, root, occurredAt)) {
-        events.push({ event: 'pull_request', action: 'synchronize', repository: repo, number: n });
-      }
+      await syncPrHeadsToBranchTip(repo, name, r.object_sha, root, occurredAt, (pr, base) => events.push({ event: 'pull_request', action: 'synchronize', repository: base, number: Number(pr.number), pr }));
     }
     events.push({ event: 'push', action: '', repository: repo, number: 0, ref: r.ref, before: prev?.object_sha ?? ZERO_SHA, after: r.object_sha });
   }
@@ -228,19 +194,17 @@ export async function reconcileGitPlaneRefs(
     if (afterBy.has(r.ref)) continue;
     await applyTwinWrite(SERVICE, {
       operation: 'git_ref.delete', subjectType: 'git_ref', subjectId: `gitref:${repo}#${r.ref}`,
-      fields: { repository: repo, ref: r.ref, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
+      fields: { deleted: true, repository: repo, ref: r.ref, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
     }, root);
     const name = branchName(r.ref);
     if (name) {
       await applyTwinWrite(SERVICE, {
         operation: 'branch.delete', subjectType: 'branch', subjectId: `branch:${repo}#${name}`,
-        fields: { repository: repo, name, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
+        fields: { deleted: true, repository: repo, name, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
       }, root);
       // Real GitHub CLOSES an open PR whose head branch is deleted (shared with the REST
       // DELETE .../git/refs path — both converge on the same helper).
-      for (const n of await closePrsForDeletedBranch(repo, name, root, occurredAt)) {
-        events.push({ event: 'pull_request', action: 'closed', repository: repo, number: n });
-      }
+      await closePrsForDeletedBranch(repo, name, root, occurredAt, (pr, base) => events.push({ event: 'pull_request', action: 'closed', repository: base, number: Number(pr.number), pr }), kernelAtomic(occurredAt, root), { operation: 'git-receive-pack', actor: 'external' });
     }
     events.push({ event: 'push', action: '', repository: repo, number: 0, ref: r.ref, before: r.object_sha, after: ZERO_SHA });
   }