@specific.dev/spectest 0.39.0 → 0.43.0

package/dist/harness/ingress-table.js

@@ -0,0 +1,129 @@
+/**
+ * The live ingress tables: which hostname reaches which upstream, and
+ * which certificate serves the TLS handshake for it.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This module owns
+ * the *tables and the decisions*; the listeners themselves (`Bun.serve`)
+ * stay with the process that binds them, because a socket is not something
+ * you can hand across a module boundary usefully.
+ *
+ * ## Why this state is special
+ *
+ * These tables are ordinary module-scope objects, and that is the whole
+ * design. They live in the harness process, so they are captured by the
+ * memory snapshot and **fork with it** — exactly like fake state and the
+ * names registry. A `dependsOn` child inherits every route its parent
+ * bound; a sibling forked from an earlier snapshot never sees them. That
+ * is what lets a fake provision a real service mid-test and hand the app a
+ * CA-trusted `https://…` endpoint that only that branch of the test DAG
+ * can reach.
+ *
+ * The failure mode to design against is therefore *silence*: a route that
+ * fails to survive doesn't raise anything, it just isn't inherited, and
+ * the test that depended on it fails somewhere else entirely.
+ *
+ * ## The two rules worth stating
+ *
+ * **A route table is identified by its object, not its contents.** Every
+ * listener's request handler closes over the `Map` it was bound with, so
+ * adding an entry takes effect with no rebind — that is what makes a
+ * runtime route possible at all. Replacing the `Map` (rather than mutating
+ * it) silently orphans every listener still holding the old one, and the
+ * routes added afterwards go nowhere. {@link routesFor} is the only way to
+ * reach a table so that this can't be done by accident.
+ *
+ * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
+ * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
+ * genuinely new certificate means stopping and re-serving :443. It's cheap
+ * (~1 ms) but it is a real interruption of live traffic, and a hostname
+ * already covered by an existing exact or wildcard cert needs nothing but a
+ * route entry. {@link planBind} is that judgement, separated from the
+ * mutation so it can be tested without a network stack.
+ */
+import { certCovers, isWildcard, wildcardSuffix } from "./hostmatch";
+/** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */
+export const INGRESS_HTTPS_PORT = 443;
+/** Fixed HTTP port, always bound alongside :443 so both schemes work. */
+export const INGRESS_HTTP_PORT = 80;
+export function emptyTables() {
+    return { routesByPort: new Map(), certByHost: new Map() };
+}
+/**
+ * The route table for `port`, creating it if absent.
+ *
+ * Always returns the *same* object for a given port for as long as the
+ * tables live. Callers must mutate what they get back and must never swap
+ * in a replacement — see the module header for what that breaks.
+ */
+export function routesFor(tables, port) {
+    let routes = tables.routesByPort.get(port);
+    if (!routes) {
+        routes = new Map();
+        tables.routesByPort.set(port, routes);
+    }
+    return routes;
+}
+/**
+ * Decide what binding `hostname` for TLS costs.
+ *
+ * A rebind is needed when a new certificate is going into the SNI table,
+ * or when :443 isn't listening yet. It is deliberately *not* needed for a
+ * hostname an existing wildcard already covers — the common case when a
+ * component claims a whole domain up front and services appear under it
+ * later, and the reason a fake can mint endpoints in a loop without
+ * restarting the listener once per iteration.
+ */
+export function planBind(tables, hostname, opts) {
+    const needsCert = !certCovers(tables.certByHost.keys(), hostname);
+    return { needsCert, needsHttpsRebind: needsCert || !opts.httpsListening };
+}
+/**
+ * Point `hostname` at `route` on both :80 and :443.
+ *
+ * Boot `tls` serves both schemes, and runtime `tls` matches it — a service
+ * reachable only over https would differ from its boot-time twin in a way
+ * nothing declares.
+ */
+export function bindRoute(tables, hostname, route) {
+    routesFor(tables, INGRESS_HTTP_PORT).set(hostname, route);
+    routesFor(tables, INGRESS_HTTPS_PORT).set(hostname, route);
+}
+/**
+ * Drop `hostname`'s routes, so it 404s.
+ *
+ * The certificate is deliberately left in the SNI table: it is harmless
+ * without a route, and removing it would force an otherwise unnecessary
+ * :443 rebind at exactly the moment a service is going away.
+ */
+export function unbindRoute(tables, hostname) {
+    tables.routesByPort.get(INGRESS_HTTP_PORT)?.delete(hostname);
+    tables.routesByPort.get(INGRESS_HTTPS_PORT)?.delete(hostname);
+}
+/** The SNI entries for `Bun.serve`'s TLS config. */
+export function certEntries(tables) {
+    return [...tables.certByHost].map(([serverName, leaf]) => ({
+        cert: leaf.cert,
+        key: leaf.key,
+        serverName,
+    }));
+}
+/** Clear every table — used between `/load` calls so a new project's
+ *  routes bind against a clean slate rather than the old project's. */
+export function clearTables(tables) {
+    tables.routesByPort.clear();
+    tables.certByHost.clear();
+}
+/**
+ * Point a hostname at an IP in a names registry document, choosing the
+ * exact or wildcard table by the hostname's shape.
+ *
+ * A wildcard has no `--add-host` or `--network-alias` equivalent, so the
+ * resolver's suffix table is the only place it can exist; an exact name
+ * could live in either, and goes in the exact table so it keeps winning
+ * over any wildcard that also matches.
+ */
+export function registryTarget(hostname) {
+    return isWildcard(hostname)
+        ? { wildcard: true, suffix: wildcardSuffix(hostname) }
+        : { wildcard: false, host: hostname };
+}

