@volter/twin-postmark 0.1.0

package/src/postmark-events.ts

@@ -0,0 +1,189 @@
+// Postmark WEBHOOK DELIVERY + the deterministic offline delivery plan.
+//
+// ⚠ FIDELITY NOTE — READ THIS BEFORE "ADDING SIGNATURES". Postmark webhooks are NOT signed.
+// There is no `svix-signature`, no HMAC, no shared secret anywhere in Postmark's webhook
+// design (this is a real difference from Resend/Clerk/Svix-backed vendors, and a twin that
+// invented a signature scheme would be teaching consumers to verify something the vendor
+// never sends). Postmark authenticates a webhook delivery the two ways its Webhooks API
+// actually models — both of which this module reproduces:
+//   · `HttpAuth: { Username, Password }` → an HTTP Basic `Authorization` header, and
+//   · `HttpHeaders: [{ Name, Value }]`   → arbitrary caller-chosen headers (the usual place
+//                                          a shared secret goes).
+// Both are stored on the webhook resource by the Webhooks API (POST /webhooks), so the
+// registry here is the twin's OWN projected state — not a parallel in-memory store.
+//
+// PAYLOAD. Each delivery is a plain JSON POST whose body carries a `RecordType` discriminator
+// — `Delivery` | `Open` | `Click` | `Bounce` | `SpamComplaint` | `SubscriptionChange` |
+// `Inbound` — matching the vendor's documented webhook payloads. A webhook only receives a
+// record type whose `Triggers.<Type>.Enabled` is true, and only for its own MessageStream.
+//
+// DELIVERY PLAN. A sent email progresses through a DETERMINISTIC, OFFLINE outcome the twin
+// drives — no SMTP, no network. `deliveryPlan()` is pure so the twin + its tests are
+// repeatable.
+import { projectResources } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+
+const SERVICE = 'postmark';
+
+/** Postmark's webhook `RecordType` discriminators (the outbound delivery-lifecycle family). */
+export const POSTMARK_RECORD_TYPES = ['Delivery', 'Open', 'Click', 'Bounce', 'SpamComplaint', 'SubscriptionChange'] as const;
+export type PostmarkRecordType = (typeof POSTMARK_RECORD_TYPES)[number];
+
+/** RecordType → the `Triggers` key on the webhook resource that gates it. */
+const TRIGGER_FOR: Record<PostmarkRecordType, string> = {
+  Delivery: 'Delivery', Open: 'Open', Click: 'Click',
+  Bounce: 'Bounce', SpamComplaint: 'SpamComplaint', SubscriptionChange: 'SubscriptionChange',
+};
+
+/** An injected webhook deliverer — a fake in tests, a real HTTP POST live. */
+export type PostmarkWebhookDelivery = (url: string, body: string, headers: Record<string, string>) => Promise<void> | void;
+
+/** What the twin needs to route a webhook: the root to read from + the injected deliverer. */
+export type WebhookContext = { root?: string; deliver?: PostmarkWebhookDelivery };
+
+function asObject(v: unknown): Record<string, unknown> {
+  return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+/**
+ * The webhooks registered on a stream whose trigger for `recordType` is enabled — read from
+ * the SAME projection the Webhooks API serves, so a webhook created through `POST /webhooks`
+ * is the one that fires (no parallel registry to drift).
+ */
+export function webhooksFor(stream: string, recordType: PostmarkRecordType, root?: string): Array<Record<string, unknown>> {
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === 'webhook' && (r as Record<string, unknown>).deleted !== true)
+    .filter((w) => w.MessageStream === stream)
+    .filter((w) => asObject(asObject(w.Triggers)[TRIGGER_FOR[recordType]]).Enabled === true);
+}
+
+/**
+ * The headers Postmark sends with a webhook delivery: JSON content type, the webhook's own
+ * custom `HttpHeaders`, and an HTTP Basic `Authorization` header when `HttpAuth` is set.
+ * Pure — exported so a verify() can assert the auth/header wiring without any I/O.
+ */
+export function webhookHeaders(webhook: Record<string, unknown>): Record<string, string> {
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  for (const raw of Array.isArray(webhook.HttpHeaders) ? webhook.HttpHeaders : []) {
+    const h = asObject(raw);
+    if (typeof h.Name === 'string' && h.Name !== '') headers[h.Name] = String(h.Value ?? '');
+  }
+  const auth = asObject(webhook.HttpAuth);
+  if (typeof auth.Username === 'string' && auth.Username !== '') {
+    headers.Authorization = `Basic ${Buffer.from(`${auth.Username}:${String(auth.Password ?? '')}`).toString('base64')}`;
+  }
+  return headers;
+}
+
+/** Fire-and-forget HTTP delivery — the live path, like the real vendor's. */
+const httpDelivery: PostmarkWebhookDelivery = async (url, body, headers) => {
+  if (worldEgressRefusal(url) !== null) return; // the World's egress rule: refused like an unreachable endpoint
+  try {
+    await fetch(url, { method: 'POST', headers, body });
+  } catch {
+    /* fire-and-forget, like the real vendor */
+  }
+};
+
+/**
+ * POST one Postmark webhook payload to every webhook on `stream` whose trigger for this
+ * `RecordType` is enabled. Returns what was delivered (for assertions); a no-op when no
+ * webhook subscribes. Offline whenever `ctx.deliver` is injected.
+ */
+export async function emitPostmarkWebhook(
+  stream: string,
+  recordType: PostmarkRecordType,
+  payload: Record<string, unknown>,
+  ctx: WebhookContext = {},
+): Promise<Array<{ url: string; body: string; headers: Record<string, string> }>> {
+  const targets = webhooksFor(stream, recordType, ctx.root);
+  if (targets.length === 0) return [];
+  const deliver = ctx.deliver ?? httpDelivery;
+  const body = JSON.stringify({ RecordType: recordType, ...payload });
+  const out: Array<{ url: string; body: string; headers: Record<string, string> }> = [];
+  for (const w of targets) {
+    const headers = webhookHeaders(w);
+    await deliver(String(w.Url), body, headers);
+    out.push({ url: String(w.Url), body, headers });
+  }
+  return out;
+}
+
+/**
+ * Deliver ONE arriving inbound message to the server's `InboundHookUrl`.
+ *
+ * This is a different door from `emitPostmarkWebhook` on purpose, because the vendor's is:
+ * Postmark's Webhooks API (`POST /webhooks`, `Triggers`) covers the OUTBOUND delivery
+ * lifecycle, while an inbound message is posted to the URL configured on the SERVER
+ * (`InboundHookUrl`, settable via `PUT /server`). The payload is the inbound message
+ * document itself — the same object `GET /messages/inbound/:id/details` serves, with NO
+ * `RecordType` discriminator, which is exactly what the vendor sends.
+ *
+ * AUTH. Postmark's inbound hook has no header configuration at all: the only credential it
+ * can carry is HTTP Basic userinfo embedded in the configured URL. That userinfo is split
+ * out into an `Authorization: Basic` header here rather than left on the URL, because that
+ * is both what the vendor puts on the wire and what `fetch` refuses to send otherwise.
+ */
+export async function emitPostmarkInboundHook(
+  message: Record<string, unknown>,
+  ctx: WebhookContext = {},
+): Promise<Array<{ url: string; body: string; headers: Record<string, string> }>> {
+  const server = projectResources(SERVICE, ctx.root).find((r) => r.type === 'server' && (r as Record<string, unknown>).deleted !== true);
+  const configured = typeof server?.InboundHookUrl === 'string' ? server.InboundHookUrl : '';
+  if (configured === '') return [];
+  let parsed: URL;
+  try {
+    parsed = new URL(configured);
+  } catch {
+    return [];
+  }
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (parsed.username !== '') {
+    headers.Authorization = `Basic ${Buffer.from(`${decodeURIComponent(parsed.username)}:${decodeURIComponent(parsed.password)}`).toString('base64')}`;
+    parsed.username = '';
+    parsed.password = '';
+  }
+  const url = parsed.toString();
+  const body = JSON.stringify(message);
+  await (ctx.deliver ?? httpDelivery)(url, body, headers);
+  return [{ url, body, headers }];
+}
+
+// ── deterministic offline delivery plan ─────────────────────────────────────────────
+export type PostmarkEventType = 'Delivered' | 'Opened' | 'LinkClicked' | 'Bounced' | 'SpamComplaint';
+
+/**
+ * The ordered `MessageEvents` the twin drives a sent message through, OFFLINE.
+ *
+ * The recipient prefixes below are a TWIN-LOCAL convention (Postmark's own bounce testing
+ * needs real mail flow, which a local twin has none of), deliberately documented rather than
+ * dressed up as vendor behavior — they are the seam that lets a test drive the bounce and
+ * spam-complaint paths deterministically:
+ *   · a recipient whose local part starts with `bounce`  → a HARD BOUNCE (no delivery);
+ *   · one starting with `spam` or `complaint`            → delivered, then a SPAM COMPLAINT;
+ *   · anything else                                      → delivered.
+ * Opens and clicks are emitted ONLY when the message asked for that tracking — `TrackOpens`
+ * and `TrackLinks` respectively — exactly as the vendor does, so a message sent with tracking
+ * off records neither.
+ *
+ * `status` is the outbound message's `Status`. It stays `Sent` for every submitted message:
+ * on real Postmark a bounce does NOT rewrite the message's Status, it surfaces through
+ * `MessageEvents` and the Bounce API. Modeled that way here on purpose.
+ */
+export function deliveryPlan(input: { recipient: string; trackOpens: boolean; trackLinks: string }): { events: PostmarkEventType[]; status: string } {
+  const local = String(input.recipient ?? '').split('@')[0]?.toLowerCase() ?? '';
+  if (local.startsWith('bounce')) return { events: ['Bounced'], status: 'Sent' };
+  if (local.startsWith('spam') || local.startsWith('complaint')) {
+    return { events: ['Delivered', 'SpamComplaint'], status: 'Sent' };
+  }
+  const events: PostmarkEventType[] = ['Delivered'];
+  if (input.trackOpens) events.push('Opened');
+  if (input.trackLinks && input.trackLinks !== 'None') events.push('LinkClicked');
+  return { events, status: 'Sent' };
+}
+
+/** The terminal event a message lands on, given its plan (the outbound activity headline). */
+export function terminalEvent(input: { recipient: string; trackOpens: boolean; trackLinks: string }): PostmarkEventType {
+  const { events } = deliveryPlan(input);
+  return events[events.length - 1]!;
+}

