@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/github-events.d.ts

@@ -0,0 +1,41 @@
+import type { GithubWriteEvent } from './github-twin.js';
+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;
+};
+export declare function signGithubPayload(secret: string, body: string): string;
+/** Current persisted hook settings are resolved per event and World, including after restart. */
+export declare function emitGithubEvent(write: GithubWriteEvent, opts?: Options): Promise<GithubWebhook[]>;
+/** 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 declare function emitGithubInstallationEvents(write: GithubWriteEvent, opts?: Options): Promise<number>;
+/** 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 declare function emitGithubAppEvent(app: {
+    id: number;
+    hook_url?: string;
+    webhook_secret?: string;
+}, event: string, payload: GithubWebhook, opts?: Options): Promise<boolean>;
+export declare function pingGithubHook(repository: string, hookId: number, opts?: Options): Promise<boolean>;
+/** A hook's last delivery as GitHub reports it on the hook (`last_response`): unused until one is made. */
+export declare function hookLastResponse(repository: string, hookId: number, root?: string): Record<string, unknown>;
+/** 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 declare function githubAppDeliveries(appId: number, root?: string): Record<string, unknown>[];
+export declare function githubAppDelivery(appId: number, id: number, root?: string): Record<string, unknown> | undefined;
+/** Native delivery/ping routes, shared by CLI serve and in-process callers. */
+export declare function handleGithubWebhookRequest(request: Request, opts: Options & {
+    readOnly?: boolean;
+}): Promise<Response | undefined>;
+export {};

package/dist/src/github-events.js