package/dist/harness/log-delta.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-case service-log deltas.
+ *
+ * A container's log is cumulative, but the dashboard shows each test case
+ * only the lines *it* produced — the branch's full log is reconstructed by
+ * concatenating the deltas along the `dependsOn` chain. So every capture
+ * records how far it read (a line marker), and the next capture returns
+ * only what came after.
+ *
+ * The markers live in harness process memory, which means they fork with
+ * the snapshot exactly like fake state: a `dependsOn` child continues from
+ * where its parent stopped, and a sibling forked from an earlier snapshot
+ * sees the parent's lines again — which is correct, because for that
+ * sibling they *are* new.
+ *
+ * Ported out of `daemon.ts`; pure, so the boundary cases below are
+ * testable rather than inferred.
+ */
+/** Cap on one delta. Beyond this the middle is elided, not the tail. */
+export declare const LOG_DELTA_MAX_BYTES: number;
+/**
+ * Truncate from the **middle**, keeping both ends.
+ *
+ * Deliberately not a tail cap: the head of a service log carries the
+ * startup banner (bind address, version, config errors) and the tail
+ * carries whatever just failed. Dropping either loses the half that
+ * usually explains the problem.
+ */
+export declare function capMiddle(s: string, max: number): {
+    value: string;
+    truncated: boolean;
+};
+export interface StreamDelta {
+    /** The new lines, possibly middle-elided. */
+    delta: string;
+    /** Line count after this capture — the next call's marker. */
+    total: number;
+    /**
+     * The stream got *shorter* than the marker, so the container was
+     * restarted or its log rotated. The delta is then the whole log rather
+     * than a suffix, because line N is no longer the line N we saw.
+     */
+    reset: boolean;
+    truncated: boolean;
+}
+/**
+ * The portion of `full` after line `marker`.
+ *
+ * Only **complete** lines are returned. A partial trailing line is held
+ * back deliberately: docker's log stream can be read mid-write, and
+ * emitting half a line would both corrupt the delta and mean the next
+ * capture repeats the other half, since the marker counts lines.
+ */
+export declare function streamDelta(full: string, marker: number): StreamDelta;

