@volter/world-core 3.0.164 → 3.0.165

package/dist/src/head.d.ts

@@ -19,6 +19,12 @@ export type PushOutcome = {
         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). */
@@ -140,6 +146,11 @@ export type DeployReport = {
         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 */
@@ -149,7 +160,7 @@ export type DeployReport = {
 };
 /** 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 declare function settlingEntries(service: string, root?: string): {
     offered: TwinAction[];
@@ -196,6 +207,10 @@ export declare function deferPerform<T>(request: string, fn: () => Promise<T>):
 export declare function performRequestGroup(service: string, request: string, root?: string): Promise<{
     ids: Map<string, string>;
     response?: RemoteExecuteResponse;
+    refused?: Array<{
+        actionId: string;
+        reason: string;
+    }>;
 } | RefusedWriteError | VendorWriteError>;
 /** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
  *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor

package/dist/src/head.js

@@ -262,11 +262,12 @@ function receiptsByEntry(parent) {
 /** 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) {
-    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, root) {
     const parent = parentEntries(service, root);
@@ -435,7 +436,14 @@ async function performNow(opts) {
             const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? outcome.data : {};
             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);
@@ -443,6 +451,10 @@ async function performNow(opts) {
                 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
@@ -545,24 +557,57 @@ export async function performRequestGroup(service, request, 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, request, refused, root) {
+    const pushed = (e) => e.input?.git !== undefined && e.input.git !== null;
+    const undo = new Set();
+    if (refused.some(pushed)) {
+        const made = branchEntries(service, root).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
  *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor

package/dist/src/html.d.ts

@@ -0,0 +1,29 @@
+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 declare class HtmlError extends Error {
+    readonly code: 'parser-unavailable';
+    constructor(code: '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 declare function parseFragment(source: string): Promise<HtmlNode[]>;
+/** Nodes serialized by the WHATWG HTML fragment serialization: its escaping, its void elements, its foreign names. */
+export declare function serialize(nodes: HtmlNode[]): Promise<string>;

package/dist/src/html.js

@@ -0,0 +1,64 @@
+export class HtmlError extends Error {
+    code;
+    constructor(code) {
+        super('HTML parser parse5 7.3.0 is unavailable');
+        this.code = code;
+        this.name = 'HtmlError';
+    }
+}
+let grammar;
+function loadGrammar() {
+    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) {
+    const { parseFragment: parse, defaultTreeAdapter: tree, html } = await loadGrammar();
+    const convert = (nodes) => {
+        const out = [];
+        for (const node of nodes) {
+            if (node.nodeName === '#text')
+                out.push({ type: 'text', value: node.value });
+            else if ('tagName' in node) {
+                const element = node;
+                // 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.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) {
+    const { serialize: write, defaultTreeAdapter: tree, html } = await loadGrammar();
+    const append = (parent, list) => {
+        for (const node of list) {
+            if (node.type === 'text') {
+                tree.insertText(parent, node.value);
+                continue;
+            }
+            const element = tree.createElement(node.name, node.namespace, 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, content);
+                append(content, node.children);
+            }
+            else
+                append(element, node.children);
+        }
+    };
+    const fragment = tree.createDocumentFragment();
+    append(fragment, nodes);
+    return write(fragment);
+}

package/dist/src/index.d.ts

@@ -56,9 +56,10 @@ export type { TwinResource } from './serve.js';
 export { passwordHash, personOf, personWith, recordPerson, shownPersonFields, type Person } from './people.js';
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
-export type { Mail, SmtpRoute } from './smtp.js';
+export type { Mail, MailReply } from './smtp.js';
 export * as s3 from './s3/wire.js';
 export * as xml from './xml.js';
+export * as html from './html.js';
 export * as clickhouse from './clickhouse/index.js';
 export { sampleFromSchema } from './schema-sample.js';
 export * as openaiWire from './openai-wire.js';
@@ -70,6 +71,7 @@ export { placeholderPng } from './placeholder-image.js';
 export { imageDimensions, readImageHeader, readMp4Header } from './media-header.js';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.js';
 export * as redis from './redis/index.js';
+export * as smtpServer from './smtp-server.js';
 export * as mysql from './mysql/index.js';
 export * as live from './live/index.js';
 export * as mongodb from './mongodb/index.js';

package/dist/src/index.js

@@ -51,6 +51,8 @@ export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from "./manag
 export * as s3 from "./s3/wire.js";
 // Generic strict XML grammar; vendor interpretation remains in its consumer.
 export * as xml from "./xml.js";
+// Generic WHATWG HTML grammar; what a pack keeps of received HTML remains the pack's policy.
+export * as html from "./html.js";
 export * as clickhouse from "./clickhouse/index.js";
 export { sampleFromSchema } from "./schema-sample.js";
 export * as openaiWire from "./openai-wire.js";
@@ -62,6 +64,7 @@ export { placeholderPng } from "./placeholder-image.js";
 export { imageDimensions, readImageHeader, readMp4Header } from "./media-header.js";
 export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
+export * as smtpServer from "./smtp-server.js";
 export * as mysql from "./mysql/index.js";
 export * as live from "./live/index.js";
 export * as mongodb from "./mongodb/index.js";

package/dist/src/pack-fetch.js

@@ -19,7 +19,9 @@ import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from "./
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
 import { getActiveWorldStore } from "./world-store.js";
 import { runWithCorrelationId } from "./actions.js";
-import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from "./head.js";
+import { deferPerform, deployableEntries, performRequestGroup, RefusedWriteError, VendorWriteError } from "./head.js";
+import { FLUSH, ZERO_SHA, pktLine, readPktLines } from "./git/smart-http.js";
+import { concat } from "./git/objects.js";
 import { withCors } from "./cors.js";
 import { contentAddressOf } from "./content-route.js";
 import { getPack } from "./packRegistry.js";
@@ -27,7 +29,7 @@ import { hostRules } from '../host-routing.cjs';
 import { expireSocketWaits, socketUpgrade } from "./sockets.js";
 import { liveIngest } from "./live/ingest.js";
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from "./resource-blob.js";
-import { resourcesOfType } from "./derived-core.js";
+import { gitRepositoryOf, resourcesOfType } from "./derived-core.js";
 import { worldNow } from "./world-clock.js";
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
@@ -635,7 +637,44 @@ export function createPackFetch(parts, options = {}) {
         const { value: answer, appended } = await runWithCorrelationId(id, () => deferPerform(id, () => fetch(request)));
         if (!appended)
             return answer;
+        // a receive-pack's pushes (derived-core.ts pushedInput): what the World's refs held before and after each
+        const pushes = m.git ? deployableEntries(m.service, options.root).filter((e) => e.correlationId === id && e.input?.git).map((e) => ({ actionId: e.id, ...e.input.git })) : [];
         const performed = await runWithCorrelationId(id, () => performRequestGroup(m.service, id, options.root));
+        // under `auto`, what the root did is what the World keeps (ADR 0031): a ref it refused goes back to its value before
+        // the push, by compare-and-set under the ref lock (a later push built on it keeps its value), its push and effects
+        // are reverted (head.ts), and the client hears git's own report, `ok` or `ng` for each ref
+        if (pushes.length) {
+            const whole = performed instanceof RefusedWriteError ? performed.reason : performed instanceof VendorWriteError ? performed.message : undefined;
+            const refused = new Map();
+            for (const p of pushes) {
+                const reason = whole ?? performed.refused?.find((r) => r.actionId === p.actionId)?.reason;
+                if (reason !== undefined)
+                    refused.set(p.actionId, reason);
+            }
+            if (refused.size) {
+                for (const p of [...pushes].reverse()) {
+                    if (!refused.has(p.actionId))
+                        continue;
+                    const { refs } = gitRepositoryOf(m, p.name, options.root);
+                    refs.withLock(() => {
+                        if ((refs.get(p.ref) ?? ZERO_SHA) !== p.after)
+                            return;
+                        if (p.before === ZERO_SHA)
+                            refs.delete(p.ref);
+                        else
+                            refs.set(p.ref, p.before);
+                    });
+                }
+                const ng = new Map(pushes.filter((p) => refused.has(p.actionId)).map((p) => [p.ref, refused.get(p.actionId).replace(/\s+/g, ' ')]));
+                const report = concat(...readPktLines(new Uint8Array(await answer.arrayBuffer())).lines.map((line) => {
+                    const ref = line.startsWith('ok ') ? line.slice(3).trim() : undefined;
+                    return pktLine(ref !== undefined && ng.has(ref) ? `ng ${ref} ${ng.get(ref)}\n` : line);
+                }), FLUSH);
+                const headers = new Headers(answer.headers);
+                headers.delete('content-length');
+                return new Response(report, { status: answer.status, headers });
+            }
+        }
         // the vendor's refusal, as its status and words (perform names them `<status>: <message>`), in the vendor's error body
         if (performed instanceof RefusedWriteError) {
             const said = /^(\d{3}): ([\s\S]*)$/.exec(performed.reason);

package/dist/src/pack-paths.d.ts

@@ -8,9 +8,8 @@ export declare function installedVendorPacks(from: string, options?: {
 }): Map<string, string>;
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export declare function installedPackageDir(from: string, name: string): string | undefined;
-/** A pack repository itself, or a platform checkout's P3 repository: the one `VOLTER_PACKS` names (a worktree's own
- *  pinned packs, as the repository's scripts read it), else the one beside it. Applications do not acquire a
- *  sibling checkout merely because one happens to be beside them. */
+/** The pack repository a World is rooted in, when it is one (ADR 0034: a platform checkout finds no pack repository
+ *  beside it; a pack reaches any other World as an installed or linked package). */
 export declare function packRepository(from: string): string | undefined;
 /** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */
 export declare function vendorPackageDir(from: string, vendor: string): string | undefined;

package/dist/src/pack-paths.js

@@ -121,23 +121,13 @@ export function installedPackageDir(from, name) {
         dir = up;
     }
 }
-/** A pack repository itself, or a platform checkout's P3 repository: the one `VOLTER_PACKS` names (a worktree's own
- *  pinned packs, as the repository's scripts read it), else the one beside it. Applications do not acquire a
- *  sibling checkout merely because one happens to be beside them. */
+/** The pack repository a World is rooted in, when it is one (ADR 0034: a platform checkout finds no pack repository
+ *  beside it; a pack reaches any other World as an installed or linked package). */
 export function packRepository(from) {
     let dir = resolve(from);
     for (;;) {
         if (packageName(dir) === 'twin-packs-p3')
             return dir;
-        if (packageName(join(dir, 'packages', 'world-core')) === '@volter/world-core') {
-            const env = globalThis.process?.env?.VOLTER_PACKS;
-            const named = env ? resolve(env) : undefined;
-            if (named && packageName(named) === 'twin-packs-p3')
-                return named;
-            const sibling = join(dirname(dir), 'twin-packs-p3');
-            if (packageName(sibling) === 'twin-packs-p3')
-                return sibling;
-        }
         const up = dirname(dir);
         if (up === dir)
             return undefined;
@@ -148,7 +138,7 @@ export function packRepository(from) {
 export function vendorPackageDir(from, vendor) {
     if (!/^[a-z][a-z0-9-]*$/.test(vendor))
         return undefined;
-    const installed = installedVendorPacks(from).get(vendor);
+    const installed = installedVendorPacks(from, { vendors: [vendor] }).get(vendor);
     const repo = packRepository(from);
     const checkout = repo === undefined ? undefined : join(repo, vendor);
     if (!checkout || packageName(checkout) !== `@volter/twin-${vendor}` || !isDerivedPack(checkout))

package/dist/src/packRegistry.d.ts

@@ -118,7 +118,9 @@ export declare function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promis
  * matches and no exclude does. Validated by scripts/pack-facts.ts: keys are `[a-z0-9-]+`, a
  * foreign key is never another pack's vendor id, belongs to one pack, and must appear in the
  * pack's `adoption.worldIds` (the world wires `<KEY>_TWIN_URL` from there); a pack must claim its
- * own vendor id too; no key is exclude-only; `exclude` is `true` or absent.
+ * own vendor id too; no key is exclude-only; `exclude` is `true` or absent. `basic` is a vendor fact for the executor: on
+ * a URL the rule names, the host takes the sealed token as HTTP Basic's password under this user (a vendor's git over
+ * HTTP whose API takes the same token as a bearer; ADR 0031).
  */
 export type HostRule = ({
     host: string;
@@ -131,6 +133,7 @@ export type HostRule = ({
     demandPathPattern?: string | false;
     key?: string;
     exclude?: true;
+    basic?: string;
 };
 export type RoundTripWrite = {
     method: string;
@@ -255,6 +258,19 @@ export type TwinPack = {
         scheme?: string;
         note: string;
     }>;
+    /** The vendor's own requests a World's generated seed makes for what its world.json declares (ADR 0033 §3), each a URL
+     *  at the vendor's own host, defined by the twin's own screen form for that act: its sign-up, and its domain screen's
+     *  add and verify with `record`, the one `/_twin/` stand-in, for a record at the domain's DNS host; `settles` is the
+     *  World-clock time the vendor takes to settle a verified domain (`10m`). */
+    seed?: {
+        signUp?: string;
+        domain?: {
+            add: string;
+            record: string;
+            verify: string;
+            settles: string;
+        };
+    };
     stateSystem?: StateSystemAdapters;
     /** The pack has no vendor-backed half, and why (copied from the manifest by packOf). */
     vendorBacked?: {

package/dist/src/runtime.d.ts

@@ -55,6 +55,7 @@ export { installedPackageDir, installedVendorPacks, packVendor, packRepository,
 export * as git from './git/index.js';
 export * as s3 from './s3/wire.js';
 export * as xml from './xml.js';
+export * as html from './html.js';
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from './placeholder-remote.js';
 export { aliasesFrom, ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from './log.js';
 export type { BranchMeta, Entry, EntryOp, Receipt } from './log.js';
@@ -79,6 +80,7 @@ export { brandTokensResponse } from './brand-tokens.js';
 export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern, type MultipartPart, type MultipartFramedPart, type MultipartEnvelope } from './multipart.js';
 export { corsHeaders, withCors, type CorsDecl } from './cors.js';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.js';
+export { setInProcessMailServers } from './smtp.js';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.js';

package/dist/src/runtime.js

@@ -78,6 +78,8 @@ export * as git from "./git/index.js";
 export * as s3 from "./s3/wire.js";
 // Generic strict XML grammar; vendor interpretation remains in its consumer.
 export * as xml from "./xml.js";
+// Generic WHATWG HTML grammar; what a pack keeps of received HTML remains the pack's policy.
+export * as html from "./html.js";
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 // The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
@@ -102,6 +104,7 @@ export { brandTokensResponse } from "./brand-tokens.js";
 export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern } from "./multipart.js";
 export { corsHeaders, withCors } from "./cors.js";
 export { setInProcessTwins, vendorFetch, VendorUnreachableError } from "./vendor-call.js";
+export { setInProcessMailServers } from "./smtp.js";
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver } from "./managed-database.js";
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from "./resource-blob.js";
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";

package/dist/src/serve-http.d.ts

@@ -67,7 +67,7 @@ export declare function serveStream(options: {
     maxConnections?: number;
 }): Promise<{
     port: number;
-    stop: () => void;
+    stop: () => Promise<void>;
 }>;
 export type WebSocketRelay = {
     url: string;

package/dist/src/serve-http.js

@@ -153,6 +153,7 @@ export async function serveStream(options) {
         throw new StreamListenerUnavailable('this runtime has no TCP listener (node:net)');
     const cap = options.maxConnections ?? options.stream.maxConnections;
     let open = 0;
+    const accepted = new Set();
     const server = net.createServer((socket) => {
         // past its cap a connection is closed before the stream sees it, so connections that never get anywhere cannot pile up
         if (cap !== undefined && open >= cap) {
@@ -160,7 +161,8 @@ export async function serveStream(options) {
             return;
         }
         open += 1;
-        socket.once('close', () => { open -= 1; });
+        accepted.add(socket);
+        socket.once('close', () => { open -= 1; accepted.delete(socket); });
         const conn = options.stream({ write: (bytes) => { socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '127.0.0.1');
         // a connection that says what waits (`backlog`: whole messages its work has not reached) is read no further past the
         // high-water mark until that work has settled, so a peer faster than the twin (a live ingest pushed faster than real
@@ -182,7 +184,14 @@ export async function serveStream(options) {
     });
     await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname ?? '127.0.0.1', () => resolve()); });
     const address = server.address();
-    return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop: () => { server.close(); } };
+    // stop is the listener's real retirement: it settles once the listener is closed and every connection it accepted has
+    // ended (each is closed here, so none holds the close open)
+    const stop = () => new Promise((resolve) => {
+        server.close(() => resolve());
+        for (const socket of accepted)
+            socket.destroy();
+    });
+    return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop };
 }
 function builtin(name) {
     const get = process.getBuiltinModule;

package/dist/src/smtp-server.d.ts

@@ -0,0 +1,78 @@
+import type { HandlerContext } from './derived-core.js';
+import type { TwinStream } from './twin-fetch.js';
+/** What a server's front answers the stream: its reply lines, the moved session, and whether the stream reads a
+ *  message's data next (`data`), an AUTH response (`auth`) or commands, or closes. */
+export type SmtpAnswer<S> = {
+    replies: string[];
+    session: S;
+    mode: 'command' | 'data' | 'auth';
+    close?: boolean;
+};
+/** The bridge between a connection and the pack's front: the header that carries the pack's key, the key, a fresh
+ *  session, and the pack's answer when its front cannot answer (its words for a local error). */
+export type SmtpBridge<S> = {
+    header: string;
+    key: () => string;
+    fresh: () => S;
+    failure: (session: S) => SmtpAnswer<S>;
+};
+/** A connection's bytes framed as SMTP frames them, each piece posted to the pack's front (`smtpFront`) through its
+ *  fetch with the session the connection carries: commands are lines ended by CRLF; after a 354, the message's lines up
+ *  to the lone dot, their leading dot removed; after a 334, one line of AUTH response. Pipelined commands are answered
+ *  in order. */
+export declare function smtpStream<S>(fetch: (request: Request) => Response | Promise<Response>, bridge: SmtpBridge<S>): TwinStream;
+/** What a pack's front does with each piece the stream carries: the greeting, a command line, a message's data, an AUTH
+ *  response (a server that takes none leaves it out). */
+type SmtpServer<S> = {
+    open(): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+    command(session: S, line: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+    data(session: S, data: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+    response?(session: S, response: string): SmtpAnswer<S> | Promise<SmtpAnswer<S>>;
+};
+/** The pack's front (its `around`): a request the stream signed with the pack's key is a piece of a connection, answered
+ *  by the pack's server; any other request is the pack's own (its doors and screens). */
+export declare function smtpFront<S>(ctx: HandlerContext, next: (request?: Request) => Promise<Response>, bridge: SmtpBridge<S>, server: SmtpServer<S>): Promise<Response>;
+/** A command's verb (upper-cased) and its argument. */
+export declare function smtpCommand(line: string): {
+    verb: string;
+    arg: string;
+};
+/** The session machine's word on a command from where a session stands (the manifest's states): a refusal's reply, or
+ *  undefined to go on. */
+export declare function smtpOrder(ctx: Pick<HandlerContext, 'legal'>, machine: string, stage: string, op: string, to?: string): string | undefined;
+/** EHLO's multi-line 250 reply: the server's name, then each keyword. */
+export declare const smtpEhlo: (keywords: string[]) => string[];
+/** An address's domain, lower-cased. */
+export declare const smtpDomain: (address: string) => string;
+/** MAIL's argument: the sender and its SIZE, BODY and SMTPUTF8 parameters, or why it is refused (the pack words it). */
+export declare function smtpMailFrom(arg: string): {
+    from: string;
+    size?: number;
+    smtputf8: boolean;
+} | {
+    refused: 'syntax' | 'sender' | 'size';
+} | {
+    refused: 'parameter';
+    parameter: string;
+};
+/** RCPT's argument: the recipient, or why it is refused (the pack words it). */
+export declare function smtpRcptTo(arg: string): {
+    to: string;
+} | {
+    refused: 'syntax' | 'recipient';
+} | {
+    refused: 'parameter';
+    parameter: string;
+};
+/** A transaction's state cleared, the greeting kept (RSET, a new EHLO, the end of DATA): the session's `stage`,
+ *  `greeted` and an empty `rcpt`, with whatever of the session the pack keeps across transactions (`kept`). */
+export declare function smtpCleared<S extends {
+    stage: string;
+    rcpt: string[];
+    greeted?: 'helo' | 'ehlo';
+}>(s: S, stage: string, kept: Omit<S, 'stage' | 'rcpt' | 'greeted' | 'from'>): Omit<S, 'stage' | 'rcpt' | 'greeted' | 'from'> & {
+    stage: string;
+    rcpt: string[];
+    greeted?: 'helo' | 'ehlo';
+};
+export {};