@volter/twin-gmail 0.0.0-stage → 1.0.1

package/spec/sources.json

@@ -0,0 +1,25 @@
+{
+  "https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes": {
+    "status": 200,
+    "checked": "2026-11-11",
+    "quotes": {
+      "gsmtp (Google SMTP) is added to all errors": true,
+      "The email account that you tried to reach does not exist.": true,
+      "Your message exceeded Google's message size limits.": true
+    }
+  },
+  "https://www.rfc-editor.org/rfc/rfc2047": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "encoded-word = \"=?\" charset \"?\" encoding \"?\" encoded-text \"?=\"": true
+    }
+  },
+  "https://www.rfc-editor.org/rfc/rfc5322": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Unfolding is accomplished by simply removing any CRLF that is immediately followed by WSP": true
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// world-gmail: serve the gmail twin (its webmail, and its receiving SMTP server on the side port the World allocates).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createGmailTwinServer } from './server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const smtpPort = Number(optionValue(rest, '--smtp-port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createGmailTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(smtpPort ? { smtpPort } : {}) });
+  process.stdout.write(`gmail twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  process.stdout.write(`gmail twin receiving mail on smtp://127.0.0.1:${s.smtpPort}\n`);
+  await keepProcessAlive();
+} else {
+  process.stdout.write('Usage: world-gmail serve [--port N] [--smtp-port N] [--root DIR] [--read-only]\n');
+}

package/src/engine/mail.ts

@@ -0,0 +1,76 @@
+// A message as RFC 5322 and MIME make of it (its headers, its text and HTML, its attachments), from the bytes Gmail's
+// receiving server accepted: pure, so the server's front keeps it in each recipient's mailbox (semantics/shared.ts
+// `deliver`). The data arrives with its dot-stuffing undone (../stream.ts); the World keeps the bytes as sent.
+type Part = { headers: Record<string, string>; body: string };
+type Attachment = { filename: string | null; contentType: string; size: number; contentId: string | null; base64: string };
+type Parsed = { headers: Record<string, string>; subject: string; from: string; to: string[]; cc: string[]; text: string | null; html: string | null; attachments: Attachment[] };
+
+/** Headers and body split at the first empty line; folded headers unfolded, names lowercased (RFC 5322 §2.2.3). */
+// source: https://www.rfc-editor.org/rfc/rfc5322 "Unfolding is accomplished by simply removing any CRLF that is immediately followed by WSP"
+function split(raw: string): Part {
+  const at = raw.search(/\r?\n\r?\n/);
+  const head = at < 0 ? raw : raw.slice(0, at);
+  const body = at < 0 ? '' : raw.slice(at).replace(/^\r?\n\r?\n/, '');
+  const headers: Record<string, string> = {};
+  for (const line of head.replace(/\r?\n[ \t]+/g, ' ').split(/\r?\n/)) {
+    const i = line.indexOf(':');
+    if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] ??= utf8(bytesOf(line.slice(i + 1).trim()));
+  }
+  return { headers, body };
+}
+
+const param = (value: string, name: string): string | undefined => {
+  const m = new RegExp(`;\\s*${name}\\*?=\\s*(?:"([^"]*)"|([^;\\s]+))`, 'i').exec(value);
+  const v = m?.[1] ?? m?.[2];
+  return v?.startsWith("utf-8''") || v?.startsWith("UTF-8''") ? decodeURIComponent(v.slice(7)) : v;
+};
+
+const bytesOf = (s: string): Uint8Array => Uint8Array.from(s, (c) => c.charCodeAt(0) & 0xff);
+const utf8 = (b: Uint8Array): string => new TextDecoder().decode(b);
+const textFor = (b: Uint8Array, charset: string | undefined): string => { try { return new TextDecoder(charset ?? 'utf-8').decode(b); } catch { return utf8(b); } };
+
+/** A part's body decoded by its Content-Transfer-Encoding: base64 and quoted-printable to bytes (RFC 2045 §6). */
+function decoded(part: Part): Uint8Array {
+  const enc = (part.headers['content-transfer-encoding'] ?? '7bit').toLowerCase();
+  if (enc === 'base64') { try { return bytesOf(atob(part.body.replace(/\s+/g, ''))); } catch { return bytesOf(part.body); } }
+  if (enc === 'quoted-printable') return bytesOf(part.body.replace(/=\r?\n/g, '').replace(/=([0-9A-Fa-f]{2})/g, (_, h: string) => String.fromCharCode(Number.parseInt(h, 16))).split('').map((c) => (c.charCodeAt(0) > 0xff ? '?' : c)).join(''));
+  return bytesOf(part.body);
+}
+
+/** Encoded words in a header (`=?UTF-8?B?…?=`, `=?UTF-8?Q?…?=`), decoded (RFC 2047). */
+// source: https://www.rfc-editor.org/rfc/rfc2047 "encoded-word = \"=?\" charset \"?\" encoding \"?\" encoded-text \"?=\""
+function words(value: string): string {
+  return value.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=(\s+(?==\?))?/g, (_, _cs: string, e: string, t: string) => {
+    try { return textFor(e.toUpperCase() === 'B' ? bytesOf(atob(t)) : bytesOf(t.replace(/_/g, ' ').replace(/=([0-9A-Fa-f]{2})/g, (_m, h: string) => String.fromCharCode(Number.parseInt(h, 16)))), _cs); } catch { return t; }
+  });
+}
+
+const addresses = (v: string | undefined): string[] => (v ? words(v).split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map((a) => (/<([^>]+)>/.exec(a)?.[1] ?? a).trim()).filter(Boolean) : []);
+
+/** The message's parts: a multipart's each (recursively), else the one. */
+function leaves(part: Part): Part[] {
+  const type = part.headers['content-type'] ?? 'text/plain';
+  const boundary = /^multipart\//i.test(type) ? param(type, 'boundary') : undefined;
+  if (!boundary) return [part];
+  const pieces = part.body.split(new RegExp(`\\r?\\n?--${boundary.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:--)?[ \\t]*\\r?\\n?`));
+  return pieces.slice(1, -1).filter((p) => p.trim()).flatMap((p) => leaves(split(p)));
+}
+
+export function parse(data: string): Parsed {
+  const top = split(data);
+  let text: string | null = null;
+  let html: string | null = null;
+  const attachments: Attachment[] = [];
+  for (const leaf of leaves(top)) {
+    const type = (leaf.headers['content-type'] ?? 'text/plain').split(';')[0]!.trim().toLowerCase();
+    const disposition = leaf.headers['content-disposition'] ?? '';
+    const filename = param(disposition, 'filename') ?? param(leaf.headers['content-type'] ?? '', 'name');
+    const bytes = decoded(leaf);
+    if (!/^attachment/i.test(disposition) && !filename && type === 'text/plain' && text === null) { text = textFor(bytes, param(leaf.headers['content-type'] ?? '', 'charset')); continue; }
+    if (!/^attachment/i.test(disposition) && !filename && type === 'text/html' && html === null) { html = textFor(bytes, param(leaf.headers['content-type'] ?? '', 'charset')); continue; }
+    let bin = '';
+    for (const b of bytes) bin += String.fromCharCode(b);
+    attachments.push({ filename: filename ? words(filename) : null, contentType: type, size: bytes.length, contentId: leaf.headers['content-id']?.replace(/^<|>$/g, '') ?? null, base64: btoa(bin) });
+  }
+  return { headers: top.headers, subject: words(top.headers.subject ?? ''), from: addresses(top.headers.from)[0] ?? '', to: addresses(top.headers.to), cc: addresses(top.headers.cc), text, html, attachments };
+}

