@volter/world-core 2.0.37 → 3.0.1

package/src/git/lfs.ts

@@ -0,0 +1,67 @@
+// 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';
+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> };
+
+const OID = /^[0-9a-f]{64}$/;
+const lfsJson = (status: number, body: unknown): Response => 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: Uint8Array | string): LfsObject | null {
+  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: LfsObject): string => `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: Uint8Array): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes as unknown as ArrayBuffer);
+  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: unknown, opts: { store: LfsStore; href: (operation: 'upload' | 'download', o: LfsObject) => string; header?: Record<string, string> }): Promise<Response> {
+  const b = (body && typeof body === 'object' ? body : {}) as { operation?: unknown; transfers?: unknown; objects?: unknown };
+  // 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 as Array<{ oid?: unknown; size?: unknown }>) {
+    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: Uint8Array, o: LfsObject, store: LfsStore): Promise<Response> {
+  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/src/git/objects.ts

@@ -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.ts';
+import { deflate } from '../bytes.ts';
 import type { BlobStore } from '../blob-store.ts';
 
 export type GitObjectType = 'commit' | 'tree' | 'blob' | 'tag';
@@ -29,10 +30,7 @@ export function decodeLoose(bytes: Uint8Array): { type: GitObjectType; payload:
 }
 export async function hashObject(type: GitObjectType, payload: Uint8Array): Promise<string> { return sha1Hex(encodeLoose(type, payload)); }
 
-export async function deflateZlib(bytes: Uint8Array): Promise<Uint8Array> {
-  const cs = new CompressionStream('deflate'); const w = cs.writable.getWriter(); void w.write(new Uint8Array(bytes) as unknown as BufferSource); void w.close();
-  return new Uint8Array(await new Response(cs.readable).arrayBuffer());
-}
+export async function deflateZlib(bytes: Uint8Array): Promise<Uint8Array> { 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

package/src/git/smart-http.ts

@@ -5,6 +5,7 @@
 // not advertised; a client that asks for it falls back to v0 on this answer, as git specifies.
 import { GitObjectStore, decodeCommit, decodeTag, decodeTree, type GitObjectType } from './objects.ts';
 import { readPack, writePack } from './pack.ts';
+import { gunzip } from '../bytes.ts';
 import type { GitRefs } from './refs.ts';
 
 const ENC = new TextEncoder(); const DEC = new TextDecoder();
@@ -36,7 +37,7 @@ const SHA = /^[0-9a-f]{40}$/;
 function cat(...parts: Uint8Array[]): Uint8Array { const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); let o = 0; for (const p of parts) { out.set(p, o); o += p.length; } return out; }
 
 export type Service = 'git-upload-pack' | 'git-receive-pack';
-const CAPS: Record<Service, string> = { 'git-upload-pack': 'ofs-delta no-progress agent=volter-twin', 'git-receive-pack': 'report-status delete-refs ofs-delta agent=volter-twin' };
+const CAPS: Record<Service, string> = { '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: Service, refs: GitRefs): Uint8Array {
@@ -67,17 +68,66 @@ async function closure(store: GitObjectStore, roots: string[], seen: Set<string>
 }
 async function reachable(store: GitObjectStore, roots: string[]): Promise<Set<string>> { const seen = new Set<string>(); 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: GitObjectStore, wants: string[], depth: number): Promise<{ commits: string[]; boundary: string[] }> {
+  const at = new Map<string, number>(); const boundary = new Set<string>();
+  let frontier = wants.map((sha) => ({ sha, d: 1 }));
+  while (frontier.length) {
+    const next: Array<{ sha: string; d: number }> = [];
+    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: Uint8Array, store: GitObjectStore): Promise<Uint8Array> {
   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: string[] = []; for (const h of haves) if (await store.has(h)) known.push(h);
   for (const w of wants) if (!(await store.has(w))) return pktLine(`ERR upload-pack: not our ref ${w}\n`);
-  if (!done) return pktLine('NAK\n');
-  const seen = await reachable(store, known); const objects = await closure(store, wants, seen);
-  return cat(pktLine('NAK\n'), await writePack(objects));
+  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 cat(update, pktLine('NAK\n'));
+  const seen = await reachable(store, known);
+  let objects: Array<{ type: GitObjectType; payload: Uint8Array; sha: string }>;
+  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));
 }
 
 export type RefCommand = { old: string; new: string; name: string; /** false when `new` does not descend from `old` (a force push); true for creates, deletes and fast-forwards. */ fastForward: boolean };
@@ -140,7 +190,7 @@ export async function serveSmartHttp(req: Request, repo: GitRepo, tailPath: stri
 /** The POST half of `serveSmartHttp` for a caller that already holds the body: a push pack is
  *  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: Uint8Array, contentEncoding: string, repo: GitRepo, tailPath: 'git-upload-pack' | 'git-receive-pack'): Promise<Response> {
-  if (contentEncoding.includes('gzip')) body = new Uint8Array(await new Response(new Response(body as unknown as BodyInit).body!.pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
+  if (contentEncoding.includes('gzip')) 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)) as unknown as BodyInit, { headers });
   const { response, applied } = await receivePack(body, repo.store, repo.refs, repo.policy);

package/src/graphql-wire.ts

@@ -0,0 +1,106 @@
+// 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.
+
+/** 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 class GraphqlError extends Error {
+  constructor(message: string, readonly type?: string) { super(message); this.name = 'GraphqlError'; }
+}
+
+type GraphqlLib = typeof import('graphql');
+let lib: Promise<GraphqlLib> | undefined;
+const graphqlLib = (): Promise<GraphqlLib> => (lib ??= import('graphql') as Promise<GraphqlLib>);
+
+const snake = (s: string): string => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+
+/** A list as a Relay connection, paged by `first`/`last` and `after`. */
+function connection(items: unknown[], args: Record<string, unknown>): Record<string, unknown> {
+  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: number): string => 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<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> {
+  let schema: import('graphql').GraphQLSchema | undefined;
+  const { resolvers, aliases, stored } = options.part;
+  const modeled = (type: string, field: string): boolean =>
+    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(() => ({}))) as { query?: string; variables?: Record<string, unknown>; operationName?: string };
+    let document: import('graphql').DocumentNode;
+    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: { type: string; field: string } | undefined;
+    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 ?? {}) as Record<string, unknown>;
+        let value = own ? own(obj, args as Record<string, unknown>, context as C) : (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 as Record<string, unknown>);
+        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/src/grpc-wire.ts

@@ -0,0 +1,159 @@
+// THE gRPC WIRE (architecture, "Other wires": gRPC): unary gRPC calls over the kernel's HTTP/2 server (./h2.ts), each
+// request's one length-prefixed message decoded by the proto unit's schema (./protobuf.ts) and handed to the pack's
+// handler for its operation, whose JSON answer is encoded back with the status trailers
+// (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). After the older catalog's temporal pack's
+// `temporal-grpc.ts`, over this repository's codec rather than protobufjs. Everything here is framing: which rpcs exist
+// and what they answer is the pack's. Importing it does nothing.
+import { acceptH2Connection, type H2Handler } from './h2.ts';
+import { nodeBuiltin, WORLD_BOOT_PATH } from './serve-http.ts';
+import { decodeMessage, encodeMessage, type ProtoSchema } from './protobuf.ts';
+
+/** gRPC's status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
+export const GrpcStatus = {
+  OK: 0, CANCELLED: 1, UNKNOWN: 2, INVALID_ARGUMENT: 3, DEADLINE_EXCEEDED: 4, NOT_FOUND: 5, ALREADY_EXISTS: 6,
+  PERMISSION_DENIED: 7, RESOURCE_EXHAUSTED: 8, FAILED_PRECONDITION: 9, ABORTED: 10, OUT_OF_RANGE: 11, UNIMPLEMENTED: 12,
+  INTERNAL: 13, UNAVAILABLE: 14, DATA_LOSS: 15, UNAUTHENTICATED: 16,
+} as const;
+
+/** A call answered with a gRPC status other than OK: its code and its message. */
+export class GrpcError extends Error {
+  constructor(readonly code: number, message: string) { super(message); }
+}
+
+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 function parseGrpcTimeout(value: string | undefined): number | undefined {
+  const match = /^(\d{1,8})([HMSmun])$/.exec(value ?? '');
+  if (!match) return undefined;
+  return Number(match[1]) * { H: 3_600_000, M: 60_000, S: 1000, m: 1, u: 0.001, n: 0.000001 }[match[2] as 'H'];
+}
+
+/** Length-prefixed messages out of a request body: [compressed flag][u32 length][bytes]… */
+export function splitGrpcFrames(body: Uint8Array): Array<{ compressed: boolean; message: Uint8Array }> {
+  const frames: Array<{ compressed: boolean; message: Uint8Array }> = [];
+  let offset = 0;
+  while (offset < body.length) {
+    if (body.length - offset < 5) throw new GrpcError(GrpcStatus.INTERNAL, 'truncated gRPC frame header');
+    const length = new DataView(body.buffer, body.byteOffset + offset, 5).getUint32(1);
+    if (body.length - offset - 5 < length) throw new GrpcError(GrpcStatus.INTERNAL, 'truncated gRPC message');
+    frames.push({ compressed: body[offset] === 1, message: body.subarray(offset + 5, offset + 5 + length) });
+    offset += 5 + length;
+  }
+  return frames;
+}
+
+export function grpcFrame(message: Uint8Array): Uint8Array {
+  const out = new Uint8Array(5 + message.length);
+  new DataView(out.buffer).setUint32(1, message.length);
+  out.set(message, 5);
+  return out;
+}
+
+/** grpc-message is percent-encoded (PROTOCOL-HTTP2.md "Status-Message"). */
+export function encodeGrpcMessage(text: string): string {
+  return Array.from(new TextEncoder().encode(text), (b) => (b >= 0x20 && b <= 0x7e && b !== 0x25 ? String.fromCharCode(b) : `%${b.toString(16).toUpperCase().padStart(2, '0')}`)).join('');
+}
+
+/** The HTTP/2 stream handler that answers the unary rpcs of a proto unit's schema through `handler`. */
+export function grpcStreamHandler(schema: ProtoSchema, handler: GrpcHandler): H2Handler {
+  return (request, response) => {
+    const headers = request.headers;
+    const fail = (code: number, message: string): void => {
+      if (response.closed) return;
+      response.headers([[':status', '200'], ['content-type', 'application/grpc'], ['grpc-status', String(code)], ['grpc-message', encodeGrpcMessage(message)]], true);
+    };
+    if (headers[':method'] !== 'POST' || !(headers['content-type'] ?? '').startsWith('application/grpc')) {
+      response.headers([[':status', '415'], ['content-type', 'text/plain']], true);
+      return;
+    }
+    const path = headers[':path'] ?? '';
+    const rpc = schema.rpcs[path];
+    if (!rpc) { fail(GrpcStatus.UNIMPLEMENTED, `unknown method ${path}`); return; }
+    if (rpc.clientStreams || rpc.serverStreams) { fail(GrpcStatus.UNIMPLEMENTED, `${path} streams; this wire answers unary calls`); return; }
+    const timeout = parseGrpcTimeout(headers['grpc-timeout']);
+    const controller = new AbortController();
+    // a call ends once: its deadline passing answers DEADLINE_EXCEEDED, and the client going away (its stream reset)
+    // is CANCELLED, which no one hears; the handler's later answer, either way, is dropped
+    // (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md "Timeout", statuscodes.md "CANCELLED")
+    let ended: number | undefined;
+    const end = (code: number): void => { if (ended !== undefined) return; ended = code; controller.abort(); if (code === GrpcStatus.DEADLINE_EXCEEDED) fail(code, 'Deadline Exceeded'); };
+    const timer = timeout !== undefined ? setTimeout(() => end(GrpcStatus.DEADLINE_EXCEEDED), timeout) : undefined;
+    request.signal.addEventListener('abort', () => end(GrpcStatus.CANCELLED), { once: true });
+    const metadata = Object.fromEntries(Object.entries(headers).filter(([k]) => !k.startsWith(':')));
+    let decoded: Record<string, unknown>;
+    try {
+      const frames = splitGrpcFrames(request.body);
+      if (frames.length !== 1) throw new GrpcError(GrpcStatus.INTERNAL, `a unary call carries exactly one message (got ${frames.length})`);
+      if (frames[0]!.compressed) throw new GrpcError(GrpcStatus.UNIMPLEMENTED, 'compressed messages are not accepted (no grpc-encoding is advertised)');
+      decoded = decodeMessage(schema, rpc.request, frames[0]!.message) as Record<string, unknown>;
+    } catch (error) {
+      if (timer) clearTimeout(timer);
+      fail(error instanceof GrpcError ? error.code : GrpcStatus.INTERNAL, (error as Error).message);
+      return;
+    }
+    void (async () => {
+      try {
+        const answer = await handler({ operation: rpc.operation, path, request: decoded, metadata, signal: controller.signal });
+        if (ended !== undefined || response.closed) return;
+        response.headers([[':status', '200'], ['content-type', 'application/grpc']]);
+        response.data(grpcFrame(encodeMessage(schema, rpc.response, answer)));
+        response.trailers([['grpc-status', '0']]);
+      } catch (error) {
+        if (ended !== undefined) return;
+        if (error instanceof GrpcError) fail(error.code, error.message);
+        else fail(GrpcStatus.INTERNAL, `internal error: ${(error as Error)?.message ?? String(error)}`);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    })();
+  };
+}
+
+/** A gRPC code for the HTTP status a pack's fetch answered: Google's REST error names it (`error.status`), else the
+ *  status's customary code (https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto, "HTTP Mapping"). */
+function codeOf(status: number, body: unknown): number {
+  const named = (body as { error?: { status?: unknown } } | undefined)?.error?.status;
+  if (typeof named === 'string' && named in GrpcStatus) return GrpcStatus[named as keyof typeof GrpcStatus];
+  return ({ 400: GrpcStatus.INVALID_ARGUMENT, 401: GrpcStatus.UNAUTHENTICATED, 403: GrpcStatus.PERMISSION_DENIED, 404: GrpcStatus.NOT_FOUND, 409: GrpcStatus.ABORTED, 429: GrpcStatus.RESOURCE_EXHAUSTED, 499: GrpcStatus.CANCELLED, 501: GrpcStatus.UNIMPLEMENTED, 503: GrpcStatus.UNAVAILABLE, 504: GrpcStatus.DEADLINE_EXCEEDED } as Record<number, number>)[status] ?? (status >= 500 ? GrpcStatus.INTERNAL : GrpcStatus.UNKNOWN);
+}
+
+/** 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 function grpcOverFetch(fetch: (request: Request) => Promise<Response>): GrpcHandler {
+  return async (call) => {
+    const res = await fetch(new Request(`http://twin${call.path}`, { method: 'POST', headers: { ...call.metadata, 'content-type': 'application/json' }, body: JSON.stringify(call.request), signal: call.signal }));
+    const text = await res.text();
+    let body: unknown;
+    try { body = text ? JSON.parse(text) : {}; } catch { body = undefined; }
+    if (res.ok) return (body ?? {}) as Record<string, unknown>;
+    const message = (body as { error?: { message?: unknown }; message?: unknown } | undefined)?.error?.message ?? (body as { message?: unknown } | undefined)?.message ?? text;
+    throw new GrpcError(codeOf(res.status, body), String(message).slice(0, 500));
+  };
+}
+
+/** 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 async function serveGrpc(options: { port?: number; fetch: (request: Request) => Promise<Response>; schema: ProtoSchema }): Promise<{ port: number; stop: () => void }> {
+  const net = nodeBuiltin<typeof import('node:net')>('node:net');
+  const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
+  const fetch = worldBoot ? (request: Request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(Response.json({ boot: worldBoot })) : options.fetch(request)) : options.fetch;
+  const handler = grpcStreamHandler(options.schema, grpcOverFetch(fetch));
+  const server = net.createServer((socket) => { acceptH2Connection(socket, handler, fetch); });
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => resolve()); });
+  const address = server.address();
+  return { port: typeof address === 'object' && address ? address.port : 0, stop: () => { server.close(); } };
+}