@volter/world-core 2.0.37 → 3.0.1

package/dist/src/executor.d.ts

@@ -114,7 +114,10 @@ export type CredentialCustody = {
     open: () => Promise<CredentialPayload>;
     seal: (credential: CredentialPayload) => Promise<void> | void;
 };
+/** `vendor`: the vendor whose rate budget every call is charged to (D8): the call is priced and reserved before it is
+ *  made, refused when the budget is spent, and settled with the vendor's answer (its back-off honoured). */
 export type RemoteExecuteOptions = {
     custody?: CredentialCustody;
+    vendor?: string;
 };
 export declare function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options?: RemoteExecuteOptions): RemoteExecute;

package/dist/src/executor.js

@@ -1,3 +1,4 @@
+import { RateBudget } from "./rateBudget.js";
 const MAX_ORIGIN_LENGTH = 2048;
 function isLoopbackHost(hostname) {
     return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]' || hostname === '::1';
@@ -129,8 +130,24 @@ async function awsSigV4Headers(input) {
     };
 }
 export function buildRemoteExecute(origin, credential, auth, vendorHosts, options = {}) {
-    if (auth?.in === 'exchange')
-        return exchangeExecute(origin, credential, auth, vendorHosts, options.custody);
+    const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
+    return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
+}
+/** Every live call charged to the vendor's rate budget (rateBudget.ts, D8): a call the budget refuses is never made;
+ *  the ledger is the credential's (only its hash names it). */
+function budgeted(vendor, execute, token) {
+    const budget = new RateBudget({ vendor, token });
+    return async (request) => {
+        const url = new URL(request.path, 'http://budget.invalid');
+        const weight = budget.weightFor(`${request.method.toUpperCase()} ${url.pathname}`, Object.fromEntries(url.searchParams));
+        const reservation = budget.checkBudget(weight);
+        const answer = await execute(request);
+        budget.recordCall(weight, answer.headers, { status: answer.status, reservation });
+        return answer;
+    };
+}
+/** The call made as the root's credential is applied by the strategy (header replacement when none). */
+function direct(origin, credential, auth, vendorHosts) {
     return async ({ method, path, headers, body, responseType, presigned }) => {
         // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
         // sealed credential never goes with it, whatever host it names. A host other than the root's

package/dist/src/file-response.d.ts

@@ -1,3 +1,9 @@
 /** The content type a file's extension implies; `application/octet-stream` for the rest. */
 export declare function contentTypeOf(path: string): string;
 export declare function fileResponse(path: string, init?: ResponseInit): Response;
+/**
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
+ * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
+ * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ */
+export declare function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl?: string): Response;

package/dist/src/file-response.js

@@ -20,3 +20,33 @@ export function fileResponse(path, init) {
         headers.set('content-type', contentTypeOf(path));
     return new Response(readFileSync(path), { ...init, headers });
 }
+/**
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
+ * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
+ * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ */
+export function bytesResponse(request, bytes, contentType, cacheControl = 'public, max-age=604800, immutable') {
+    const total = bytes.length;
+    const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
+    const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
+    let start = 0;
+    let end = total - 1;
+    const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && Number(range[1]) > Number(range[2]));
+    if (valid) {
+        if (range[1] === '') {
+            start = Math.max(0, total - Number(range[2]));
+        }
+        else {
+            start = Number(range[1]);
+            end = range[2] === '' ? total - 1 : Math.min(Number(range[2]), total - 1);
+        }
+        if (start >= total || (range[1] === '' && Number(range[2]) === 0))
+            return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
+    }
+    const partial = start !== 0 || end !== total - 1;
+    const body = bytes.slice(start, end + 1);
+    return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+        status: partial ? 206 : 200,
+        headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+    });
+}

package/dist/src/fork.js