package/src/fetch.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { around } from './semantics/around.ts';
+import { gmailSemantics } from './semantics/index.ts';
+import { screen as screen_home } from './screens/home.ts';
+import { screen as screen_mail } from './screens/mail.ts';
+
+export function createGmailFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as unknown as DerivedSurface,
+    handlers: gmailSemantics,
+    around,
+    screens: { "home": screen_home, "mail": screen_mail },
+  }, options);
+}

package/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"rfc5321.txt","format":"command-reply","version":"RFC 5321","anyCommand":[500,501,421],"commands":[{"id":"CONNECTION ESTABLISHMENT","intermediate":[],"success":[220],"error":[554]},{"id":"EHLO","intermediate":[],"success":[250],"error":[504,550,502]},{"id":"HELO","intermediate":[],"success":[250],"error":[504,550,502]},{"id":"MAIL","intermediate":[],"success":[250],"error":[552,451,452,550,553,503,455,555]},{"id":"RCPT","intermediate":[],"success":[250,251],"error":[550,551,552,553,450,451,452,503,455,555]},{"id":"DATA","intermediate":[354],"success":[],"error":[503,554],"then":{"intermediate":[],"success":[250],"error":[552,554,451,452,450,550]}},{"id":"RSET","intermediate":[],"success":[250],"error":[]},{"id":"VRFY","intermediate":[],"success":[250,251,252],"error":[550,551,553,502,504]},{"id":"EXPN","intermediate":[],"success":[250,252],"error":[550,500,502,504]},{"id":"HELP","intermediate":[],"success":[211,214],"error":[502,504]},{"id":"NOOP","intermediate":[],"success":[250],"error":[]},{"id":"QUIT","intermediate":[],"success":[221],"error":[]}]}

package/src/index.ts

@@ -0,0 +1,13 @@
+// @volter/twin-gmail — the gmail twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+
+export { createGmailFetch } from './fetch.ts';
+export { createGmailTwinServer } from './server.ts';
+export { createGmailTwinStream } from './stream.ts';
+export { manifest };
+
+export const pack = registerPack(packOf(manifest, surface as unknown as DerivedSurface));

package/src/manifest.ts