@@ -0,0 +1,232 @@
+// 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.js";
+import { appDestination, appFetch } from '@volter/world-core/app-route';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+const TYPE = 'webhook_delivery';
+export function signGithubPayload(secret, body) {
+    return `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+}
+const httpDelivery = async (url, _event, _payload, headers, body) => {
+    // the World's egress rule: a refused hook URL fails as a transport failure, recorded on the delivery; the
+    // application's own hostnames reach it inside the World. GitHub follows no redirect: the 3xx is the delivery's answer.
+    const refusal = appDestination(url) ? null : worldEgressRefusal(url);
+    if (refusal !== null)
+        throw new Error(refusal);
+    const response = await appFetch(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, root) {
+    const response = await handleGithubRequest({ method: 'GET', path, root });
+    return response.status === 200 && response.body && !Array.isArray(response.body)
+        ? response.body : undefined;
+}
+async function buildPayload(write, root) {
+    const payload = { 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, path, root) {
+    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) {
+    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, write) {
+    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) {
+    return twinResources('github', root).filter(r => r.type === TYPE).map(r => ownFields(r));
+}
+function hookFor(repository, id, root) {
+    return githubState(root).webhooks.find(h => h.repository === repository && h.id === id);
+}
+function headersFor(hook, event, guid, body) {
+    const headers = {
+        '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;
+}
+async function dispatch(hook, event, payload, opts, original) {
+    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('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 = {
+            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;
+    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, opts = {}) {
+    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, write, opts) {
+    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, opts = {}) {
+    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 delivered;
+}
+const nodeIdOf = (type, id) => 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, event, payload, opts = {}) {
+    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] };
+    await dispatch(hook, event, payload, opts);
+    return true;
+}
+export async function pingGithubHook(repository, hookId, opts = {}) {
+    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, hookId, root) {
+    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, detail, repositoryId) {
+    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, root) {
+    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, id, root) {
+    const d = records(root).find((x) => x.repository === '' && x.hookId === appId && x.id === id);
+    return d && appDeliveryJson(d, true);
+}
+function appDeliveryJson(d, detail) {
+    const payload = JSON.parse(d.payloadJson);
+    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, opts) {
+    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 = {};
+        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/dist/src/github-git-http.d.ts

@@ -0,0 +1,49 @@
+import { type PlaneRef } from './github-git-plane.js';
+import { type GithubWriteEvent } from './github-twin.js';
+export type GitSmartHttpRoute = {
+    kind: 'info-refs';
+    repo: string;
+} | {
+    kind: 'upload-pack';
+    repo: string;
+} | {
+    kind: 'receive-pack';
+    repo: string;
+};
+/** Parse a smart-HTTP pathname; null when the path is not a git-protocol route. */
+export declare function parseGitSmartHttpPath(method: string, pathname: string): GitSmartHttpRoute | null;
+export type GitSmartHttpResponse = {
+    status: number;
+    contentType: string;
+    body: Uint8Array;
+    /** push webhook events (receive-pack only) — the server announces them. */
+    webhooks: GithubWriteEvent[];
+};
+/**
+ * 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 declare function handleGithubGitSmartHttp(req: {
+    method: string;
+    pathname: string;
+    query?: URLSearchParams;
+    body?: Uint8Array;
+    root?: string;
+    readOnly?: boolean;
+    /** request Content-Encoding (git clients gzip large POST bodies) */
+    contentEncoding?: string;
+    /** request Git-Protocol header (protocol v2 negotiation — the library answers v0, as git falls back to) */
+    gitProtocol?: string;
+    occurredAt?: string;
+}): Promise<GitSmartHttpResponse | null>;
+/**
+ * Fold the bare repo's ref changes since `before` into the kernel event log — the SAME
+ * git_ref.* / branch.* operations the Git Data REST writes append, so the control plane and
+ * the git plane converge on one ref record. Returns the `push` webhook events (one per
+ * changed branch/tag ref, GitHub-style ref/before/after).
+ */
+export declare function reconcileGitPlaneRefs(repo: string, before: PlaneRef[], opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<GithubWriteEvent[]>;

package/dist/src/github-git-http.js

@@ -0,0 +1,185 @@
+// GitHub twin git smart-HTTP — serves the REAL git wire protocol over the pack's REAL bare
+// repos (github-git-plane.ts), so an UNMODIFIED `git` CLI can clone from and push to the twin:
+//
+//   GET  /:owner/:repo[.git]/info/refs?service=git-upload-pack|git-receive-pack
+//   POST /:owner/:repo[.git]/git-upload-pack
+//   POST /:owner/:repo[.git]/git-receive-pack
+//
+// Implementation choice — `git upload-pack|receive-pack --stateless-rpc` SPAWNED DIRECTLY,
+// not `git http-backend` (CGI). Both are first-party; direct spawn is the simpler one to
+// GATE: http-backend adds a CGI translation layer (GIT_PROJECT_ROOT/PATH_INFO/QUERY_STRING/
+// REMOTE_USER env plumbing + CGI response-header parsing) whose plumbing would live in the
+// twin and need its own tests, while contributing no protocol behavior of its own —
+// http-backend itself execs exactly these two commands with exactly these flags
+// (gitprotocol-http(5), "Smart Service git-upload-pack"). Direct spawn leaves ONE seam
+// (this module) a mutation saboteur can kill and the fidelity oracle (a real `git` client)
+// can prove end-to-end. The only protocol framing the twin adds itself is the documented
+// service-advertisement prefix — one pkt-line (`# service=$servicename` LF) plus a
+// flush-pkt, per gitprotocol-http(5) "smart_reply" — everything else on the wire is
+// produced by real git.
+//
+// Reconciliation (the heart of the upgrade): after a receive-pack POST, ref changes in the
+// bare repo are FOLDED into the kernel event log (git_ref.* + branch.* actions — the same
+// operations the Git Data REST writes append), so a pushed branch is immediately visible to
+// the REST plane: GET git/refs, GET branches, PR head/base resolution. Objects are NOT
+// copied into kernel rows — the bare repo IS the object store (one store, not two); the Git
+// 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 announces as a REST contents write's is — GitHub's push reactions and the webhook.
+//
+// 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, worldNow } from '@volter/world-core';
+const { serveSmartHttp, serveSmartHttpPost } = git;
+import { ensureBareRepo, hasBareRepo, listGitPlaneRefs, planeRepo } from "./github-git-plane.js";
+import { closePrsForDeletedBranch, githubState, kernelAtomic, syncPrHeadsToBranchTip } from "./github-twin.js";
+import { directPushRules } from "./semantics/push-reactions.js";
+const SERVICE = 'github';
+/** Parse a smart-HTTP pathname; null when the path is not a git-protocol route. */
+export function parseGitSmartHttpPath(method, pathname) {
+    const m = /^\/([^/]+)\/([^/]+?)(?:\.git)?\/(info\/refs|git-upload-pack|git-receive-pack)$/.exec(pathname);
+    if (!m)
+        return null;
+    const owner = decodeURIComponent(m[1]);
+    const name = decodeURIComponent(m[2]);
+    // A name the plane's path validation would reject can never be a twin repo — fall through
+    // to the REST handler's vendor-shaped 404 instead of throwing a 500 out of bareRepoDir.
+    const SEG = /^[A-Za-z0-9_.-]+$/;
+    if (!SEG.test(owner) || !SEG.test(name) || owner === '.' || owner === '..' || name === '.' || name === '..')
+        return null;
+    const repo = `${owner}/${name}`;
+    if (m[3] === 'info/refs')
+        return method === 'GET' ? { kind: 'info-refs', repo } : null;
+    if (method !== 'POST')
+        return null;
+    return m[3] === 'git-upload-pack' ? { kind: 'upload-pack', repo } : { kind: 'receive-pack', repo };
+}
+function plain(status, message) {
+    return { status, contentType: 'text/plain; charset=utf-8', body: Buffer.from(`${message}\n`, 'utf8'), webhooks: [] };
+}
+/** The vendor-shaped miss: git clients render a 404 here as "repository not found". */
+function repoNotFound() {
+    return plain(404, 'Repository not found.');
+}
+// 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.
+/** The repository's refs exist, or are created for a repository the twin knows (its default branch). */
+function resolvePlaneRepo(repo, root) {
+    if (hasBareRepo(repo, root))
+        return true;
+    const known = githubState(root).repos.find((r) => r.full_name === repo);
+    if (!known)
+        return false;
+    ensureBareRepo(repo, root, known.default_branch ?? 'main');
+    return true;
+}
+/**
+ * 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) {
+    const route = parseGitSmartHttpPath(req.method, req.pathname);
+    if (!route)
+        return null;
+    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') {
+            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');
+    }
+    if (route.kind === 'receive-pack' && req.readOnly)
+        return plain(403, 'twin is read-only (mirror mode); pushes are rejected');
+    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);
+    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: 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, root) {
+    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/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
+ * git_ref.* / branch.* operations the Git Data REST writes append, so the control plane and
+ * the git plane converge on one ref record. Returns the `push` webhook events (one per
+ * changed branch/tag ref, GitHub-style ref/before/after).
+ */
+export async function reconcileGitPlaneRefs(repo, before, opts = {}) {
+    const root = opts.root;
+    const occurredAt = opts.occurredAt ?? worldNow();
+    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 = [];
+    const branchName = (ref) => (ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : null);
+    for (const r of after) {
+        const prev = beforeBy.get(r.ref);
+        if (prev && prev.object_sha === r.object_sha)
+            continue;
+        await applyTwinWrite(SERVICE, {
+            operation: prev ? 'git_ref.update' : 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${repo}#${r.ref}`,
+            fields: { repository: repo, ref: r.ref, object_sha: r.object_sha, object_type: r.object_type === 'tag' ? 'tag' : 'commit', rev: ++reconcileSeq },
+            occurredAt, actor: { kind: 'agent' },
+        }, root);
+        const name = branchName(r.ref);
+        if (name) {
+            await applyTwinWrite(SERVICE, {
+                operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${name}`,
+                fields: { repository: repo, name, commit_sha: r.object_sha, rev: ++reconcileSeq },
+                occurredAt, actor: { kind: 'agent' },
+            }, 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).
+            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 });
+    }
+    for (const r of before) {
+        if (afterBy.has(r.ref))
+            continue;
+        await applyTwinWrite(SERVICE, {
+            operation: 'git_ref.delete', subjectType: 'git_ref', subjectId: `gitref:${repo}#${r.ref}`,
+            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: { 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).
+            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 });
+    }
+    return events;
+}

package/dist/src/github-git-plane.d.ts

@@ -0,0 +1,114 @@
+import { git } from '@volter/world-core';
+declare const GitObjectStore: typeof git.GitObjectStore, GitRefs: typeof git.GitRefs;
+type GitObjectStore = InstanceType<typeof git.GitObjectStore>;
+type GitRefs = InstanceType<typeof git.GitRefs>;
+/** The git plane root for a twin instance: `<state>/github/git`. */
+export declare function githubGitPlaneDir(root?: string): string;
+/** A repository's ref prefix in the world store — `<plane>/<owner>/<name>.git` — after validating the name. */
+export declare function bareRepoDir(repo: string, root?: string): string;
+export declare function hasBareRepo(repo: string, root?: string): boolean;
+/** Create the repository's refs (HEAD → the default branch) when absent; answers its prefix. */
+export declare function ensureBareRepo(repo: string, root?: string, defaultBranch?: string): string;
+export declare function objectExistsInPlane(repo: string, sha: string, root?: string): Promise<boolean>;
+export declare function objectTypeInPlane(repo: string, sha: string, root?: string): Promise<string | null>;
+export declare function writeGitBlobToPlane(repo: string, contentB64: string, root?: string): Promise<string>;
+export declare function readGitBlobFromPlane(repo: string, sha: string, root?: string): Promise<{
+    content_b64: string;
+    size: number;
+} | null>;
+export type PlaneTreeEntry = {
+    path: string;
+    mode: string;
+    type: string;
+    sha: string;
+    size?: number;
+};
+/** A tree from `entries` over `baseTreeSha` (an entry with no sha deletes its path). */
+export declare function writeGitTreeToPlane(repo: string, entries: PlaneTreeEntry[], baseTreeSha: string | undefined, root?: string): Promise<string>;
+/** `ls-tree -l`: one level, blob sizes measured. */
+export declare function readGitTreeFromPlane(repo: string, sha: string, root?: string): Promise<PlaneTreeEntry[] | null>;
+export type PlaneIdent = {
+    name: string;
+    email: string;
+    date?: string;
+};
+export declare function writeGitCommitToPlane(repo: string, commit: {
+    message: string;
+    treeSha: string;
+    parents: string[];
+    author?: PlaneIdent;
+    committer?: PlaneIdent;
+    occurredAt: string;
+}, root?: string): Promise<string>;
+export type PlaneCommit = {
+    sha: string;
+    message: string;
+    tree_sha: string;
+    parents: string[];
+    author_name?: string;
+    author_email?: string;
+    created_at?: string;
+};
+export declare function readGitCommitFromPlane(repo: string, sha: string, root?: string): Promise<PlaneCommit | null>;
+export declare function writeGitTagToPlane(repo: string, tag: {
+    tag: string;
+    message: string;
+    objectSha: string;
+    objectType: string;
+    tagger?: PlaneIdent;
+    occurredAt: string;
+}, root?: string): Promise<string>;
+export type PlaneTag = {
+    sha: string;
+    tag: string;
+    message: string;
+    object_sha: string;
+    object_type: string;
+    tagger_name?: string;
+    created_at?: string;
+};
+export declare function readGitTagFromPlane(repo: string, sha: string, root?: string): Promise<PlaneTag | null>;
+/** Point `ref` at `sha` — only at an object the plane holds whole (a dangling chain is not clonable). */
+export declare function updateGitRefInPlane(repo: string, ref: string, sha: string, root?: string, expected?: string | null): Promise<boolean>;
+export declare function deleteGitRefInPlane(repo: string, ref: string, root?: string): Promise<void>;
+export type PlaneRef = {
+    ref: string;
+    object_sha: string;
+    object_type: string;
+};
+export declare function setBareRepoHead(repo: string, branch: string, root?: string): void;
+/** Drop the repository's refs; its objects stay in the world's store (content-addressed, shared). */
+export declare function deleteBareRepo(repo: string, root?: string): void;
+/** A fork shares the world's object store: copy the refs and HEAD, nothing else. */
+export declare function forkBareRepo(parentRepo: string, forkRepo: string, root?: string, defaultBranch?: string): void;
+export declare function isAncestorInPlane(repo: string, ancestor: string, descendant: string, root?: string): Promise<boolean>;
+export type PlaneDiffFile = {
+    filename: string;
+    status: string;
+    additions: number;
+    deletions: number;
+    sha?: string;
+    patch?: string;
+};
+export declare function mergeBaseInPlane(repo: string, a: string, b: string, root?: string): Promise<string | null>;
+/** GitHub's compare: merge-base(base, head)..head, as the library's `diffFiles` computes it. */
+export declare function diffFilesInPlane(repo: string, baseSha: string, headSha: string, root?: string, opts?: {
+    patch?: boolean;
+}): Promise<PlaneDiffFile[] | null>;
+export declare function isValidBranchName(name: string): boolean;
+/** `for-each-ref`: every ref with its object's sha and type. */
+export declare function listGitPlaneRefs(repo: string, root?: string): Promise<PlaneRef[]>;
+/** The library's view of a repository, for smart HTTP. */
+export declare function planeRepo(repo: string, root?: string): {
+    store: GitObjectStore;
+    refs: GitRefs;
+};
+/** 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 declare function mergeIntoBranchInPlane(repo: string, baseBranch: string, headSha: string, message: string, method: 'merge' | 'squash' | 'rebase', occurredAt: string, root?: string, merger?: PlaneIdent, dryRun?: boolean): Promise<{
+    sha: string;
+} | {
+    conflict: string;
+} | null>;
+export {};