package/dist/harness/log-delta.js

@@ -0,0 +1,83 @@
+/**
+ * Per-case service-log deltas.
+ *
+ * A container's log is cumulative, but the dashboard shows each test case
+ * only the lines *it* produced — the branch's full log is reconstructed by
+ * concatenating the deltas along the `dependsOn` chain. So every capture
+ * records how far it read (a line marker), and the next capture returns
+ * only what came after.
+ *
+ * The markers live in harness process memory, which means they fork with
+ * the snapshot exactly like fake state: a `dependsOn` child continues from
+ * where its parent stopped, and a sibling forked from an earlier snapshot
+ * sees the parent's lines again — which is correct, because for that
+ * sibling they *are* new.
+ *
+ * Ported out of `daemon.ts`; pure, so the boundary cases below are
+ * testable rather than inferred.
+ */
+/** Cap on one delta. Beyond this the middle is elided, not the tail. */
+export const LOG_DELTA_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * Truncate from the **middle**, keeping both ends.
+ *
+ * Deliberately not a tail cap: the head of a service log carries the
+ * startup banner (bind address, version, config errors) and the tail
+ * carries whatever just failed. Dropping either loses the half that
+ * usually explains the problem.
+ */
+export function capMiddle(s, max) {
+    if (s.length <= max)
+        return { value: s, truncated: false };
+    const half = Math.floor(max / 2);
+    const elided = s.length - 2 * half;
+    return {
+        value: `${s.slice(0, half)}\n… [${elided} bytes elided] …\n${s.slice(s.length - half)}`,
+        truncated: true,
+    };
+}
+/**
+ * The portion of `full` after line `marker`.
+ *
+ * Only **complete** lines are returned. A partial trailing line is held
+ * back deliberately: docker's log stream can be read mid-write, and
+ * emitting half a line would both corrupt the delta and mean the next
+ * capture repeats the other half, since the marker counts lines.
+ */
+export function streamDelta(full, marker) {
+    const lastNl = full.lastIndexOf("\n");
+    const complete = lastNl < 0 ? "" : full.slice(0, lastNl + 1);
+    let total = 0;
+    for (let i = 0; i < complete.length; i++) {
+        if (complete.charCodeAt(i) === 10)
+            total++;
+    }
+    // Fewer lines than we had already read means this is not the same log.
+    let reset = false;
+    let startLine = marker;
+    if (total < marker) {
+        reset = true;
+        startLine = 0;
+    }
+    let delta;
+    if (startLine <= 0) {
+        delta = complete;
+    }
+    else if (startLine >= total) {
+        delta = "";
+    }
+    else {
+        // Byte offset just past the `startLine`-th newline.
+        let seen = 0;
+        let off = 0;
+        for (let i = 0; i < complete.length; i++) {
+            if (complete.charCodeAt(i) === 10 && ++seen === startLine) {
+                off = i + 1;
+                break;
+            }
+        }
+        delta = complete.slice(off);
+    }
+    const capped = capMiddle(delta, LOG_DELTA_MAX_BYTES);
+    return { delta: capped.value, total, reset, truncated: capped.truncated };
+}