@@ -0,0 +1,86 @@
+// Gmail's manifest (ADR 0032 §4): the mail half of a Google account. A message sent to an address at gmail.com reaches
+// Gmail's receiving server (gmail.com's MX) over SMTP, which accepts it for an account Google holds and refuses it for
+// any other; the person reads it in Gmail's webmail at mail.google.com, signed in to Google.
+//
+// THE SURFACE is generated (./generated/surface.gen.json): RFC 5321's command-reply table, the receiving server's, served
+// on the pack's SMTP side port. The front (./semantics/around.ts) runs each command a connection's byte-stream door
+// (../stream.ts) hands it. The Gmail API, IMAP and submission are later cards (ADR 0032, Staging).
+//
+// THE STATE is each mailbox's messages (`message`: its mailbox, its envelope, its bytes and what they parse to). The
+// mailboxes are Google's accounts: googleoauth owns them and Google's sign-in, and this pack reads them through the
+// kernel's cross-pack read (`ownerReads`, architecture A3), never writes them: a person who signed up (`_person`, keyed
+// `person:<email>`, with the account's `sub`), the account (`account` <sub>) and the browser's Google session
+// (`_web_session`, keyed `websession:<the SID cookie>`).
+//
+// THE ADDRESSING is a static vendor fact: the descriptor's host rules name gmail.com, and its side port's scheme is
+// `smtp`, so the kernel's `ctx.mail` hands a gmail.com recipient's mail here (world-core smtp.ts, ADR 0032 §3).
+import type { DerivedManifest } from '@volter/world-core';
+import { states } from './semantics/states.ts';
+
+export const manifest: DerivedManifest = {
+  vendor: 'gmail',
+  service: 'gmail',
+  discovery: {
+    twinOf: "Gmail: its receiving SMTP server (gmail.com's MX) and its webmail at mail.google.com",
+    identity: "The SMTP side port takes mail from any sender, as an MX does, for gmail.com accounts Google holds. Webmail reads the person's Google session (googleoauth's SID cookie).",
+    stores: "each Google account's mailbox: the messages it received, with their envelope, bytes, headers, bodies and attachments",
+  },
+  body: { json: 'always' },
+  ids: { template: '{letters:16}' },
+  time: 'iso',
+  // the screens' and the wire's refusals; the wire answers in SMTP replies (./semantics/shared.ts)
+  error: { error: '{message}' },
+  readOnly: { status: 403, message: 'the twin is read-only' },
+  notFound: { status: 404, message: 'Not Found' },
+  list: { style: 'envelope', envelope: { messages: '{data}' }, limit: { param: 'limit', default: 50, max: 500 } },
+  deleted: {},
+  vendorBacked: { none: 'Mail reaches Gmail over SMTP from a sending twin inside the World; there is no derived HTTP perform or vendor resource refresh (the Gmail API is a later card).' },
+  unmodeled: ['EXPN', 'HELP'],
+  // who a message's records name (ADR 0036, "Replicating an issue"): its mailbox, the Google account it was kept for,
+  // and its envelope's addresses; the recipient as Gmail delivers it, where `local+tag@gmail.com` is the mailbox
+  // `local@gmail.com` labelled (shared.ts accountOf), so a pseudonymized pull keeps the tag on the mailbox's pseudonym (`email+`)
+  privacy: {
+    identifiers: {
+      message: { mailbox: 'email', 'envelope.to': 'email+', 'envelope.from': 'email', receivedAt: 'time' },
+    },
+  },
+  ownerReads: [
+    { owner: 'googleoauth', resource: '_person' },
+    { owner: 'googleoauth', resource: 'account' },
+    { owner: 'googleoauth', resource: '_web_session' },
+  ],
+  resources: {
+    Session: { storedAs: '_session', refresh: { none: 'Connection-local state, not a vendor resource.' }, idPrefix: 'session', ...states.Session },
+    message: { refresh: { none: 'The Gmail API, which would read a mailbox back, is a later card.' }, idPrefix: '', ids: '{letters:16}' },
+  },
+  screens: [{
+    // Gmail's webmail (screens/mail.ts): the signed-in person's inbox, a message with its links, and its attachments
+    id: 'mail', kind: 'workspace', host: 'mail.google.com', path: '/mail',
+    demand: "a person reads the mail an application sent them (Rallly's invitation with its invite.ics, Dub's links) and follows its link", status: 'done',
+    controls: ['Inbox', 'Download'], source: 'https://support.google.com/mail/answer/8494',
+  }, {
+    // gmail.com itself, which sends a visitor to the webmail
+    id: 'home', kind: 'flow', host: 'gmail.com', path: '/',
+    demand: 'a person who opens gmail.com reaches their inbox', status: 'done',
+    source: 'https://support.google.com/mail/answer/8494',
+  }],
+  descriptor: {
+    protocol: '3',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-gmail',
+    resources: ['message'],
+    specSource: "spec/rfc5321.txt (RFC 5321): the command-reply table of Gmail's receiving server (spec/SOURCE.md)",
+    description: "Gmail twin — gmail.com's receiving SMTP server, which keeps mail for the World's Google accounts and refuses other addresses, and the webmail at mail.google.com where the signed-in person reads it and downloads its attachments.",
+    adoption: { sdks: [], envStems: [] },
+    // gmail.com: the domain whose mail this server receives (the kernel's ctx.mail routes by it), and its site; the
+    // webmail's host
+    hosts: [{ host: 'mail.google.com' }, { host: 'gmail.com' }],
+    endpointEnvNone: 'no application reads Gmail by a base URL: mail reaches it from the World\'s senders (ctx.mail), and a person opens its webmail',
+    // a gmail.com address is a Google account, made at Google's own sign-up (googleoauth's accounts.google.com/signup,
+    // which leaves the person signed in): the door the World's generated seed calls for each declared person whose
+    // address this pack's mail domain is (ADR 0033 §3)
+    seed: { signUp: 'https://accounts.google.com/signup' },
+    sidePorts: [{ name: 'smtp', option: 'smtpPort', flag: '--smtp-port', scheme: 'smtp', note: "Gmail's receiving SMTP server (gmail-smtp-in.l.google.com), without TLS: mail for gmail.com's accounts, handed on by the World's senders through ctx.mail" }],
+  },
+};

package/src/screens/home.ts