@@ -3,7 +3,7 @@ import { captureHistory, historyEntries, historyLength, historyPrefix, readHisto
 // The kernel registers parent ownership before publishing the pointer. Lifecycle removal
 // refuses while a child depends on that storage; direct filesystem deletion bypasses it.
 import { dirname, join } from 'node:path';
-import { checkParent, withAncestryLock } from "./ancestry.js";
+import { checkParent, withHistoryLock } from "./ancestry.js";
 import { getActiveWorldStore } from "./world-store.js";
 import { writeBranchMeta } from "./log.js";
 import { twinResources } from "./serve.js";
@@ -17,7 +17,8 @@ function forkMetaPath(service, root) {
  * References the base log at a position, then records the divergence baseline. `occurredAt` is supplied by the caller (deterministic; no clock).
  */
 export function forkTwin(opts) {
-    return withAncestryLock(() => {
+    // under the new branch's history lock; capturing the base nests the base's inside it (child before ancestor)
+    return withHistoryLock(worldPaths(opts.service, opts.toRoot).dir, () => {
         // A BRANCH IS A POINTER (log.ts): the base root and the position in its logs, nothing copied.
         // The branch reads the base's parent view and branch log up to that position as its own
         // parent, and records only its own entries from there. The base keeps appending past the

package/dist/src/git/history.d.ts

@@ -34,3 +34,10 @@ export declare function diffFiles(store: GitObjectStore, baseSha: string, headSh
 /** Three-way line merge. Return null for overlapping edits; preserve exact line endings.
  * Binary payloads belong to the caller's conflict path, never a text decoder's replacement. */
 export declare function mergeText(base: string, ours: string, theirs: string): string | null;
+/** The blob at a path in a commit (walking its trees segment by segment), or null when the commit, a directory on the
+ *  way or the file is not there. A host that serves a file at a revision (the Hugging Face Hub's `resolve`) reads it. */
+export declare function blobAt(store: GitObjectStore, commit: string, path: string): Promise<{
+    sha: string;
+    mode: string;
+    bytes: Uint8Array;
+} | null>;

package/dist/src/git/history.js

@@ -296,3 +296,27 @@ export function mergeText(base, ours, theirs) {
         result.splice(h.start, h.end - h.start, ...h.lines);
     return result.map(line => JSON.parse(line)).join('');
 }
+/** The blob at a path in a commit (walking its trees segment by segment), or null when the commit, a directory on the
+ *  way or the file is not there. A host that serves a file at a revision (the Hugging Face Hub's `resolve`) reads it. */
+export async function blobAt(store, commit, path) {
+    const c = await store.read(commit);
+    if (!c || c.type !== 'commit')
+        return null;
+    let tree = decodeCommit(c.payload).tree;
+    const parts = path.split('/').filter(Boolean);
+    for (const [i, name] of parts.entries()) {
+        const t = await store.read(tree);
+        if (!t || t.type !== 'tree')
+            return null;
+        const e = decodeTree(t.payload).find((x) => x.name === name);
+        if (!e)
+            return null;
+        if (i < parts.length - 1) {
+            tree = e.sha;
+            continue;
+        }
+        const b = await store.read(e.sha);
+        return b && b.type === 'blob' ? { sha: e.sha, mode: e.mode, bytes: b.payload } : null;
+    }
+    return null;
+}

package/dist/src/git/index.d.ts

@@ -4,3 +4,4 @@ export * from './pack.js';
 export * from './refs.js';
 export * from './smart-http.js';
 export * from './history.js';
+export * from './lfs.js';

package/dist/src/git/index.js

@@ -4,3 +4,4 @@ export * from "./pack.js";
 export * from "./refs.js";
 export * from "./smart-http.js";
 export * from "./history.js";
+export * from "./lfs.js";

package/dist/src/git/lfs.d.ts

@@ -0,0 +1,28 @@
+export declare const LFS_TYPE = "application/vnd.git-lfs+json";
+export type LfsObject = {
+    oid: string;
+    size: number;
+};
+/** Where a pack keeps its objects: by oid. */
+export type LfsStore = {
+    get(oid: string): Promise<Uint8Array | null>;
+    put(oid: string, bytes: Uint8Array): Promise<void>;
+};
+/** A pointer file's object (`version https://git-lfs.github.com/spec/v1`, `oid sha256:<hex>`, `size <n>`), or null
+ *  for any other file. */
+export declare function parseLfsPointer(file: Uint8Array | string): LfsObject | null;
+/** A pointer file's text for an object. */
+export declare const lfsPointer: (o: LfsObject) => string;
+/** An object's sha256, as its oid. */
+export declare function lfsOid(bytes: Uint8Array): Promise<string>;
+/** `POST …/info/lfs/objects/batch`: for each object asked, an upload's action (none when the object is held already) or
+ *  a download's (an error when it is not held), by the basic transfer. `href` names where an object goes up or comes
+ *  down; `header` is sent with each action. */
+export declare function lfsBatch(body: unknown, opts: {
+    store: LfsStore;
+    href: (operation: 'upload' | 'download', o: LfsObject) => string;
+    header?: Record<string, string>;
+}): Promise<Response>;
+/** A basic transfer's upload (`PUT` of the object's bytes): kept when they hash to the oid and have the declared size
+ *  (the size is the request's Content-Length when the caller has no other), else refused and nothing kept. */
+export declare function lfsUpload(bytes: Uint8Array, o: LfsObject, store: LfsStore): Promise<Response>;

package/dist/src/git/lfs.js

@@ -0,0 +1,66 @@
+// GIT LFS (architecture, "The tree contract": Git LFS is the git library's too): the batch API git-lfs speaks
+// (https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md, the basic transfer), a pointer file read
+// (https://github.com/git-lfs/git-lfs/blob/main/docs/spec.md), and an upload accepted only when its bytes hash to the
+// object's oid and its size is the one declared. The objects are the caller's (a pack's resource blobs, by oid); the
+// caller says where objects go up and come down (the vendor's own hosts) and decides who may do either before it calls.
+// Importing it does nothing.
+export const LFS_TYPE = 'application/vnd.git-lfs+json';
+const OID = /^[0-9a-f]{64}$/;
+const lfsJson = (status, body) => Response.json(body, { status, headers: { 'content-type': LFS_TYPE } });
+/** A pointer file's object (`version https://git-lfs.github.com/spec/v1`, `oid sha256:<hex>`, `size <n>`), or null
+ *  for any other file. */
+export function parseLfsPointer(file) {
+    const text = typeof file === 'string' ? file : file.length > 1024 ? '' : new TextDecoder().decode(file);
+    if (!text.startsWith('version https://git-lfs.github.com/spec/'))
+        return null;
+    const oid = /^oid sha256:([0-9a-f]{64})$/m.exec(text)?.[1];
+    const size = /^size (\d+)$/m.exec(text)?.[1];
+    return oid && size ? { oid, size: Number(size) } : null;
+}
+/** A pointer file's text for an object. */
+export const lfsPointer = (o) => `version https://git-lfs.github.com/spec/v1\noid sha256:${o.oid}\nsize ${o.size}\n`;
+/** An object's sha256, as its oid. */
+export async function lfsOid(bytes) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** `POST …/info/lfs/objects/batch`: for each object asked, an upload's action (none when the object is held already) or
+ *  a download's (an error when it is not held), by the basic transfer. `href` names where an object goes up or comes
+ *  down; `header` is sent with each action. */
+export async function lfsBatch(body, opts) {
+    const b = (body && typeof body === 'object' ? body : {});
+    // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "Should be download or upload."
+    if (b.operation !== 'upload' && b.operation !== 'download')
+        return lfsJson(422, { message: 'operation must be download or upload' });
+    if (Array.isArray(b.transfers) && b.transfers.length && !b.transfers.includes('basic'))
+        return lfsJson(422, { message: 'no transfer adapter in common: this server speaks basic' });
+    if (!Array.isArray(b.objects))
+        return lfsJson(422, { message: 'objects is required' });
+    const operation = b.operation;
+    const objects = [];
+    for (const raw of b.objects) {
+        const o = { oid: String(raw?.oid ?? ''), size: Number(raw?.size) };
+        // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object is invalid (for example, an invalid oid or size)."
+        if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || o.size < 0) {
+            objects.push({ ...o, error: { code: 422, message: 'Invalid object' } });
+            continue;
+        }
+        const held = await opts.store.get(o.oid);
+        if (operation === 'upload') {
+            objects.push(held ? { ...o, authenticated: true } : { ...o, authenticated: true, actions: { upload: { href: opts.href('upload', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } });
+        }
+        else {
+            // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object does not exist on the server."
+            objects.push(held ? { oid: o.oid, size: held.length, authenticated: true, actions: { download: { href: opts.href('download', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } } : { ...o, error: { code: 404, message: 'Object does not exist' } });
+        }
+    }
+    return lfsJson(200, { transfer: 'basic', objects, hash_algo: 'sha256' });
+}
+/** A basic transfer's upload (`PUT` of the object's bytes): kept when they hash to the oid and have the declared size
+ *  (the size is the request's Content-Length when the caller has no other), else refused and nothing kept. */
+export async function lfsUpload(bytes, o, store) {
+    if (bytes.length !== o.size || (await lfsOid(bytes)) !== o.oid)
+        return lfsJson(422, { message: `the object's bytes do not match ${o.oid} (${o.size} bytes)` });
+    await store.put(o.oid, bytes);
+    return new Response(null, { status: 200 });
+}

package/dist/src/git/objects.js

@@ -2,9 +2,10 @@
 // <size>\0<payload>`, zlib-deflated, addressed by the SHA-1 of the uncompressed form — written
 // and read through the active BlobStore under `<prefix>/objects/<ab>/<rest>`, the exact layout
 // a bare repository keeps. Pure JS: SHA-1 through WebCrypto, loose objects stored uncompressed in zlib framing (storeZlib),
-// a pack deflated through the standard CompressionStream, inflate through ./inflate.ts (it reports consumed bytes, which a packfile
+// a pack deflated through the kernel's `deflate` (bytes.ts), inflate through ./inflate.ts (it reports consumed bytes, which a packfile
 // reader needs). Bun and workerd alike; no `git` binary anywhere.
 import { inflateZlib } from "./inflate.js";
+import { deflate } from "../bytes.js";
 const ENC = new TextEncoder();
 const DEC = new TextDecoder();
 export async function sha1Hex(bytes) {
@@ -31,13 +32,7 @@ export function decodeLoose(bytes) {
     return { type: type, payload };
 }
 export async function hashObject(type, payload) { return sha1Hex(encodeLoose(type, payload)); }
-export async function deflateZlib(bytes) {
-    const cs = new CompressionStream('deflate');
-    const w = cs.writable.getWriter();
-    void w.write(new Uint8Array(bytes));
-    void w.close();
-    return new Uint8Array(await new Response(cs.readable).arrayBuffer());
-}
+export async function deflateZlib(bytes) { return deflate(bytes); }
 /** zlib with stored (uncompressed) deflate blocks: what git writes at `core.compression 0`, and what every
  *  inflater reads. A loose object is written on every commit a World makes; compressing each one through the
  *  asynchronous CompressionStream made a write's cost the stream's round trips, not the object's size. */

package/dist/src/git/smart-http.d.ts

@@ -16,7 +16,9 @@ export declare function readAllPktLines(bytes: Uint8Array): {
 export type Service = 'git-upload-pack' | 'git-receive-pack';
 /** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
 export declare function advertisement(service: Service, refs: GitRefs): Uint8Array;
-/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. */
+/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. A request with `deepen <n>` is shallow:
+ *  its answer opens with the shallow-update section (`shallow <sha>` for each boundary commit, `unshallow <sha>` for a
+ *  commit the client held shallow whose parents it now receives, then a flush), and its pack stops at the boundary. */
 export declare function uploadPack(body: Uint8Array, store: GitObjectStore): Promise<Uint8Array>;
 export type RefCommand = {
     old: string;

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

@@ -5,6 +5,7 @@
 // not advertised; a client that asks for it falls back to v0 on this answer, as git specifies.
 import { decodeCommit, decodeTag, decodeTree } from "./objects.js";
 import { readPack, writePack } from "./pack.js";
+import { gunzip } from "../bytes.js";
 const ENC = new TextEncoder();
 const DEC = new TextDecoder();
 export const ZERO_SHA = '0'.repeat(40);
@@ -55,7 +56,7 @@ function cat(...parts) { const out = new Uint8Array(parts.reduce((n, p) => n + p
     out.set(p, o);
     o += p.length;
 } return out; }
-const CAPS = { 'git-upload-pack': 'ofs-delta no-progress agent=volter-twin', 'git-receive-pack': 'report-status delete-refs ofs-delta agent=volter-twin' };
+const CAPS = { 'git-upload-pack': 'ofs-delta shallow no-progress agent=volter-twin', 'git-receive-pack': 'report-status delete-refs ofs-delta agent=volter-twin' };
 /** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
 export function advertisement(service, refs) {
     const all = refs.list();
@@ -104,11 +105,47 @@ async function closure(store, roots, seen) {
     return out;
 }
 async function reachable(store, roots) { const seen = new Set(); await closure(store, roots, seen); return seen; }
-/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. */
+/**
+ * A shallow request's commits (gitprotocol-pack, "Shallow requests"): every commit within `depth` of a want (a want is
+ * depth 1), and the boundary, the commits whose parents the client will not have. The client's own shallow commits it
+ * already has are boundaries it keeps unless this walk passes through them.
+ */
+async function deepened(store, wants, depth) {
+    const at = new Map();
+    const boundary = new Set();
+    let frontier = wants.map((sha) => ({ sha, d: 1 }));
+    while (frontier.length) {
+        const next = [];
+        for (const { sha, d } of frontier) {
+            if ((at.get(sha) ?? Infinity) <= d)
+                continue;
+            at.set(sha, d);
+            const obj = await store.read(sha);
+            if (obj?.type !== 'commit')
+                continue;
+            const parents = decodeCommit(obj.payload).parents;
+            if (d >= depth) {
+                if (parents.length)
+                    boundary.add(sha);
+                continue;
+            }
+            boundary.delete(sha);
+            for (const p of parents)
+                next.push({ sha: p, d: d + 1 });
+        }
+        frontier = next;
+    }
+    return { commits: [...at.keys()], boundary: [...boundary].filter((sha) => at.get(sha) >= depth) };
+}
+/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. A request with `deepen <n>` is shallow:
+ *  its answer opens with the shallow-update section (`shallow <sha>` for each boundary commit, `unshallow <sha>` for a
+ *  commit the client held shallow whose parents it now receives, then a flush), and its pack stops at the boundary. */
 export async function uploadPack(body, store) {
     const { lines } = readAllPktLines(body);
     const wants = lines.filter((l) => l.startsWith('want ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
     const haves = lines.filter((l) => l.startsWith('have ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
+    const clientShallow = lines.filter((l) => l.startsWith('shallow ')).map((l) => l.slice(8, 48)).filter((s) => SHA.test(s));
+    const depth = Number(/^deepen (\d+)/.exec(lines.find((l) => l.startsWith('deepen ')) ?? '')?.[1] ?? 0);
     const done = lines.some((l) => l.trim() === 'done');
     const known = [];
     for (const h of haves)
@@ -117,11 +154,35 @@ export async function uploadPack(body, store) {
     for (const w of wants)
         if (!(await store.has(w)))
             return pktLine(`ERR upload-pack: not our ref ${w}\n`);
+    const shallow = depth > 0 ? await deepened(store, wants, depth) : undefined;
+    const update = shallow
+        ? cat(...shallow.boundary.filter((sha) => !clientShallow.includes(sha)).map((sha) => pktLine(`shallow ${sha}\n`)), ...clientShallow.filter((sha) => shallow.commits.includes(sha) && !shallow.boundary.includes(sha)).map((sha) => pktLine(`unshallow ${sha}\n`)), FLUSH)
+        : new Uint8Array();
+    // a stateless client sends its wants and `deepen` alone first and reads only the shallow section back (git's
+    // fetch-pack, find_common); every later request carries haves or `done`, and its answer repeats the section before NAK
+    if (!done && shallow && haves.length === 0)
+        return update;
     if (!done)
-        return pktLine('NAK\n');
+        return cat(update, pktLine('NAK\n'));
     const seen = await reachable(store, known);
-    const objects = await closure(store, wants, seen);
-    return cat(pktLine('NAK\n'), await writePack(objects));
+    let objects;
+    if (shallow) {
+        objects = [];
+        for (const sha of shallow.commits) {
+            if (seen.has(sha))
+                continue;
+            seen.add(sha);
+            const obj = await store.read(sha);
+            if (!obj)
+                continue;
+            objects.push({ ...obj, sha });
+            if (obj.type === 'commit')
+                objects.push(...await closure(store, [decodeCommit(obj.payload).tree], seen));
+        }
+    }
+    else
+        objects = await closure(store, wants, seen);
+    return cat(update, pktLine('NAK\n'), await writePack(objects));
 }
 /** Bounded ancestry walk: is `ancestor` reachable from `sha` through parents? */
 export async function isAncestor(store, ancestor, sha, limit = 5000) {
@@ -212,7 +273,7 @@ export async function serveSmartHttp(req, repo, tailPath) {
  *  the size of the repository, so re-wrapping it in a Request only to read it back is a full copy. */
 export async function serveSmartHttpPost(body, contentEncoding, repo, tailPath) {
     if (contentEncoding.includes('gzip'))
-        body = new Uint8Array(await new Response(new Response(body).body.pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
+        body = await gunzip(body);
     const headers = { 'content-type': `application/x-${tailPath}-result`, 'cache-control': 'no-cache' };
     if (tailPath === 'git-upload-pack')
         return new Response((await uploadPack(body, repo.store)), { headers });

package/dist/src/graphql-wire.d.ts

@@ -0,0 +1,29 @@
+/** A resolver of one field, `Type.field`: its parent object, its arguments, and the request's handler context. */
+export type GraphqlResolver<C = unknown> = (source: Record<string, unknown>, args: Record<string, unknown>, ctx: C) => unknown;
+/** What a pack's `semantics/graphql.ts` exports as `graphql`. */
+export type GraphqlPart<C = unknown> = {
+    /** resolvers by `Type.field` (`Query.repository`, `PullRequest.state`) */
+    resolvers: Record<string, GraphqlResolver<C>>;
+    /** per type, a GraphQL field name → the object's field that holds it (`nameWithOwner` → `full_name`) */
+    aliases?: Record<string, Record<string, string>>;
+    /** per type, the object's fields the default resolver may read as they are */
+    stored?: Record<string, string[]>;
+};
+/** An error a resolver answers, with the vendor's `type` for it (GitHub's NOT_FOUND, UNPROCESSABLE). */
+export declare class GraphqlError extends Error {
+    readonly type?: string | undefined;
+    constructor(message: string, type?: string | undefined);
+}
+/** A GraphQL endpoint over a schema and a pack's part: answers a request's `{query, variables, operationName}`. The
+ *  context each resolver receives is made per request (the handler context). `unmodeled` answers a query selecting a
+ *  field nothing models; `mutationRefused`, when given, a mutation the World may not make (a read-only twin). */
+export declare function graphqlEndpoint<C>(options: {
+    sdl: string;
+    part: GraphqlPart<C>;
+    context: (request: Request) => Promise<C>;
+    unmodeled: (field: {
+        type: string;
+        field: string;
+    }) => Response;
+    mutationRefused?: (request: Request) => Response | undefined;
+}): (request: Request) => Promise<Response>;

package/dist/src/graphql-wire.js

@@ -0,0 +1,101 @@
+// THE GRAPHQL WIRE — a vendor's GraphQL API served from its published schema over the pack's state
+// (docs/contributing/architecture.md, "Other wires: lanes, headers and line protocols": GraphQL). A query is parsed and
+// validated against the vendor's own schema, so an unknown field is the GraphQL error the vendor gives. A field resolves
+// from the pack's resolver when it writes one (`semantics/graphql.ts`), else from the object its parent resolved: the
+// field's own name, its snake_case form, or the pack's alias for it. A list answering a `…Connection` field is a Relay
+// connection, and an enum resolves case-insensitively. The wire takes a query only when every field it selects is
+// modeled; any other is answered by the manifest's `graphql.unmodeled`, naming the first field nothing models. An error
+// a resolver throws (`GraphqlError`) carries its `type`, as GitHub's GraphQL errors do.
+//
+// The `graphql` protocol library is loaded the first time a GraphQL request comes (installed by the pack's package.json,
+// as node-postgres is for the managed database): the kernel's own dependencies stay B1's, and importing the kernel
+// loads nothing.
+/** An error a resolver answers, with the vendor's `type` for it (GitHub's NOT_FOUND, UNPROCESSABLE). */
+export class GraphqlError extends Error {
+    type;
+    constructor(message, type) {
+        super(message);
+        this.type = type;
+        this.name = 'GraphqlError';
+    }
+}
+let lib;
+const graphqlLib = () => (lib ??= import('graphql'));
+const snake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+/** A list as a Relay connection, paged by `first`/`last` and `after`. */
+function connection(items, args) {
+    const first = typeof args.first === 'number' ? args.first : undefined;
+    const last = typeof args.last === 'number' ? args.last : undefined;
+    const after = typeof args.after === 'string' ? Number(atob(args.after)) + 1 : 0;
+    let slice = items.slice(after);
+    if (first !== undefined)
+        slice = slice.slice(0, first);
+    if (last !== undefined)
+        slice = slice.slice(-last);
+    const start = after + (last !== undefined ? Math.max(0, items.slice(after).length - last) : 0);
+    const cursor = (i) => btoa(String(start + i));
+    return {
+        totalCount: items.length, nodes: slice, edges: slice.map((node, i) => ({ node, cursor: cursor(i) })),
+        pageInfo: { hasNextPage: start + slice.length < items.length, hasPreviousPage: start > 0, startCursor: slice.length ? cursor(0) : null, endCursor: slice.length ? cursor(slice.length - 1) : null },
+    };
+}
+/** A GraphQL endpoint over a schema and a pack's part: answers a request's `{query, variables, operationName}`. The
+ *  context each resolver receives is made per request (the handler context). `unmodeled` answers a query selecting a
+ *  field nothing models; `mutationRefused`, when given, a mutation the World may not make (a read-only twin). */
+export function graphqlEndpoint(options) {
+    let schema;
+    const { resolvers, aliases, stored } = options.part;
+    const modeled = (type, field) => field === '__typename' || `${type}.${field}` in resolvers || !!aliases?.[type]?.[field] || !!stored?.[type]?.includes(field) || !!stored?.[type]?.includes(snake(field));
+    return async (request) => {
+        const g = await graphqlLib();
+        schema ??= g.buildSchema(options.sdl, { assumeValidSDL: true });
+        const payload = (await request.clone().json().catch(() => ({})));
+        let document;
+        try {
+            document = g.parse(payload.query ?? '');
+        }
+        catch (error) {
+            return Response.json({ errors: [{ message: error instanceof Error ? error.message : String(error) }] });
+        }
+        const invalid = g.validate(schema, document);
+        if (invalid.length)
+            return Response.json({ errors: invalid.map((e) => ({ message: e.message, locations: e.locations })) });
+        const mutation = document.definitions.some((d) => d.kind === 'OperationDefinition' && d.operation === 'mutation');
+        if (mutation) {
+            const refused = options.mutationRefused?.(request);
+            if (refused)
+                return refused;
+        }
+        const typeInfo = new g.TypeInfo(schema);
+        let unmodeled;
+        g.visit(document, g.visitWithTypeInfo(typeInfo, {
+            Field(node) {
+                const parent = typeInfo.getParentType();
+                if (!unmodeled && parent && g.isObjectType(parent) && !parent.name.endsWith('Connection') && !parent.name.endsWith('Edge') && parent.name !== 'PageInfo' && !modeled(parent.name, node.name.value))
+                    unmodeled = { type: parent.name, field: node.name.value };
+            },
+        }));
+        if (unmodeled)
+            return options.unmodeled(unmodeled);
+        const ctx = await options.context(request);
+        const result = await g.execute({
+            schema, document, variableValues: payload.variables ?? {}, ...(payload.operationName ? { operationName: payload.operationName } : {}), contextValue: ctx,
+            fieldResolver: (source, args, context, info) => {
+                const own = resolvers[`${info.parentType.name}.${info.fieldName}`];
+                const obj = (source ?? {});
+                let value = own ? own(obj, args, context) : (obj[aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
+                const named = g.getNamedType(info.returnType);
+                if (Array.isArray(value) && g.isObjectType(named) && named.name.endsWith('Connection'))
+                    value = connection(value, args);
+                if (typeof value === 'string' && g.isEnumType(named))
+                    value = named.getValues().find((v) => v.name.toLowerCase() === String(value).toLowerCase())?.name ?? value;
+                return value;
+            },
+        });
+        const errors = (result.errors ?? []).map((e) => {
+            const type = e.originalError instanceof GraphqlError ? e.originalError.type : typeof e.extensions?.type === 'string' ? e.extensions.type : undefined;
+            return { ...(type ? { type } : {}), message: e.message, ...(e.path ? { path: e.path } : {}), ...(e.locations ? { locations: e.locations } : {}) };
+        });
+        return Response.json({ ...(result.data !== undefined ? { data: result.data } : {}), ...(errors.length ? { errors } : {}) });
+    };
+}

package/dist/src/grpc-wire.d.ts

@@ -0,0 +1,67 @@
+import { type H2Handler } from './h2.js';
+import { type ProtoSchema } from './protobuf.js';
+/** gRPC's status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
+export declare const GrpcStatus: {
+    readonly OK: 0;
+    readonly CANCELLED: 1;
+    readonly UNKNOWN: 2;
+    readonly INVALID_ARGUMENT: 3;
+    readonly DEADLINE_EXCEEDED: 4;
+    readonly NOT_FOUND: 5;
+    readonly ALREADY_EXISTS: 6;
+    readonly PERMISSION_DENIED: 7;
+    readonly RESOURCE_EXHAUSTED: 8;
+    readonly FAILED_PRECONDITION: 9;
+    readonly ABORTED: 10;
+    readonly OUT_OF_RANGE: 11;
+    readonly UNIMPLEMENTED: 12;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly DATA_LOSS: 15;
+    readonly UNAUTHENTICATED: 16;
+};
+/** A call answered with a gRPC status other than OK: its code and its message. */
+export declare class GrpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+export type GrpcCall = {
+    /** the operation the rpc is (the derive's name for it) and its path */
+    operation: string;
+    path: string;
+    /** the request message, in its proto3 JSON form */
+    request: Record<string, unknown>;
+    /** the call's metadata (its non-pseudo headers: `authorization`, `x-goog-api-client`, …) */
+    metadata: Record<string, string>;
+    /** aborted when the client cancels or its deadline passes */
+    signal: AbortSignal;
+};
+/** Answers one unary call with its response message's JSON form, or throws a GrpcError. */
+export type GrpcHandler = (call: GrpcCall) => Promise<Record<string, unknown>>;
+/** `grpc-timeout`: an integer and a unit (H M S m u n), PROTOCOL-HTTP2.md "Timeout". */
+export declare function parseGrpcTimeout(value: string | undefined): number | undefined;
+/** Length-prefixed messages out of a request body: [compressed flag][u32 length][bytes]… */
+export declare function splitGrpcFrames(body: Uint8Array): Array<{
+    compressed: boolean;
+    message: Uint8Array;
+}>;
+export declare function grpcFrame(message: Uint8Array): Uint8Array;
+/** grpc-message is percent-encoded (PROTOCOL-HTTP2.md "Status-Message"). */
+export declare function encodeGrpcMessage(text: string): string;
+/** The HTTP/2 stream handler that answers the unary rpcs of a proto unit's schema through `handler`. */
+export declare function grpcStreamHandler(schema: ProtoSchema, handler: GrpcHandler): H2Handler;
+/** A gRPC call answered by the pack's own fetch, as the derive serves a proto unit's rpc (`POST /<package>.<Service>/
+ *  <Method>`, the request message's JSON form the body): its JSON answer is the response message; any other status its
+ *  gRPC code, the error's message as the status message. */
+export declare function grpcOverFetch(fetch: (request: Request) => Promise<Response>): GrpcHandler;
+/** A pack that speaks gRPC, served on one port: HTTP/2 (gRPC, by the schema through the pack's fetch) and HTTP/1 (the
+ *  pack's fetch: its doors, its REST) on the same socket, as the kernel's HTTP/2 server tells them apart. Inside a World
+ *  it answers the World's boot probe as `serveHttp` does. */
+export declare function serveGrpc(options: {
+    port?: number;
+    fetch: (request: Request) => Promise<Response>;
+    schema: ProtoSchema;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;