package/dist/harness/main.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The harness process.
+ *
+ * Started by the supervisor (`crates/spectest-vm-agent/src/supervisor.rs`)
+ * from the app dir's `node_modules`, so it is the *user's* SDK version
+ * that runs the user's project. It dials the socket the supervisor
+ * already bound, completes the `hello` handshake, and then serves
+ * requests until told to shut down.
+ *
+ * ## This process is long-lived and is never restarted
+ *
+ * It holds the state that makes forking a product feature — fake `state`,
+ * the ingress listeners with their per-fork route and certificate tables,
+ * the DNS registry, containers started mid-test, live browser sessions,
+ * the recorder. The supervisor deliberately has no respawn path: if this
+ * process dies, the environment is dead and says so, rather than silently
+ * coming back empty.
+ *
+ * So the rules here are: never call `process.exit` on a request failure
+ * (answer with an error instead), and never let an unhandled rejection
+ * take the process down.
+ *
+ * ## One implementation, two transports
+ *
+ * Everything this serves comes from the same method table the legacy HTTP
+ * daemon serves (`METHODS`, built in `daemon.ts`). That is deliberate and
+ * temporary: during the cutover both transports are live, and the failure
+ * being designed out is the one where a fix lands on the transport that is
+ * being replaced and never reaches the new one.
+ *
+ * The table is built **once** per process, so the mutual-exclusion slots
+ * that stop two tests running at the same time are shared across both
+ * transports. Two tables would each enforce the rule and together break it.
+ */
+type Handler = (params: Record<string, unknown>) => Promise<unknown>;
+/** Methods this build can serve. Everything else is answered with an
+ *  error naming the method, which is far easier to diagnose than a
+ *  request that hangs. */
+export declare function handlers(sdkVersion: string, onShutdown: () => void, methods?: Record<string, Handler>): Record<string, Handler>;
+/**
+ * Serve one connection until it closes.
+ *
+ * Split from `main` so it can be driven over any duplex stream in tests.
+ */
+export declare function serve(socket: NodeJS.ReadWriteStream, registry: Record<string, Handler>): void;
+export declare function main(): Promise<void>;
+export {};

package/dist/harness/main.js