package/src/postmark-mirror-ui.ts

@@ -0,0 +1,213 @@
+// Postmark MIRROR UI — a Postmark-dashboard-like Activity view served as a React/TSX app
+// (Bun-bundled, the repo convention).
+//
+// TRANSPORT: archetype A, API PASSTHROUGH (ADDING_A_TWIN "Does this vendor get a mirror?").
+// Every non-asset request falls straight through to the pack's OWN FETCH ADAPTER, and the
+// browser client fetches POSTMARK'S OWN REAL API PATHS — `/messages/outbound`,
+// `/messages/outbound/:id/details`, `/bounces`, `/templates`, `/message-streams`,
+// `/webhooks`, `/message-streams/outbound/suppressions/dump`. There is exactly ONE code path
+// serving the screen and the API, so API↔UI parity cannot drift: it is not "kept in sync",
+// it is the same handler. (Resend needed a `/_twin/emails` side-read only because Resend has
+// no list-emails endpoint; Postmark's Messages API does, so no side projection exists here.)
+//
+// The pure render/format helpers below are framework-agnostic so they can be unit-tested AND
+// imported by the browser client — Bun tree-shakes the server-only exports out of the bundle.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// own fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createPostmarkTwinFetch } from './postmark-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/postmark-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/postmark-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (no `@volter/world-core`, no `Bun`, no handler).
+// ---------------------------------------------------------------------------
+
+export type PostmarkRow = Record<string, any>;
+
+/** The recipients of an outbound message, as a readable list. */
+export function recipientsOf(m: PostmarkRow): string {
+  if (Array.isArray(m?.Recipients)) return m.Recipients.map(String).join(', ');
+  if (Array.isArray(m?.To)) return m.To.map((r: PostmarkRow) => String(r?.Email ?? '')).filter(Boolean).join(', ');
+  if (typeof m?.To === 'string') return m.To;
+  return '';
+}
+
+/** A subject line for a message row, or a placeholder. */
+export function messageSubject(m: PostmarkRow): string {
+  return m?.Subject ? String(m.Subject) : '(no subject)';
+}
+
+/** The ordered `MessageEvents` types the twin recorded for a message. */
+export function deliveryTimeline(m: PostmarkRow): string[] {
+  const events = Array.isArray(m?.MessageEvents) ? m.MessageEvents : [];
+  return ['Sent', ...events.map((e: PostmarkRow) => String(e?.Type ?? ''))].filter(Boolean);
+}
+
+/**
+ * The headline delivery status of a message: its LAST recorded MessageEvent, falling back to
+ * the vendor's `Status` field. This is what the Activity list and the status pill show.
+ */
+export function messageStatus(m: PostmarkRow): string {
+  const timeline = deliveryTimeline(m);
+  const last = timeline[timeline.length - 1];
+  return last && last !== 'Sent' ? last : String(m?.Status ?? 'Sent');
+}
+
+/** The rendered preview of a message body — prefers HtmlBody, falls back to TextBody. */
+export function messagePreview(m: PostmarkRow): { kind: 'html' | 'text' | 'none'; value: string } {
+  if (m?.HtmlBody) return { kind: 'html', value: String(m.HtmlBody) };
+  if (m?.TextBody) return { kind: 'text', value: String(m.TextBody) };
+  return { kind: 'none', value: '' };
+}
+
+/** Format an ISO timestamp as a short date, or an em dash. */
+export function formatPostmarkDate(iso: unknown): string {
+  if (typeof iso !== 'string' || !iso) return '—';
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return '—';
+  try {
+    return new Date(t).toISOString().slice(0, 16).replace('T', ' ');
+  } catch {
+    return '—';
+  }
+}
+
+/**
+ * A status → CSS tone class for the status pill. The returned values are STATIC STRING
+ * LITERALS (never template-built) so they survive the bundler's minification and a UI
+ * verify can assert on the class the component actually emits.
+ */
+export function statusTone(value: string): string {
+  const v = String(value ?? '').toLowerCase();
+  if (['delivered', 'opened', 'linkclicked', 'sent', 'processed', 'verified', 'active', 'true'].includes(v)) return 'ok';
+  if (['queued', 'pending', 'scheduled', 'unconfirmed', 'false'].includes(v)) return 'warn';
+  if (['bounced', 'hardbounce', 'spamcomplaint', 'blocked', 'failed', 'suppressed', 'transient'].includes(v)) return 'bad';
+  return 'neutral';
+}
+
+/** Flatten a (possibly nested) value into label/value lines for the detail panel. */
+export type FlatLine = { key: string; value: string; depth: number };
+export function flattenPostmarkValue(value: unknown, prefix = '', depth = 0, out: FlatLine[] = []): FlatLine[] {
+  if (value === null || value === undefined) {
+    out.push({ key: prefix || '(value)', value: '—', depth });
+  } else if (Array.isArray(value)) {
+    if (value.length === 0) out.push({ key: prefix, value: '[]', depth });
+    else value.forEach((v, i) => flattenPostmarkValue(v, `${prefix}[${i}]`, depth, out));
+  } else if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      flattenPostmarkValue(v, prefix ? `${prefix}.${k}` : k, depth, out);
+    }
+  } else {
+    out.push({ key: prefix || '(value)', value: String(value), depth });
+  }
+  return out;
+}
+
+/** The nav sections the mirror renders, each bound to one REAL Postmark API path + its
+ *  collection key. Shared by the client (to fetch) and by tests (to assert the binding). */
+export type MirrorSection = { key: string; label: string; path: string; collection: string; idKey: string };
+export const POSTMARK_MIRROR_SECTIONS: MirrorSection[] = [
+  { key: 'messages', label: 'Activity', path: '/messages/outbound', collection: 'Messages', idKey: 'MessageID' },
+  { key: 'bounces', label: 'Bounces', path: '/bounces', collection: 'Bounces', idKey: 'ID' },
+  { key: 'templates', label: 'Templates', path: '/templates', collection: 'Templates', idKey: 'TemplateId' },
+  { key: 'streams', label: 'Streams', path: '/message-streams', collection: 'MessageStreams', idKey: 'ID' },
+  { key: 'webhooks', label: 'Webhooks', path: '/webhooks', collection: 'Webhooks', idKey: 'ID' },
+  { key: 'suppressions', label: 'Suppressions', path: '/message-streams/outbound/suppressions/dump', collection: 'Suppressions', idKey: 'EmailAddress' },
+];
+
+// ---------------------------------------------------------------------------
+// Server-only (Bun) below — NOT imported by the browser client.
+// ---------------------------------------------------------------------------
+
+const APP_SHELL = `<!doctype html><html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<base href="/"><title>Postmark twin — activity mirror</title>
+<link rel="stylesheet" href="assets/styles.css" /></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX mirror client to browser JS (Bun bundles TSX); memoized at module
+ *  scope so a pack on its own does exactly ONE `Bun.build`. */
+export function buildPostmarkMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/**
+ * The mirror's first-party credential, added to a request the adapter is about to serve.
+ *
+ * A pure REQUEST REWRITE — the mirror never calls the handler and never reaches around the wire;
+ * it only fills in the token header a browser cannot carry (Postmark authenticates every route
+ * with `X-Postmark-Server-Token`, or `X-Postmark-Account-Token` on its account-scoped families).
+ * The console is signed in to ITS root, so any non-empty token does — deliberately NOT the
+ * vendor's public test token, which is /email-only and changes the send reply text. Headers
+ * already present are left alone, so a caller that brings its own token keeps it.
+ */
+const MIRROR_TOKEN = 'postmark-twin-mirror-token';
+async function withMirrorCredentials(request: Request): Promise<Request> {
+  const headers = new Headers(request.headers);
+  if (!headers.has('x-postmark-server-token')) headers.set('x-postmark-server-token', MIRROR_TOKEN);
+  if (!headers.has('x-postmark-account-token')) headers.set('x-postmark-account-token', MIRROR_TOKEN);
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    ...(hasBody ? { body: await request.text() } : {}),
+  });
+}
+
+/** Serve the Postmark activity mirror (React app) over the twin's OWN REST API. */
+export async function createPostmarkMirrorServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const twin = createPostmarkTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildPostmarkMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // Everything else → the twin's OWN FETCH ADAPTER (composition, R2): the same closure
+      // `createPostmarkTwinServer` serves, so the mirror port and the API port cannot drift — the
+      // uniform `GET /twin` door, the world clock, `readOnly`, Postmark's token auth and the
+      // `connection: close` Bun-socket workaround all come from it rather than from a hand-rolled
+      // copy that has to be kept in step. The client fetches the vendor's real paths, so the
+      // mirror and an SDK consumer are served by literally the same code (archetype A).
+      return twin(await withMirrorCredentials(request));
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The mirror itself is the React client. */
+export function postmarkMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function postmarkMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/postmark-perform-harness.ts

@@ -0,0 +1,21 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushPostmarkAction, type PostmarkClient } from './postmark-connector.ts';
+
+export async function performPending(client: PostmarkClient, opts: { root?: string; occurredAt?: string } = {}): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const entry of deployableEntries('postmark', opts.root)) {
+    let externalId: string;
+    try {
+      ({ externalId } = await pushPostmarkAction(client, { operation: entry.operation ?? `${entry.subject.type}.update`, subject: entry.subject, fields: entry.fields ?? {} }));
+    } catch { continue; } // the twin's own record: nothing to write
+    confirmAction({
+      service: 'postmark', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(entry.id); externalIds[entry.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}

package/src/postmark-server.ts

@@ -0,0 +1,37 @@
+// Postmark twin HTTP server — serve the full Postmark API twin handler over HTTP so the real
+// `postmark` SDK (pointed at this base URL) works unmodified. JSON bodies pass through to the
+// handler. Writable by default; pass readOnly to reject writes (D3).
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES —
+// the manifest and the `connection: close` response header. The server is one line of Bun.serve
+// around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handlePostmarkTwinRequest } from './postmark-twin.ts';
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+
+/** Options every Postmark-twin HTTP surface needs, independent of who owns the socket. */
+export interface PostmarkTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+export function createPostmarkTwinFetch(options: PostmarkTwinFetchOptions): (request: Request) => Promise<Response> {
+  return createTwinFetchFromHandler(handlePostmarkTwinRequest, {
+    ...options,
+    manifest: statefulTwinManifest({ vendor: 'postmark', twinOf: 'the Postmark transactional-email API', stores: 'servers, sent messages and their opens/deliveries (the mirror shows the inbox)' }),
+    // The official SDK's Node transport reuses sockets. Bun 1.2 can reject a later request on
+    // that socket with its own HTTP 400 before fetch() runs; closing makes each modeled request
+    // reach the handler. (Inert under workerd, which owns its own connection handling.)
+    responseHeaders: { connection: 'close' },
+  });
+}
+
+export async function createPostmarkTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createPostmarkTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}