@volter/world-core 3.0.163 → 3.0.165

package/src/executor.ts

@@ -248,8 +248,8 @@ async function awsSigV4Headers(input: {
 /** `vendorHosts`: the pack's declared vendor host rules (its descriptor's `hosts`). An absolute https URL
  *  on one of them — an exact `host` rule whose `pathPattern` the path matches — is a second host of the
  *  same vendor that takes the credential (LinkedIn's image uploads on www.linkedin.com/dms-uploads,
- *  Instagram's rupload host); it is sent credentialed like an anchored call. Any other absolute URL is
- *  refused, as before. */
+ *  Instagram's rupload host); it is sent credentialed like an anchored call, as HTTP Basic when a rule naming
+ *  it names a `basic` user. Any other absolute URL is refused. */
 /** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
  *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
 /** `unsealed`: where a rotation the seal failed to keep is recorded durably (the field and the cause, never a value), since
@@ -326,6 +326,8 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     let target: URL;
     // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
     let vendorUrl: URL | undefined;
+    // the user a host that takes the token as HTTP Basic's password names it under (HostRule.basic)
+    let basicUser: string | undefined;
     if (/^https:\/\//i.test(path) && vendorHosts?.length) {
       // a second host the pack declares for this vendor, on a path its rule names: validated as the root is
       target = new URL(path);
@@ -335,6 +337,7 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
         && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname));
       const declared = vendorHosts.some((r) => !r.exclude && named(r)) && !vendorHosts.some((r) => r.exclude && named(r));
       if (!declared) throw new Error(`remote execute: ${target.host}${target.pathname.slice(0, 64)} is not a host this vendor's pack declares for this path`);
+      basicUser = vendorHosts.find((r) => !r.exclude && r.basic !== undefined && named(r))?.basic;
       // A loopback root is the vendor substitute. Preserve the vendor Host while retaining
       // the already-validated root's mounted path; an absolute URL never escapes that root.
       if (isLoopbackHost(origin.hostname)) {
@@ -352,6 +355,14 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // a credential the vendor issued in this perform is the request's authorization; the sealed one stays home
     if (issued !== undefined) outbound.set('authorization', issued);
     else for (const [name, value] of Object.entries(credential.headers)) outbound.set(name, value);
+    // A HOST THAT TAKES THE TOKEN AS HTTP BASIC: the sealed authorization header's credentials, after its scheme, are
+    // Basic's password under the rule's user; one sealed as Basic goes as it is, and none sealed refuses before egress
+    if (issued === undefined && basicUser !== undefined) {
+      const sealed = outbound.get('authorization') ?? '';
+      const token = /^\S+\s+(\S.*)$/.exec(sealed)?.[1];
+      if (token === undefined) throw new Error(`remote execute: ${target.host} takes the credential as HTTP Basic, and the sealed credential carries no authorization header`);
+      if (!/^basic\s/i.test(sealed)) outbound.set('authorization', `Basic ${btoa(`${basicUser}:${token}`)}`);
+    }
     // the vendor's host, kept over any the credential carries (a loopback twin routes by it, as the World's proxy's)
     if (vendorUrl) { outbound.set('host', vendorUrl.host); outbound.set('x-volter-twin-original-host', vendorUrl.host); }
 

package/src/file-response.ts

@@ -25,10 +25,16 @@ export function fileResponse(path: string, init?: ResponseInit): Response {
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; 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 (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
-export function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl = 'public, max-age=604800, immutable'): Response {
-  const total = bytes.length;
+export function bytesResponse(
+  request: Request,
+  bytes: Uint8Array | { size: number; range(start: number, end: number): Promise<Uint8Array | null> },
+  contentType: string,
+  cacheControl = 'public, max-age=604800, immutable',
+): Response {
+  const total = bytes instanceof Uint8Array ? bytes.length : bytes.size;
   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;
@@ -44,9 +50,25 @@ export function bytesResponse(request: Request, bytes: Uint8Array, contentType:
   // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
   // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
   const partial = valid;
-  const body = bytes.slice(start, end + 1);
-  return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+  let body: BodyInit | null = null;
+  if (request.method !== 'HEAD') {
+    if (bytes instanceof Uint8Array) body = new Blob([bytes.slice(start, end + 1)]);
+    else {
+      let at = start;
+      body = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          if (at > end) { controller.close(); return; }
+          const last = Math.min(at + 8 * 1024 * 1024 - 1, end);
+          const chunk = await bytes.range(at, last);
+          if (!chunk) { controller.error(new Error('stored bytes are gone')); return; }
+          controller.enqueue(chunk);
+          at = last + 1;
+        },
+      });
+    }
+  }
+  return new Response(body, {
     status: partial ? 206 : 200,
-    headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+    headers: { ...base, 'content-length': String(end + 1 - start), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
   });
 }

package/src/git/index.ts

@@ -6,3 +6,4 @@ export * from './smart-http.ts';
 export * from './history.ts';
 export * from './lfs.ts';
 export * from './format.ts';
+export * from './smart-http-client.ts';

package/src/git/smart-http-client.ts

@@ -0,0 +1,99 @@
+// THE CLIENT HALF OF SMART HTTP (gitprotocol-http, protocol v0): what `git fetch` and `git push` send to a server,
+// over a transport the caller supplies. The library opens no socket, holds no credential and names no host; a root's
+// refresh and deploy reach the vendor's git through it over the kernel executor (derived-real.ts, ADR 0031). It asks
+// only for what it reads: no side-band (the pack arrives bare), no multi_ack (one answer), no thin pack (every delta
+// base is in the pack or the store), ofs-delta (readPack resolves both delta kinds), and on a push report-status, with
+// atomic when the server offers it.
+import { concat, type GitObjectStore } from './objects.ts';
+import { readPack } from './pack.ts';
+import { FLUSH, ZERO_SHA, packObjects, pktLine, readPktLines, type Service } from './smart-http.ts';
+
+const DEC = new TextDecoder();
+const SHA = /^[0-9a-f]{40}$/;
+
+/** One exchange: `GET info/refs?service=<service>` when there is no body, `POST <service>` when there is. It answers
+ *  the response's bytes, and throws when the server did not answer 200. */
+export type SmartHttpTransport = (request: { service: Service; body?: Uint8Array }) => Promise<Uint8Array>;
+
+/** What a server advertises: its refs (peeled `^{}` lines dropped), the ref its HEAD names, and its capabilities. */
+export type RemoteRefs = { refs: Map<string, string>; head: string | null; caps: string[] };
+
+/** `GET info/refs?service=<service>`, read. */
+export async function lsRemote(transport: SmartHttpTransport, service: Service): Promise<RemoteRefs> {
+  let { lines, rest } = readPktLines(await transport({ service }));
+  if (lines[0]?.startsWith('# service=')) ({ lines, rest } = readPktLines(rest));
+  const refs = new Map<string, string>(); let head: string | null = null; let caps: string[] = [];
+  for (const raw of lines) {
+    const [line, offered] = raw.replace(/\n$/, '').split('\0') as [string, string | undefined];
+    if (line.startsWith('ERR ')) throw new Error(`git ${service}: ${line.slice(4)}`);
+    if (offered !== undefined) {
+      caps = offered.split(' ').filter(Boolean);
+      const symref = caps.find((c) => c.startsWith('symref=HEAD:'));
+      if (symref) head = symref.slice('symref=HEAD:'.length);
+    }
+    const sha = line.slice(0, 40); const name = line.slice(41);
+    if (!SHA.test(sha) || sha === ZERO_SHA || name === 'HEAD' || name.endsWith('^{}')) continue;
+    refs.set(name, sha);
+  }
+  return { refs, head, caps };
+}
+
+const isPack = (bytes: Uint8Array, at: number): boolean => DEC.decode(bytes.subarray(at, at + 4)) === 'PACK';
+
+/** `POST git-upload-pack` with `done`: every object `wants` reach and `haves` do not, read into `store`. */
+export async function fetchPack(transport: SmartHttpTransport, store: GitObjectStore, wants: string[], haves: string[]): Promise<void> {
+  if (wants.length === 0) return;
+  const answer = await transport({
+    service: 'git-upload-pack',
+    body: concat(
+      pktLine(`want ${wants[0]} ofs-delta no-progress agent=volter-twin\n`),
+      ...wants.slice(1).map((w) => pktLine(`want ${w}\n`)),
+      FLUSH,
+      ...haves.map((h) => pktLine(`have ${h}\n`)),
+      pktLine('done\n'),
+    ),
+  });
+  // the negotiation's ACK / NAK lines, then the pack
+  let at = 0;
+  while (at + 4 <= answer.length && !isPack(answer, at)) {
+    const len = parseInt(DEC.decode(answer.subarray(at, at + 4)), 16);
+    if (Number.isNaN(len)) break;
+    if (len < 4) { at += 4; continue; }
+    const line = DEC.decode(answer.subarray(at + 4, at + len));
+    if (line.startsWith('ERR ')) throw new Error(`git upload-pack: ${line.slice(4).trim()}`);
+    at += len;
+  }
+  if (!isPack(answer, at)) throw new Error('git upload-pack: the server answered no pack');
+  await readPack(answer.subarray(at), store);
+}
+
+/** One ref update a push asks for: `old` is the server's value as advertised (ZERO_SHA to create), `new` the object
+ *  to point it at (ZERO_SHA to delete). */
+export type PushCommand = { name: string; old: string; new: string };
+
+/** `POST git-receive-pack`: the commands and the pack of what they need beyond `haves`, atomic when `atomic` (the
+ *  server offered it). Answers each command's outcome by ref name: null when the server took it, else its reason. */
+export async function sendPack(transport: SmartHttpTransport, store: GitObjectStore, commands: PushCommand[], haves: string[], atomic = false): Promise<Map<string, string | null>> {
+  const updates = commands.filter((c) => c.new !== ZERO_SHA).map((c) => c.new);
+  const caps = `report-status${atomic ? ' atomic' : ''} agent=volter-twin`;
+  const answer = await transport({
+    service: 'git-receive-pack',
+    body: concat(
+      ...commands.map((c, i) => pktLine(`${c.old} ${c.new} ${c.name}${i === 0 ? `\0${caps}` : ''}\n`)),
+      FLUSH,
+      // a push of deletions alone sends no pack (gitprotocol-pack, "Pushing data to a server")
+      ...(updates.length ? [await packObjects(store, updates, haves)] : []),
+    ),
+  });
+  const report = readPktLines(answer).lines.map((l) => l.replace(/\n$/, ''));
+  const failure = report.find((l) => l.startsWith('ERR '));
+  if (failure) throw new Error(`git receive-pack: ${failure.slice(4)}`);
+  const unpack = report.find((l) => l.startsWith('unpack '))?.slice('unpack '.length);
+  if (unpack === undefined) throw new Error('git receive-pack: the server sent no report');
+  const out = new Map<string, string | null>(commands.map((c) => [c.name, unpack === 'ok' ? 'the server reported nothing for it' : `unpacker error: ${unpack}`]));
+  for (const l of report) {
+    if (l.startsWith('ok ')) out.set(l.slice(3), null);
+    else if (l.startsWith('ng ')) { const rest = l.slice(3); const sp = rest.indexOf(' '); out.set(sp === -1 ? rest : rest.slice(0, sp), sp === -1 ? 'refused' : rest.slice(sp + 1)); }
+  }
+  return out;
+}

package/src/git/smart-http.ts

@@ -68,6 +68,13 @@ 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; }
 
+/** The pack of every object `wants` reach that the `haves` the store holds do not: what a push sends (a client's
+ *  send-pack, smart-http-client.ts). */
+export async function packObjects(store: GitObjectStore, wants: string[], haves: string[]): Promise<Uint8Array> {
+  const known: string[] = []; for (const h of haves) if (await store.has(h)) known.push(h);
+  return writePack(await closure(store, wants, await reachable(store, known)));
+}
+
 /**
  * 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

package/src/head.ts

@@ -34,6 +34,9 @@ export type PushOutcome = {
   actionId?: string;
   /** the group's other entries the answer named an id for (a resource's `companions`) */
   also?: Array<{ actionId: string; externalId: string; data?: Record<string, unknown> }>;
+  /** the group's entries the vendor refused while it took the rest (a git push to a root without `atomic`, each ref its
+   *  own outcome: ADR 0031); each settles refused with its reason */
+  refused?: Array<{ actionId: string; reason: string }>;
 };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
  *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