@@ -0,0 +1,164 @@
+/**
+ * The harness process.
+ *
+ * Started by the supervisor (`crates/spectest-vm-agent/src/supervisor.rs`)
+ * from the app dir's `node_modules`, so it is the *user's* SDK version
+ * that runs the user's project. It dials the socket the supervisor
+ * already bound, completes the `hello` handshake, and then serves
+ * requests until told to shut down.
+ *
+ * ## This process is long-lived and is never restarted
+ *
+ * It holds the state that makes forking a product feature — fake `state`,
+ * the ingress listeners with their per-fork route and certificate tables,
+ * the DNS registry, containers started mid-test, live browser sessions,
+ * the recorder. The supervisor deliberately has no respawn path: if this
+ * process dies, the environment is dead and says so, rather than silently
+ * coming back empty.
+ *
+ * So the rules here are: never call `process.exit` on a request failure
+ * (answer with an error instead), and never let an unhandled rejection
+ * take the process down.
+ *
+ * ## One implementation, two transports
+ *
+ * Everything this serves comes from the same method table the legacy HTTP
+ * daemon serves (`METHODS`, built in `daemon.ts`). That is deliberate and
+ * temporary: during the cutover both transports are live, and the failure
+ * being designed out is the one where a fix lands on the transport that is
+ * being replaced and never reaches the new one.
+ *
+ * The table is built **once** per process, so the mutual-exclusion slots
+ * that stop two tests running at the same time are shared across both
+ * transports. Two tables would each enforce the rule and together break it.
+ */
+import net from "node:net";
+import { METHODS } from "../daemon";
+import { codeOf } from "./methods";
+import { PROTOCOL_VERSION, decodeFrame, encodeFrame, fail, ok, } from "./protocol";
+/** Capabilities this build announces. Empty is fine — the slot is what
+ *  matters, so a later release has something to negotiate against. */
+const CAPABILITIES = [];
+/** Methods this build can serve. Everything else is answered with an
+ *  error naming the method, which is far easier to diagnose than a
+ *  request that hangs. */
+export function handlers(sdkVersion, onShutdown, methods = METHODS) {
+    return {
+        // Everything the environment actually does.
+        ...methods,
+        // Transport-level methods, which the method table has no business
+        // knowing about: they concern this connection, not this environment.
+        // Declared after the spread so the table can never shadow them — a
+        // `shutdown` that didn't shut down would be an unkillable environment.
+        hello: async () => ({
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: CAPABILITIES,
+            sdkVersion,
+        }),
+        shutdown: async () => {
+            // Reply first, exit after — the supervisor is waiting on this
+            // response, and dropping the connection instead would surface as a
+            // transport error rather than a clean stop.
+            queueMicrotask(onShutdown);
+            return {};
+        },
+    };
+}
+/**
+ * Serve one connection until it closes.
+ *
+ * Split from `main` so it can be driven over any duplex stream in tests.
+ */
+export function serve(socket, registry) {
+    let buffered = "";
+    const send = (frame) => socket.write(encodeFrame(frame));
+    const dispatch = async (req) => {
+        const handler = registry[req.method];
+        if (!handler) {
+            send(fail(req.id, `harness does not implement ${JSON.stringify(req.method)}`, "unimplemented"));
+            return;
+        }
+        try {
+            send(ok(req.id, (await handler(req.params ?? {}))));
+        }
+        catch (err) {
+            // A failing request must not take the process down: the harness holds
+            // the environment's live state, so its death is unrecoverable.
+            //
+            // A refusal the method meant to make (an unknown case, a second test
+            // while one is running) reports its own kind and just its message. An
+            // unexpected throw is a bug in the method and carries the stack,
+            // which is the only place that information exists.
+            const e = err;
+            const code = codeOf(err);
+            const detail = code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+            send(fail(req.id, detail, code));
+        }
+    };
+    socket.on("data", (chunk) => {
+        buffered += chunk.toString();
+        // NDJSON: a chunk can hold several frames, or half of one.
+        for (;;) {
+            const nl = buffered.indexOf("\n");
+            if (nl === -1)
+                break;
+            const line = buffered.slice(0, nl);
+            buffered = buffered.slice(nl + 1);
+            if (!line.trim())
+                continue;
+            let frame;
+            try {
+                frame = decodeFrame(line);
+            }
+            catch (e) {
+                // Unroutable — no id to answer on. Log and keep serving rather
+                // than dropping a connection that is otherwise healthy.
+                console.error(`harness: ${e.message}`);
+                continue;
+            }
+            if (frame.kind === "request")
+                void dispatch(frame);
+            // Responses to our own up-calls and events are handled elsewhere;
+            // ignoring them here keeps this loop about serving.
+        }
+    });
+}
+/** Read the SDK's own version, for the handshake. */
+async function sdkVersion() {
+    try {
+        const pkg = await import("../../package.json", { with: { type: "json" } });
+        return pkg.default?.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export async function main() {
+    const path = process.env.SPECTEST_HARNESS_SOCKET;
+    if (!path) {
+        console.error("harness: SPECTEST_HARNESS_SOCKET is not set");
+        process.exit(2);
+    }
+    // An unhandled rejection anywhere in user code must not kill the
+    // environment — report it and keep serving.
+    process.on("unhandledRejection", (reason) => {
+        console.error("harness: unhandled rejection:", reason);
+    });
+    const version = await sdkVersion();
+    const socket = net.createConnection(path);
+    socket.on("error", (e) => {
+        console.error(`harness: socket error: ${e.message}`);
+        process.exit(1);
+    });
+    socket.on("close", () => {
+        // The supervisor went away; there is nothing left to serve.
+        process.exit(0);
+    });
+    await new Promise((resolve) => socket.once("connect", () => resolve()));
+    serve(socket, handlers(version, () => socket.end(() => process.exit(0))));
+}
+// Only run when executed directly, so importing this module in a test
+// doesn't try to dial a socket.
+if (import.meta.main) {
+    void main();
+}

package/dist/harness/methods.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What the harness can be asked to do, independent of how it was asked.
+ *
+ * The daemon grew as an HTTP server, so every operation was written against
+ * `IncomingMessage`/`ServerResponse`: parsing a body, choosing a status
+ * code, and writing a reply were tangled up with deciding what to actually
+ * do. That is the coupling this module removes. A method here takes plain
+ * params and returns a plain object; a *transport* — the legacy HTTP router,
+ * or the supervisor's frame protocol — adapts to it.
+ *
+ * The point is that both transports run the **same** implementation. During
+ * the cutover the two are live at once, and the failure this design refuses
+ * to allow is the one where a fix lands on the transport that is being
+ * replaced and quietly doesn't reach the new one.
+ *
+ * ## Errors carry a kind, not a status code
+ *
+ * HTTP status codes were the daemon's error vocabulary: 400 for a bad body,
+ * 404 for an unknown case, 409 for "already running". The frame protocol has
+ * no statuses, so the kind is named ({@link HarnessErrorCode}) and each
+ * transport renders it — the frame protocol carries it as the error's
+ * `code`. Naming them also makes the one that matters legible: `conflict` is
+ * not a client mistake, it is the harness refusing to run two tests in one
+ * process at once, which is a correctness property rather than a validation
+ * failure.
+ */
+/** The kinds of failure a method can report. */
+export type HarnessErrorCode = 
+/** The request itself was malformed — missing or wrong-typed params. */
+"bad_request"
+/** The thing named does not exist here (an unknown case id). */
+ | "not_found"
+/** Refused because something incompatible is already running. */
+ | "conflict"
+/** The method ran and threw. */
+ | "handler_error";
+/** An error a transport can render without knowing what failed. */
+export declare class HarnessError extends Error {
+    readonly code: HarnessErrorCode;
+    constructor(code: HarnessErrorCode, message: string);
+}
+export declare const badRequest: (m: string) => HarnessError;
+export declare const notFound: (m: string) => HarnessError;
+export declare const conflict: (m: string) => HarnessError;
+/** One operation: plain params in, plain result out. */
+export type Method = (params: Record<string, unknown>) => Promise<unknown>;
+/** Everything the harness can serve, by method name. */
+export type MethodTable = Record<string, Method>;
+/** The kind to report for a value thrown from a method body. Anything that
+ *  isn't already a {@link HarnessError} is an unexpected failure inside the
+ *  method, not a statement about the request. */
+export declare function codeOf(err: unknown): HarnessErrorCode;
+/** Require a non-empty string param, with the message the caller had. */
+export declare function requireString(params: Record<string, unknown>, name: string, label?: string): string;

package/dist/harness/methods.js

@@ -0,0 +1,65 @@
+/**
+ * What the harness can be asked to do, independent of how it was asked.
+ *
+ * The daemon grew as an HTTP server, so every operation was written against
+ * `IncomingMessage`/`ServerResponse`: parsing a body, choosing a status
+ * code, and writing a reply were tangled up with deciding what to actually
+ * do. That is the coupling this module removes. A method here takes plain
+ * params and returns a plain object; a *transport* — the legacy HTTP router,
+ * or the supervisor's frame protocol — adapts to it.
+ *
+ * The point is that both transports run the **same** implementation. During
+ * the cutover the two are live at once, and the failure this design refuses
+ * to allow is the one where a fix lands on the transport that is being
+ * replaced and quietly doesn't reach the new one.
+ *
+ * ## Errors carry a kind, not a status code
+ *
+ * HTTP status codes were the daemon's error vocabulary: 400 for a bad body,
+ * 404 for an unknown case, 409 for "already running". The frame protocol has
+ * no statuses, so the kind is named ({@link HarnessErrorCode}) and each
+ * transport renders it — the frame protocol carries it as the error's
+ * `code`. Naming them also makes the one that matters legible: `conflict` is
+ * not a client mistake, it is the harness refusing to run two tests in one
+ * process at once, which is a correctness property rather than a validation
+ * failure.
+ */
+/** An error a transport can render without knowing what failed. */
+export class HarnessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HarnessError";
+        this.code = code;
+    }
+}
+export const badRequest = (m) => new HarnessError("bad_request", m);
+export const notFound = (m) => new HarnessError("not_found", m);
+export const conflict = (m) => new HarnessError("conflict", m);
+/** How a transport that speaks HTTP renders an error kind. */
+function unusedHttpStatusFor(code) {
+    switch (code) {
+        case "bad_request":
+            return 400;
+        case "not_found":
+            return 404;
+        case "conflict":
+            return 409;
+        case "handler_error":
+            return 500;
+    }
+}
+/** The kind to report for a value thrown from a method body. Anything that
+ *  isn't already a {@link HarnessError} is an unexpected failure inside the
+ *  method, not a statement about the request. */
+export function codeOf(err) {
+    return err instanceof HarnessError ? err.code : "handler_error";
+}
+/** Require a non-empty string param, with the message the caller had. */
+export function requireString(params, name, label = `${name} (string)`) {
+    const v = params[name];
+    if (typeof v !== "string" || v.length === 0) {
+        throw badRequest(`${label} is required`);
+    }
+    return v;
+}