@@ -0,0 +1,6 @@
+// gmail.com: the site sends its visitor to the webmail, which signs them in first when it must (./mail.ts).
+import type { HandlerContext } from '@volter/world-core';
+
+export async function screen(_ctx: HandlerContext): Promise<Response> {
+  return new Response(null, { status: 301, headers: { location: 'https://mail.google.com/mail/' } });
+}

package/src/screens/mail.ts

@@ -0,0 +1,128 @@
+// Gmail's webmail (mail.google.com/mail): the signed-in person's inbox, one message with its links, and its attachments,
+// under the person's Google session (googleoauth's SID cookie, read through the kernel's cross-pack read: ADR 0032 §2).
+// A browser with no Google session is sent to Google's sign-in, which returns it here.
+//
+//   GET /mail, /mail/u/0/                          the inbox, newest first
+//   GET /mail/u/0/inbox/<id>                       one message: its sender, recipients, subject and body, links followable
+//   GET /mail/u/0/inbox/<id>/attachments/<index>   one attachment's bytes, downloaded
+//
+// Where the documentation stops: Gmail draws its pages in the browser and names a message in the page's fragment
+// (`#inbox/<id>`); the twin renders each on the server at a path of its own, so a person (or a walk) opens and clicks it
+// as a page. A message's HTML is sanitized on the server by the kernel's HTML grammar and shown inline in the message
+// body, as Gmail shows it, its links opening a new tab; the body is the containing boundary of everything it draws.
+// Composing, replying, labels, search and the other folders are not built.
+import { html, type HandlerContext } from '@volter/world-core';
+import { MESSAGE, type Row, signedInAccount } from '../semantics/shared.ts';
+
+const esc = (v: unknown): string => String(v ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);
+
+type HtmlNode = Awaited<ReturnType<typeof html.parseFragment>>[number];
+type HtmlElement = Extract<HtmlNode, { type: 'element' }>;
+
+// What Gmail keeps of a received message (ADR 0032 §4): these elements go with their content; these are kept; any other
+// element is unwrapped, its children kept. Only these attributes stay, so no received class or id poses as the
+// webmail's own element.
+const DROPPED = new Set(['script', 'style', 'link', 'meta', 'base', 'title', 'head', 'iframe', 'frame', 'frameset', 'object', 'embed', 'applet', 'form', 'input', 'button', 'select', 'textarea', 'option', 'template', 'noscript', 'svg', 'math', 'video', 'audio', 'source', 'track', 'canvas']);
+const KEPT = new Set(['a', 'abbr', 'address', 'b', 'bdi', 'bdo', 'big', 'blockquote', 'br', 'caption', 'center', 'cite', 'code', 'col', 'colgroup', 'dd', 'del', 'dfn', 'div', 'dl', 'dt', 'em', 'font', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'ins', 'kbd', 'li', 'mark', 'ol', 'p', 'pre', 'q', 's', 'samp', 'small', 'span', 'strike', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'tt', 'u', 'ul', 'wbr']);
+const ATTRIBUTES = new Set(['href', 'src', 'alt', 'title', 'width', 'height', 'align', 'valign', 'colspan', 'rowspan', 'border', 'cellpadding', 'cellspacing', 'bgcolor', 'color', 'face', 'size', 'dir', 'lang', 'style']);
+
+/** A style attribute as Gmail keeps it (ADR 0032 §4): without a remote load, a script or positioning, for an ordinary
+ *  spelling. This is fidelity with Gmail, not the boundary: the message body contains whatever a style draws (BODY) and
+ *  the page's CSP refuses every load, so an escaped spelling this misses stays inside the body and loads nothing. */
+const style = (value: string): string => value.split(';').map((declaration) => declaration.trim()).filter((declaration) => {
+  if (!declaration) return false;
+  const lower = declaration.toLowerCase();
+  if (lower.includes('url(') || lower.includes('expression(') || lower.includes('@import')) return false;
+  const property = lower.slice(0, lower.indexOf(':') === -1 ? lower.length : lower.indexOf(':')).trim();
+  return property !== 'position' && property !== 'behavior' && property !== '-moz-binding';
+}).join('; ');
+
+// The message body is the containing boundary of what the message draws: paint containment makes it the containing
+// block of every positioned descendant, `position: fixed` included, and clips what they paint to it (CSS Containment
+// Level 2 §3.3, https://www.w3.org/TR/css-contain-2/#containment-paint); its own stacking context keeps the message's
+// z-index inside it.
+const BODY = 'contain:paint;overflow:hidden;isolation:isolate;position:relative';
+
+const scheme = (value: string): string => { try { return new URL(value).protocol; } catch { return ''; } };
+
+function keep(nodes: HtmlNode[]): HtmlNode[] {
+  const out: HtmlNode[] = [];
+  for (const node of nodes) {
+    if (node.type === 'text') { out.push(node); continue; }
+    if (DROPPED.has(node.name)) continue;
+    const children = keep(node.children);
+    if (!KEPT.has(node.name)) { out.push(...children); continue; }
+    const attributes: HtmlElement['attributes'] = [];
+    for (const { name, value, namespace } of node.attributes) {
+      // a namespaced attribute (xlink:href, xml:lang) is no attribute the message's HTML keeps
+      if (namespace || !ATTRIBUTES.has(name)) continue;
+      if (name === 'href' && !['http:', 'https:', 'mailto:'].includes(scheme(value))) continue;
+      if (name === 'src' && !(node.name === 'img' && scheme(value) === 'data:')) continue;
+      if (name === 'style') { const kept = style(value); if (kept) attributes.push({ name, value: kept }); continue; }
+      attributes.push({ name, value });
+    }
+    if (node.name === 'a') attributes.push({ name: 'target', value: '_blank' }, { name: 'rel', value: 'noreferrer noopener' });
+    out.push({ type: 'element', name: node.name, namespace: node.namespace, attributes, children });
+  }
+  return out;
+}
+
+/** A received message's HTML as Gmail shows it (ADR 0032 §4): sanitized on the server and shown inline in its body. */
+async function sanitized(source: string): Promise<string> {
+  return html.serialize(keep(await html.parseFragment(source)));
+}
+
+/** A plain-text body with its addresses followable, as Gmail links them. */
+const linked = (text: string): string => esc(text).replace(/https?:\/\/[^\s<>"']+/g, (url) => `<a href="${url}" target="_blank" rel="noreferrer">${url}</a>`);
+
+const when = (iso: unknown): string => {
+  const d = new Date(String(iso));
+  return Number.isNaN(d.getTime()) ? '' : d.toLocaleString('en-US', { month: 'short', day: 'numeric', year: 'numeric', hour: 'numeric', minute: '2-digit', timeZone: 'UTC' });
+};
+
+// the inbox is Gmail's, at its own host, however the request reached the twin: a person's browser reaches it there
+// through the World's DNS, so the links it writes carry that host (ADR 0036 §9)
+const MAIL = 'https://mail.google.com';
+
+function page(title: string, email: string, body: string, status = 200): Response {
+  return new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title><style>body{margin:0;font:14px/1.45 Roboto,Arial,sans-serif;background:#f6f8fc;color:#1f1f1f}header{display:flex;justify-content:space-between;align-items:center;padding:12px 20px}header .brand{font-size:22px;color:#444746}header .who{color:#444746}nav{position:absolute;width:220px;padding:8px 12px}nav a{display:block;padding:6px 16px;border-radius:16px;background:#d3e3fd;color:#001d35;font-weight:600;text-decoration:none}main{margin-left:244px;margin-right:16px;background:#fff;border-radius:16px;min-height:70vh;padding:8px 0}.row{display:grid;grid-template-columns:200px 1fr 120px;gap:12px;padding:10px 20px;border-bottom:1px solid #f1f3f4;color:inherit;text-decoration:none}.row.unread{font-weight:700}.row .date{text-align:right;color:#5e5e5e}.msg{padding:12px 24px}.msg h2.hP{font-size:22px;font-weight:400;margin:8px 0 16px}.meta{color:#5e5e5e;margin-bottom:16px}.body{border-top:1px solid #f1f3f4;padding-top:16px;overflow-wrap:anywhere;${BODY}}.body pre{white-space:pre-wrap;font:inherit}.files{margin-top:24px;display:flex;gap:12px;flex-wrap:wrap}.files a{border:1px solid #dadce0;border-radius:8px;padding:10px 14px;color:#1f1f1f;text-decoration:none}.empty{padding:24px}</style></head><body><header><span class="brand">Gmail</span><span class="who">${esc(email)}</span></header><nav><a href="${MAIL}/mail/u/0/" aria-current="page">Inbox</a></nav><main>${body}</main></body></html>`, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; script-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'" } });
+}
+
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  if (!['GET', 'HEAD'].includes(request.method)) return new Response('Method Not Allowed', { status: 405, headers: { allow: 'GET, HEAD' } });
+  const url = new URL(request.url);
+  const who = signedInAccount(ctx);
+  if (!who) {
+    // to Google's sign-in, which returns the person to the page they asked for
+    const back = `${MAIL}${url.pathname}${url.search}`;
+    return new Response(null, { status: 302, headers: { location: `https://accounts.google.com/ServiceLogin?${new URLSearchParams({ service: 'mail', continue: back })}` } });
+  }
+  const mine = ctx.rowsRaw(MESSAGE).filter((m) => m.mailbox === who && m.deleted !== true)
+    .sort((a, b) => String(b.receivedAt).localeCompare(String(a.receivedAt)) || String(b.id).localeCompare(String(a.id)));
+  const path = url.pathname.replace(/\/+$/, '');
+  const opened = /^\/mail\/u\/0\/inbox\/([^/]+)(?:\/attachments\/(\d+))?$/.exec(path);
+  if (!opened) {
+    if (path !== '/mail' && path !== '/mail/u/0') return page('Gmail', who, '<p class="empty" role="alert">Temporary Error (404)</p>', 404);
+    const rows = mine.map((m) => `<a class="row${(m.labelIds as string[] | undefined)?.includes('UNREAD') ? ' unread' : ''}" href="${MAIL}/mail/u/0/inbox/${encodeURIComponent(String(m.id))}"><span class="from">${esc(m.from || (m.envelope as Row | undefined)?.from)}</span><span class="subject">${esc(m.subject || '(no subject)')}</span><span class="date">${esc(when(m.receivedAt))}</span></a>`).join('');
+    return page(`Inbox - ${who} - Gmail`, who, rows || '<p class="empty">Your Primary tab is empty.</p>');
+  }
+  let id = '';
+  try { id = decodeURIComponent(opened[1]!); } catch { /* no such message */ }
+  const m = mine.find((x) => x.id === id);
+  if (!m) return page('Gmail', who, '<p class="empty" role="alert">That message could not be found.</p>', 404);
+  const files = (m.attachments as Row[] | undefined) ?? [];
+  if (opened[2] !== undefined) {
+    const index = Number(opened[2]);
+    const key = (m._attachments as string[] | undefined)?.[index];
+    const meta = files[index];
+    const bytes = key === undefined ? undefined : await ctx.blobs.get(key);
+    if (!meta || !bytes) return page('Gmail', who, '<p class="empty" role="alert">That attachment could not be found.</p>', 404);
+    const name = String(meta.filename ?? `attachment-${index}`).replace(/["\r\n\\]/g, '');
+    return new Response(new Uint8Array(bytes), { headers: { 'content-type': String(meta.contentType ?? 'application/octet-stream'), 'content-disposition': `attachment; filename="${name}"` } });
+  }
+  const body = typeof m.html === 'string' && m.html ? await sanitized(m.html) : `<pre>${linked(String(m.text ?? ''))}</pre>`;
+  const list = files.map((f, i) => `<a href="${MAIL}/mail/u/0/inbox/${encodeURIComponent(String(m.id))}/attachments/${i}" download="${esc(f.filename ?? '')}">${esc(f.filename ?? `attachment ${i + 1}`)} <small>Download</small></a>`).join('');
+  return page(`${String(m.subject ?? '(no subject)')} - ${who} - Gmail`, who,
+    `<article class="msg"><h2 class="hP">${esc(m.subject || '(no subject)')}</h2><div class="meta"><strong>${esc(m.from)}</strong> to ${esc(((m.to as string[] | undefined) ?? []).join(', ') || who)} · ${esc(when(m.receivedAt))}</div><div class="body a3s">${body}</div>${list ? `<div class="files" aria-label="Attachments">${list}</div>` : ''}</article>`);
+}

package/src/semantics/around.ts

@@ -0,0 +1,91 @@
+// GMAIL'S RECEIVING SERVER'S FRONT: each command a connection sends, run as RFC 5321 orders it and Gmail's MX answers
+// it. The byte-stream door (../stream.ts) frames a connection's bytes and posts each command (or a message's whole data)
+// here with the session it carries; the answer is the reply lines, the moved session, and what the stream reads next.
+// Every other request is the webmail's (the screens).
+//
+// The server takes mail from any sender, as an MX does, and refuses a recipient it does not hold: an address at another
+// domain (it relays for no one) or a gmail.com address that is no Google account (550 5.1.1). It asks no authentication
+// and has no certificate here, so it advertises neither AUTH nor STARTTLS (ADR 0032 §4).
+import { smtpServer, type HandlerContext } from '@volter/world-core';
+import {
+  accountOf, BRIDGE, BYE, deliver, GO_AHEAD, GREETING, HOST, MAIL_DOMAIN, MAX_SIZE, NO_ACCOUNT, NO_TLS, NOT_OURS, OK, OK_MAIL, OK_RCPT,
+  type Session, SYNTAX, TOO_BIG, UNRECOGNIZED, unsupported, type WireAnswer,
+} from './shared.ts';
+
+const { smtpCleared, smtpCommand, smtpDomain: domainOf, smtpEhlo, smtpFront, smtpMailFrom, smtpOrder, smtpRcptTo } = smtpServer;
+
+const cmd = (session: Session, ...replies: string[]): WireAnswer => ({ replies, session, mode: 'command' });
+
+/** The machine's word on a command from where the session stands: a refusal's reply, or undefined to go on. */
+const order = (ctx: HandlerContext, s: Session, op: string, to?: string): string | undefined => smtpOrder(ctx, 'Session', s.stage, op, to);
+
+/** A transaction's state cleared, the greeting kept (RSET, a new EHLO, the end of DATA). */
+const cleared = (s: Session, stage: string): Session => smtpCleared(s, stage, {});
+
+function command(ctx: HandlerContext, s: Session, line: string): WireAnswer {
+  const { verb, arg } = smtpCommand(line);
+  switch (verb) { default: return cmd(s, UNRECOGNIZED);
+    case 'EHLO': case 'HELO': {
+      if (!arg.trim()) return cmd(s, `501 5.5.4 Empty ${verb} argument not allowed, closing connection. - gsmtp`);
+      order(ctx, s, verb, verb.toLowerCase());
+      const next = cleared(s, verb.toLowerCase());
+      if (verb === 'HELO') return cmd(next, `250 ${HOST} at your service`);
+      return { replies: smtpEhlo([`${HOST} at your service`, `SIZE ${MAX_SIZE}`, '8BITMIME', 'ENHANCEDSTATUSCODES', 'PIPELINING', 'SMTPUTF8']), session: next, mode: 'command' };
+    }
+    // source: spec:4.1.1.2 "This command clears the reverse-path buffer, the forward-path buffer, and the mail data buffer"
+    case 'MAIL': {
+      const refused = order(ctx, s, 'MAIL', 'mail');
+      if (refused) return cmd(s, refused);
+      const mail = smtpMailFrom(arg);
+      if ('refused' in mail) return cmd(s, 'parameter' in mail ? unsupported(mail.parameter) : SYNTAX);
+      if (mail.size !== undefined && mail.size > MAX_SIZE) return cmd(s, TOO_BIG);
+      return cmd({ ...s, stage: 'mail', from: mail.from.toLowerCase(), rcpt: [], ...(mail.smtputf8 ? { smtputf8: true } : {}) }, OK_MAIL);
+    }
+    // source: spec:4.1.1.3 "This command is used to identify an individual recipient of the mail data; multiple recipients are specified by multiple uses of this command."
+    case 'RCPT': {
+      const refused = order(ctx, s, 'RCPT', 'rcpt');
+      if (refused) return cmd(s, refused);
+      const rcpt = smtpRcptTo(arg);
+      if ('refused' in rcpt) return cmd(s, 'parameter' in rcpt ? unsupported(rcpt.parameter) : SYNTAX);
+      const to = rcpt.to.toLowerCase();
+      if (domainOf(to) !== MAIL_DOMAIN) return cmd(s, NOT_OURS);
+      if (!accountOf(ctx, to)) return cmd(s, NO_ACCOUNT);
+      return cmd({ ...s, stage: 'rcpt', rcpt: [...s.rcpt, to] }, OK_RCPT);
+    }
+    // source: spec:4.1.1.4 "The receiver normally sends a 354 response to DATA"
+    case 'DATA': {
+      const refused = order(ctx, s, 'DATA', 'data');
+      if (refused) return cmd(s, refused);
+      return { replies: [GO_AHEAD], session: { ...s, stage: 'data' }, mode: 'data' };
+    }
+    // source: spec:4.1.1.5 "This command specifies that the current mail transaction will be aborted."
+    case 'RSET': {
+      const back = s.greeted ?? 'fresh';
+      if (s.stage === 'mail' || s.stage === 'rcpt') order(ctx, s, 'RSET', back);
+      return cmd(cleared(s, s.stage === 'mail' || s.stage === 'rcpt' ? back : s.stage), OK);
+    }
+    // source: spec:4.1.1.9 "This command does not affect any parameters or previously entered commands."
+    case 'NOOP': return cmd(s, OK);
+    // source: spec:4.1.1.10 "The QUIT command may be issued at any time."
+    case 'QUIT': order(ctx, s, 'QUIT', 'closed'); return { replies: [BYE], session: { ...s, stage: 'closed' }, mode: 'command', close: true };
+    case 'STARTTLS': return cmd(s, NO_TLS);
+  }
+}
+
+/** The end of a message's data: its size held against the limit, the message kept in each recipient's mailbox. */
+async function endOfData(ctx: HandlerContext, s: Session, data: string): Promise<WireAnswer> {
+  const back = s.greeted ?? 'ehlo';
+  order(ctx, s, 'DATA', back);
+  const next = cleared(s, back);
+  if (data.length > MAX_SIZE) return cmd(next, TOO_BIG);
+  await deliver(ctx, { from: s.from ?? '', to: s.rcpt, data, smtputf8: s.smtputf8 === true });
+  return cmd(next, OK);
+}
+
+export async function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response> {
+  return smtpFront(ctx, next, BRIDGE, {
+    open: () => ({ replies: [GREETING], session: BRIDGE.fresh(), mode: 'command' }),
+    command: (s, line) => command(ctx, s, line),
+    data: (s, data) => endOfData(ctx, s, data),
+  });
+}

package/src/semantics/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by twin-standard create --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+
+export const gmailSemantics: Record<string, Handler> = {
+};

package/src/semantics/shared.ts

@@ -0,0 +1,111 @@
+// What Gmail's receiving server, its byte-stream door and its webmail share: the server's replies, a session's shape, the
+// key the stream proves itself with, the mailboxes (Google's accounts, read from googleoauth: architecture A3) and the
+// delivery of a message into them.
+import { browserSessionToken, privateTransportKey, type HandlerContext, type smtpServer } from '@volter/world-core';
+import { parse } from '../engine/mail.ts';
+
+export type Row = Record<string, unknown>;
+
+export const MESSAGE = 'message';
+
+/** The domain whose accounts this server receives mail for: the descriptor's host rule names it, so the kernel's
+ *  ctx.mail hands its mail here. */
+export const MAIL_DOMAIN = 'gmail.com';
+
+/** A session as its connection carries it between commands. */
+export type Session = { stage: string; from?: string; rcpt: string[]; smtputf8?: boolean; greeted?: 'helo' | 'ehlo' };
+
+/** What the front answers the stream: the reply lines, the session, and whether the stream reads a message next. */
+export type WireAnswer = smtpServer.SmtpAnswer<Session>;
+
+// Gmail's receiving server's replies. Google publishes its refusals in "Gmail SMTP errors and codes", each ending
+// `gsmtp`; where the documentation stops: the page lists no successes and no refusal of a recipient at a domain Google
+// does not receive for, so those replies' words are unverified (each is said so below), and the queue ids Gmail adds
+// are left out.
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "gsmtp (Google SMTP) is added to all errors"
+export const HOST = 'mx.google.com';
+export const GREETING = `220 ${HOST} ESMTP - gsmtp`;
+// the largest message the server takes, as its EHLO advertises SIZE (recalled, as above)
+export const MAX_SIZE = 157_286_400;
+export const OK_MAIL = '250 2.1.0 OK - gsmtp';
+export const OK_RCPT = '250 2.1.5 OK - gsmtp';
+export const OK = '250 2.0.0 OK - gsmtp';
+export const GO_AHEAD = '354 Go ahead - gsmtp';
+export const BYE = '221 2.0.0 closing connection - gsmtp';
+export const UNRECOGNIZED = '502 5.5.1 Unrecognized command. - gsmtp';
+// an address at gmail.com that is no account
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "The email account that you tried to reach does not exist."
+export const NO_ACCOUNT = '550 5.1.1 The email account that you tried to reach does not exist. - gsmtp';
+// an address at a domain this server does not receive for: an MX relays for no one. Unverified: Google's error page has
+// no row for it, no published transcript of mx.google.com's reply to it was found, and a session to its MX from a
+// residential connection could not be made (port 25 closed); no wording is claimed for it, the words below only stand in
+export const NOT_OURS = '550 5.7.1 Relaying denied. - gsmtp';
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "Your message exceeded Google's message size limits."
+export const TOO_BIG = '552 5.3.4 Your message exceeded Google\'s message size limits. - gsmtp';
+// no certificate on the World's side port (ADR 0032 §4: IMAP and submission, which need TLS, are later cards)
+export const NO_TLS = '454 4.7.0 TLS not available - gsmtp';
+// source: spec:4.1.1.11 "command, it will return code 555."
+export const unsupported = (arg: string): string => `555 5.5.4 Unsupported option: ${arg} - gsmtp`;
+export const SYNTAX = '501 5.5.2 Syntax error. - gsmtp';
+// The host cannot persist a message: a temporary failure, as RFC 5321 names it.
+// source: spec:4.2.3 "451 Requested action aborted: local error in processing"
+const queueFailure = (session: Session): WireAnswer => ({ replies: ['451 4.3.0 Local error in processing - gsmtp'], session, mode: 'command', close: true });
+
+/** The bridge between a connection and the server's front (world-core's SMTP server machine): the header the stream
+ *  signs its requests with, a key made once per process so a request from outside it (the webmail's port) cannot speak
+ *  for a connection, a fresh session, and the server's local-error reply. */
+export const BRIDGE: smtpServer.SmtpBridge<Session> = { header: 'x-volter-gmail-wire', key: () => privateTransportKey('gmail'), fresh: () => ({ stage: 'fresh', rcpt: [] }), failure: queueFailure };
+
+
+type Reader = Pick<HandlerContext, 'ownerRow'>;
+
+/** The mailbox an address names: the address of the Google account whose sign-up recorded its person (googleoauth's
+ *  `_person`, keyed `person:<email>`, with the account's `sub`, whose `account` stands); a `+tag` reaches the same
+ *  mailbox, as Gmail delivers it. Where the
+ *  documentation stops: Gmail also ignores dots in the local part; the twin matches the address as signed up. */
+export function accountOf(ctx: Reader, address: string): string | undefined {
+  const lower = address.toLowerCase();
+  const plain = lower.replace(/\+[^@]*@/, '@');
+  for (const email of lower === plain ? [lower] : [lower, plain]) {
+    const person = ctx.ownerRow('googleoauth', '_person', `person:${email}`);
+    const sub = typeof person?.sub === 'string' && person.deleted !== true ? person.sub : undefined;
+    const account = sub ? ctx.ownerRow('googleoauth', 'account', sub) : undefined;
+    if (sub && account && account.deleted !== true) return email;
+  }
+  return undefined;
+}
+
+/** A message accepted: kept once in each recipient's mailbox, with its envelope, its bytes and what they parse to. */
+export async function deliver(ctx: HandlerContext, e: { from: string; to: string[]; data: string; smtputf8: boolean }): Promise<void> {
+  const p = parse(e.data);
+  for (const rcpt of e.to) {
+    const mailbox = accountOf(ctx, rcpt);
+    if (!mailbox) continue;
+    const id = ctx.mint(MESSAGE);
+    const rawKey = `${id}/raw`;
+    await ctx.blobs.put(rawKey, Uint8Array.from(e.data, (c) => c.charCodeAt(0) & 0xff));
+    const attachmentKeys: string[] = [];
+    for (let i = 0; i < p.attachments.length; i++) {
+      const key = `${id}/attachments/${i}`;
+      await ctx.blobs.put(key, Uint8Array.from(atob(p.attachments[i]!.base64), (c) => c.charCodeAt(0)));
+      attachmentKeys.push(key);
+    }
+    await ctx.write(MESSAGE, id, {
+      id, mailbox, envelope: { from: e.from, to: rcpt, smtputf8: e.smtputf8 }, size: e.data.length, receivedAt: ctx.occurredAt,
+      headers: p.headers, subject: p.subject, from: p.from, to: p.to, cc: p.cc, text: p.text, html: p.html,
+      attachments: p.attachments.map(({ base64: _b, ...a }) => a), labelIds: ['INBOX', 'UNREAD'], _raw: rawKey, _attachments: attachmentKeys,
+    }, 'message.deliver');
+  }
+}
+
+/** The SID cookie Google's sign-in sets on .google.com (googleoauth's contract). */
+const SESSION_COOKIE = 'SID';
+/** The mailbox of the Google account a request's browser is signed in to: its `SID` cookie names a session googleoauth
+ *  recorded (`_web_session`, keyed `websession:<token>`), whose person is the account's. */
+export function signedInAccount(ctx: HandlerContext): string | undefined {
+  const token = browserSessionToken(ctx.call.request, SESSION_COOKIE);
+  if (!token) return undefined;
+  const session = ctx.ownerRow('googleoauth', '_web_session', `websession:${token}`);
+  if (!session || session.token !== token || typeof session.email !== 'string') return undefined;
+  return accountOf(ctx, session.email);
+}