@@ -269,6 +272,8 @@ export type DeployReport = {
   refused?: { actionId: string; check: string; reason: string };
   /** the first failure, with the vendor's words; nothing after it was attempted */
   failed?: { actionId: string; error: string };
+  /** a group the vendor took in part: its entries it refused, each with its reason; nothing after it was attempted */
+  partial?: Array<{ actionId: string; reason: string }>;
   /** entries after the refusal or failure, not attempted */
   skipped: string[];
   /** entries whose landed copy already said `deployed` — not performed again */
@@ -287,12 +292,13 @@ function receiptsByEntry(parent: Entry[]): Map<string, Receipt> {
 /** Whether an entry records a call of the vendor's surface (an operation or a GraphQL mutation): what a perform can send
  *  again (the real-system adapters, "What the derived core records with a write"). */
 function surfaceWrite(e: { input?: Record<string, unknown> }): boolean {
-  return typeof e.input?.operationId === 'string' || (e.input?.graphql !== undefined && e.input.graphql !== null);
+  // a push to a World repository is the vendor's too: a deploy sends it as a git push (derived-core.ts pushedInput)
+  return typeof e.input?.operationId === 'string' || (e.input?.graphql !== undefined && e.input.graphql !== null) || (e.input?.git !== undefined && e.input.git !== null);
 }
 
 /** The branch entries a root twin still has to settle: `set` rows, not reverted, whose landed copy is absent or says
  *  `failed`/`skipped` (a `deployed` or `refused` copy settles the entry), split into what is offered to the vendor (a
- *  surface write on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
+ *  surface write or a git push on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
  *  clock or a seed made, and any write on a subject only the World's own writes made. */
 export function settlingEntries(service: string, root?: string): { offered: TwinAction[]; worldOnly: TwinAction[] } {
   const parent = parentEntries(service, root);
@@ -436,7 +442,10 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
       const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? (outcome.data as Record<string, unknown>) : {};
       const primary = resolved.find((a) => a.id === outcome.actionId) ?? resolved[0]!;
       const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a]));