package/dist/harness/names-registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The DNS names registry: the file the harness writes and
+ * `spectest-resolver` reads.
+ *
+ * Ported out of `daemon.ts`. The point of a shared module is that this
+ * format had **two independent implementations** — the writer here and
+ * the reader in `resolver.ts` — with nothing keeping them in step. That
+ * is the same shape as the `config.rs` ↔ SDK drift the harness split
+ * exists to remove, just inside one language.
+ *
+ * The registry answers names that Docker's own DNS cannot:
+ *  - fake hostnames (`api.stripe.com` → the bridge gateway),
+ *  - names bound at runtime by `ctx.dnsName`,
+ *  - **wildcards** (`*.us-east-1.amazonaws.com`), which have no
+ *    `--add-host` or `--network-alias` equivalent and therefore *only*
+ *    exist here.
+ *
+ * Lookup is exact-first, then longest matching suffix — the same
+ * precedence the ingress routes and the SNI cert table use.
+ */
+export interface RegistryDoc {
+    /** Exact name → IP. */
+    hosts: Record<string, string>;
+    /** Suffix (with leading dot) → IP, longest match wins. */
+    wildcards: Array<{
+        suffix: string;
+        ip: string;
+    }>;
+    /** Written by the harness; the resolver re-reads on mtime change, so
+     *  this is diagnostic rather than load-bearing. */
+    updatedAt?: number;
+}
+export declare const EMPTY_REGISTRY: RegistryDoc;
+/** Serialise for the resolver. */
+export declare function encodeRegistry(doc: RegistryDoc, now: number): string;
+/**
+ * Parse a registry file.
+ *
+ * Deliberately total: a truncated or malformed file yields an **empty**
+ * registry rather than throwing. The resolver reads this on a hot path
+ * while the harness may be rewriting it, and a parse error there would
+ * take out DNS for the whole environment — every name, not just the one
+ * being added. Degrading to "no custom names" is recoverable; the next
+ * successful read restores everything.
+ */
+export declare function decodeRegistry(text: string): RegistryDoc;
+/** `"*.example.com"` → `".example.com"`, the form stored in `wildcards`. */
+export declare function suffixOf(pattern: string): string;
+/**
+ * Resolve a name: exact entry first, then the longest matching wildcard
+ * suffix. Returns `null` when nothing matches, which is the resolver's
+ * signal to fall through to Docker's DNS and then upstream.
+ */
+export declare function lookup(doc: RegistryDoc, name: string): string | null;
+/**
+ * Add or replace a name.
+ *
+ * A wildcard replaces any existing entry for the same suffix rather than
+ * appending, so re-registering a name (which `ctx.dnsName` allows, and
+ * which a re-run of a `setup` hook does) cannot grow the list without
+ * bound or leave two entries racing on equal suffix length.
+ */
+export declare function upsert(doc: RegistryDoc, hostname: string, ip: string): RegistryDoc;