+      const refusedHere = new Map((outcome.refused ?? []).map((r) => [r.actionId, r.reason]));
       for (const action of resolved) {
+        const refusal = refusedHere.get(action.id);
+        if (refusal !== undefined) { settle(action, at, { status: 'refused', reason: refusal }); refusedIds.add(action.subject.id); continue; }
         const answeredId = action === primary ? outcome.externalId : also.get(action.id)?.externalId;
         const externalId = answeredId || aliases.get(`${action.subject.type}:${action.subject.id}`);
         settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, { ...action.fields, ...(action === primary ? answered : also.get(action.id)?.data ?? {}) }, externalId || undefined);
@@ -444,6 +453,7 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
         report.pushed += 1;
         report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(data !== undefined ? { data } : {}), ...(action === primary && outcome.response ? { response: outcome.response } : {}) });
       }
+      if (refusedHere.size) { report.partial = [...refusedHere].map(([actionId, reason]) => ({ actionId, reason })); stopped = true; }
     } catch (error) {
       // a write the vendor refuses (a 4xx: it can never be sent as it is) settles the group refused, as a check's
       // refusal does, so the next deploy moves on to the group after it; anything else failed and stays offered
@@ -515,7 +525,7 @@ export async function deferPerform<T>(request: string, fn: () => Promise<T>): Pr
 /** Under `auto`, perform the entries one request made as one call (the real-system adapters, "Perform"): the ids the
  *  vendor gave them by local id, or the vendor's refusal or failure, the request's entries reverted as performAtHead
  *  reverts one. Nothing when the head is not real and auto, or the request wrote nothing the vendor is offered. */
-export async function performRequestGroup(service: string, request: string, root?: string): Promise<{ ids: Map<string, string>; response?: RemoteExecuteResponse } | RefusedWriteError | VendorWriteError> {
+export async function performRequestGroup(service: string, request: string, root?: string): Promise<{ ids: Map<string, string>; response?: RemoteExecuteResponse; refused?: Array<{ actionId: string; reason: string }> } | RefusedWriteError | VendorWriteError> {
   const head = headOf(service, root);
   const ids = new Map<string, string>();
   if (head.kind !== 'real' || head.deploy !== 'auto') return { ids };
@@ -525,21 +535,42 @@ export async function performRequestGroup(service: string, request: string, root
   try { report = await performEntries({ service, actionIds: group.map((e) => e.id), ...(root !== undefined ? { root } : {}) }); }
   catch (error) {
     if (error instanceof DeploymentOrderError) {
-      for (const e of [...group].reverse()) revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+      revertRequest(service, request, group, root);
       return new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, group[0]!.id);
     }
     throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
   }
   if (report.refused || report.failed) {
-    for (const e of [...group].reverse()) revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+    revertRequest(service, request, group, root);
     return report.refused ? new RefusedWriteError(report.refused.check, report.refused.reason, report.refused.actionId) : new VendorWriteError(report.failed!.error, report.failed!.actionId);
   }
+  if (report.partial) revertRequest(service, request, group.filter((e) => report.partial!.some((r) => r.actionId === e.id)), root);
   for (const d of report.deployed) {
     const e = group.find((g) => g.id === d.actionId);
     if (e && d.externalId && d.externalId !== e.subject.id) ids.set(e.subject.id, d.externalId);
   }
   const response = report.deployed.find((entry) => entry.response)?.response;
-  return { ids, ...(response ? { response } : {}) };
+  return { ids, ...(response ? { response } : {}), ...(report.partial ? { refused: report.partial } : {}) };
+}
+
+/** Revert what a request's refused entries made, latest first. An entry that is a declared push a screen recorded
+ *  (`input.git`, ADR 0031) owns the request's writes after it up to the next such push, its push's effects (the
+ *  reactions and vendor moves the pack runs on it), which go with it; any other refused entry goes alone, as the group
+ *  it is in. */
+function revertRequest(service: string, request: string, refused: TwinAction[], root?: string): void {
+  const pushed = (e: { input?: Record<string, unknown> }): boolean => e.input?.git !== undefined && e.input.git !== null;
+  const undo = new Set<string>();
+  if (refused.some(pushed)) {
+    const made = (branchEntries(service, root) as TwinAction[]).filter((e) => e.correlationId === request && e.op === 'set');
+    for (const r of refused) {
+      if (!pushed(r)) { undo.add(r.id); continue; }
+      const at = made.findIndex((e) => e.id === r.id);
+      if (at < 0) { undo.add(r.id); continue; }
+      undo.add(r.id);
+      for (const e of made.slice(at + 1)) { if (pushed(e)) break; undo.add(e.id); }
+    }
+  } else for (const r of refused) undo.add(r.id);
+  for (const e of branchEntries(service, root).filter((x) => undo.has(x.id)).reverse()) revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
 }
 
 /** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the

package/src/html.ts

@@ -0,0 +1,72 @@
+// The WHATWG HTML grammar is shared mechanics; what a pack keeps of a document is the pack's own policy.
+// The exact optional dependency belongs to this kernel, so Node and browser bundles resolve one parser.
+// Source: parse5 7.3.0 (parseFragment, serialize, defaultTreeAdapter).
+//
+// A fragment is parsed in an HTML `<body>` context. Elements keep their namespace (HTML, SVG or MathML) and attributes
+// their prefix and namespace, and serialization reproduces what the tree holds: a foreign subtree survives parsing, and
+// a pack's policy may drop it.
+export type HtmlAttribute = { name: string; value: string; prefix?: string; namespace?: string };
+export type HtmlElement = { type: 'element'; name: string; namespace: string; attributes: HtmlAttribute[]; children: HtmlNode[] };
+export type HtmlText = { type: 'text'; value: string };
+export type HtmlNode = HtmlElement | HtmlText;
+export class HtmlError extends Error {
+  constructor(readonly code: 'parser-unavailable') {
+    super('HTML parser parse5 7.3.0 is unavailable');
+    this.name = 'HtmlError';
+  }
+}
+type Grammar = typeof import('parse5');
+type Tree = import('parse5').DefaultTreeAdapterMap;
+let grammar: Promise<Grammar> | undefined;
+function loadGrammar(): Promise<Grammar> {
+  return grammar ??= import('parse5').catch(() => { grammar = undefined; throw new HtmlError('parser-unavailable'); });
+}
+
+/**
+ * A fragment parsed as WHATWG fragment parsing does in an HTML `<body>` context: elements and text, comments dropped,
+ * an HTML `<template>`'s content carried as that element's children. Importing this module does not load the grammar.
+ */
+export async function parseFragment(source: string): Promise<HtmlNode[]> {
+  const { parseFragment: parse, defaultTreeAdapter: tree, html } = await loadGrammar();
+  const convert = (nodes: Tree['node'][]): HtmlNode[] => {
+    const out: HtmlNode[] = [];
+    for (const node of nodes) {
+      if (node.nodeName === '#text') out.push({ type: 'text', value: (node as Tree['textNode']).value });
+      else if ('tagName' in node) {
+        const element = node as Tree['element'];
+        // only an HTML template has content; an SVG or MathML `template` is a foreign element with children
+        const children = element.tagName === 'template' && element.namespaceURI === html.NS.HTML
+          ? (element as Tree['template']).content.childNodes
+          : element.childNodes;
+        out.push({
+          type: 'element', name: element.tagName, namespace: element.namespaceURI,
+          attributes: element.attrs.map(attr => ({ name: attr.name, value: attr.value, ...(attr.prefix ? { prefix: attr.prefix } : {}), ...(attr.namespace ? { namespace: attr.namespace } : {}) })),
+          children: convert(children),
+        });
+      }
+    }
+    return out;
+  };
+  return convert(parse(tree.createElement('body', html.NS.HTML, []), source, {}).childNodes);
+}
+
+/** Nodes serialized by the WHATWG HTML fragment serialization: its escaping, its void elements, its foreign names. */
+export async function serialize(nodes: HtmlNode[]): Promise<string> {
+  const { serialize: write, defaultTreeAdapter: tree, html } = await loadGrammar();
+  const append = (parent: Tree['parentNode'], list: HtmlNode[]): void => {
+    for (const node of list) {
+      if (node.type === 'text') { tree.insertText(parent, node.value); continue; }
+      const element = tree.createElement(node.name, node.namespace as import('parse5').html.NS,
+        node.attributes.map(({ name, value, prefix, namespace }) => ({ name, value, ...(prefix ? { prefix } : {}), ...(namespace ? { namespace } : {}) })));
+      tree.appendChild(parent, element);
+      if (node.name === 'template' && node.namespace === html.NS.HTML) {
+        const content = tree.createDocumentFragment();
+        tree.setTemplateContent(element as Tree['template'], content);
+        append(content, node.children);
+      } else append(element, node.children);
+    }
+  };
+  const fragment = tree.createDocumentFragment();
+  append(fragment, nodes);
+  return write(fragment);
+}

package/src/index.ts

@@ -76,11 +76,13 @@ export { passwordHash, personOf, personWith, recordPerson, shownPersonFields, ty
 // the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
-export type { Mail, SmtpRoute } from './smtp.ts';
+export type { Mail, MailReply } from './smtp.ts';
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
 export * as s3 from './s3/wire.ts';
 // Generic strict XML grammar; vendor interpretation remains in its consumer.
 export * as xml from './xml.ts';
+// Generic WHATWG HTML grammar; what a pack keeps of received HTML remains the pack's policy.
+export * as html from './html.ts';
 export * as clickhouse from './clickhouse/index.ts';
 export { sampleFromSchema } from './schema-sample.ts';
 export * as openaiWire from './openai-wire.ts';
@@ -89,8 +91,10 @@ export * as protobuf from './protobuf.ts';
 export * as grpc from './grpc-wire.ts';
 export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.ts';
 export { placeholderPng } from './placeholder-image.ts';
+export { imageDimensions, readImageHeader, readMp4Header } from './media-header.ts';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.ts';
 export * as redis from './redis/index.ts';
+export * as smtpServer from './smtp-server.ts';
 export * as mysql from './mysql/index.ts';
 export * as live from './live/index.ts';
 export * as mongodb from './mongodb/index.ts';
@@ -102,7 +106,7 @@ export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioE
 
 export { verifyAttestationBundle } from './attestation.ts';
 
-export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
 
 export { readHostPort } from './host-port.ts';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.ts';

package/src/managed-database.ts

@@ -254,10 +254,10 @@ export function managedDatabase(url: string, options: { readOnly?: boolean } = {
  *  walk/journey-kit.ts), its statements sent as its client sends them: a text alone as one simple Query (a migration
  *  file, a `BEGIN`), a text with values as one extended-protocol statement, the values bind parameters. A transaction it
  *  opens stays open across its statements until it ends it, as on the application's own connection. Each statement's
- *  answer is its results in Postgres's text format, untyped. */
-export type DatabaseSession = { query(text: string, values?: ReadonlyArray<string | null>): Promise<StatementResult[]>; end(): Promise<void> };
+ *  answer is its results in Postgres's text format, with native column type OIDs retained beside the values. */
+export type DatabaseSession = { query(text: string, values?: ReadonlyArray<string | null>): Promise<Array<StatementResult & { fieldTypes: number[] }>>; end(): Promise<void> };
 
-type PgResult = { command?: string | null; rowCount?: number | null; fields?: Array<{ name: string }>; rows?: Array<Array<string | null>> };
+type PgResult = { command?: string | null; rowCount?: number | null; fields?: Array<{ name: string; dataTypeID: number }>; rows?: Array<Array<string | null>> };
 
 /** The World's Postgres at `url` as one connection held until `end()`. */
 export async function databaseSession(url: string): Promise<DatabaseSession> {
@@ -277,6 +277,7 @@ export async function databaseSession(url: string): Promise<DatabaseSession> {
         const answer = (await (client.query({ text, ...(values === undefined ? {} : { values }), rowMode: 'array', types: raw }) as Promise<PgResult | PgResult[]>));
         return (Array.isArray(answer) ? answer : [answer]).map((r) => ({
           fields: (r.fields ?? []).map((f) => f.name),
+          fieldTypes: (r.fields ?? []).map((f) => f.dataTypeID),
           rows: r.rows ?? [],
           command: [r.command ?? '', r.command === 'INSERT' ? '0' : '', r.rowCount ?? ''].filter((part) => part !== '').join(' '),
         }));

package/src/media-header.ts

@@ -0,0 +1,108 @@
+// File-format headers only: no decoding, vendor limits, processing or rendition policy.
+type ImageType = 'image/png' | 'image/gif' | 'image/jpeg' | 'image/webp';
+type Dimensions = { width: number; height: number };
+type ImageHeader = Dimensions & { jpeg?: { frameEnd: number; nonMarkerBytes: boolean; standaloneMarkers: boolean; fillBytes: boolean; shortSegments: boolean } };
+
+const tag = (bytes: Uint8Array, at: number): string => String.fromCharCode(...bytes.subarray(at, at + 4));
+
+/** Dimensions in a caller-declared image format, or undefined for an incomplete header. */
+export function imageDimensions(bytes: Uint8Array, type: ImageType): ImageHeader | undefined {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (type === 'image/png') return bytes.length >= 24 ? { width: view.getUint32(16), height: view.getUint32(20) } : undefined;
+  if (type === 'image/gif') return bytes.length >= 10 ? { width: view.getUint16(6, true), height: view.getUint16(8, true) } : undefined;
+  if (type === 'image/webp') {
+    if (bytes.length < 30) return undefined;
+    const chunk = tag(bytes, 12);
+    if (chunk === 'VP8 ') return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+    if (chunk === 'VP8L') {
+      const bits = view.getUint32(21, true);
+      return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >>> 14) & 0x3fff) };
+    }
+    if (chunk === 'VP8X') {
+      const u24 = (at: number): number => bytes[at]! | (bytes[at + 1]! << 8) | (bytes[at + 2]! << 16);
+      return { width: 1 + u24(24), height: 1 + u24(27) };
+    }
+    return undefined;
+  }
+  let at = 2;
+  const jpeg = { frameEnd: 0, nonMarkerBytes: false, standaloneMarkers: false, fillBytes: false, shortSegments: false };
+  while (at + 4 <= bytes.length) {
+    if (bytes[at] !== 0xff) { jpeg.nonMarkerBytes = true; at += 1; continue; }
+    const marker = bytes[at + 1]!;
+    if (marker === 0xff) { jpeg.fillBytes = true; at += 1; continue; }
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { jpeg.standaloneMarkers = true; at += 2; continue; }
+    const length = view.getUint16(at + 2);
+    if (length < 2) jpeg.shortSegments = true;
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return at + 9 <= bytes.length ? { width: view.getUint16(at + 7), height: view.getUint16(at + 5), jpeg: { ...jpeg, frameEnd: at + 9 } } : undefined;
+    }
+    if (marker === 0xda) return undefined;
+    at += 2 + length;
+  }
+  return undefined;
+}
+
+/** An image's signature and dimensions, without deciding whether a vendor accepts that format or size. */
+export function readImageHeader(bytes: Uint8Array): (ImageHeader & { type: ImageType }) | undefined {
+  let type: ImageType;
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) type = 'image/png';
+  else if (tag(bytes, 0).startsWith('GIF')) type = 'image/gif';
+  else if (bytes[0] === 0xff && bytes[1] === 0xd8) type = 'image/jpeg';
+  else if (tag(bytes, 0) === 'RIFF' && tag(bytes, 8) === 'WEBP') type = 'image/webp';
+  else return undefined;
+  const dimensions = imageDimensions(bytes, type);
+  return dimensions ? { type, ...dimensions } : undefined;
+}
+
+/** ISO BMFF's bounded top-level boxes and movie headers, with raw duration and 16.16 track dimensions. */
+export function readMp4Header(bytes: Uint8Array): {
+  fileType: boolean;
+  hasMediaData: boolean;
+  movies: Array<{ headers: Array<{ timescale: number; duration: number; payloadSize: number }>; tracks: Dimensions[] }>;
+} {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  function* boxes(from: number, to: number): Generator<{ type: string; start: number; end: number }> {
+    let at = from;
+    while (at + 8 <= to) {
+      let size = view.getUint32(at);
+      const type = tag(bytes, at + 4);
+      let header = 8;
+      if (size === 1) {
+        if (at + 16 > to) return;
+        size = Number(view.getBigUint64(at + 8));
+        header = 16;
+      }
+      if (size === 0) size = to - at;
+      if (!Number.isSafeInteger(size) || size < header || size > to - at) return;
+      yield { type, start: at + header, end: at + size };
+      at += size;
+    }
+  }
+  const result: ReturnType<typeof readMp4Header> = { fileType: bytes.length >= 8 && tag(bytes, 4) === 'ftyp', hasMediaData: false, movies: [] };
+  for (const box of boxes(0, bytes.length)) {
+    if (box.type === 'mdat' && box.end > box.start) result.hasMediaData = true;
+    if (box.type !== 'moov') continue;
+    const movie: (typeof result.movies)[number] = { headers: [], tracks: [] };
+    result.movies.push(movie);
+    for (const child of boxes(box.start, box.end)) {
+      const { type, start, end } = child;
+      if (type === 'mvhd' && start < end) {
+        const version = bytes[start];
+        const payloadSize = end - start;
+        if (version === 0 && payloadSize >= 20) movie.headers.push({ timescale: view.getUint32(start + 12), duration: view.getUint32(start + 16), payloadSize });
+        if (version === 1 && payloadSize >= 32) movie.headers.push({ timescale: view.getUint32(start + 20), duration: Number(view.getBigUint64(start + 24)), payloadSize });
+      }
+      if (type !== 'trak') continue;
+      for (const track of boxes(start, end)) {
+        if (track.type !== 'tkhd' || track.start >= track.end) continue;
+        const version = bytes[track.start];
+        const at = version === 1 ? track.start + 88 : version === 0 ? track.start + 76 : track.end;
+        if (at + 8 > track.end) continue;
+        const width = view.getUint32(at) / 65536;
+        const height = view.getUint32(at + 4) / 65536;
+        movie.tracks.push({ width, height });
+      }
+    }
+  }
+  return result;
+}