@specific.dev/spectest 0.131.19 → 0.131.20

package/dist/daemon.js

@@ -65,12 +65,12 @@ import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, tak
 import { compactReach, projectReach, renderReachRules, renderReadsLcov } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
-import { encodeRegistry } from "./harness/names-registry.js";
+import { ServiceDns, ServiceOperations } from "./harness/service-dns.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, withIngressCors, upstreamRequestHeaders, } from "./harness/http-proxy.js";
 import { openUpstreamWebSocket, parseSubprotocols, upstreamHandshakeHeaders, } from "./harness/ws-bridge.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectCertName, wildcardSuffix, } from "./harness/hostmatch.js";
-import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, routesFor, unbindRoute, } from "./harness/ingress-table.js";
 import { startIngressServer } from "./harness/ingress-server.js";
 import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
@@ -1218,7 +1218,9 @@ async function runContainer(svc, tag, volumeFlags,
 extraAliases = []) {
     // Preserve the previous incarnation before the name is reused.
     if (RUNTIME_SERVICES.has(svc.name))
-        await stopRuntimeService(svc.name);
+        await stopRuntimeServiceUnlocked(svc.name);
+    PROXY_IP_CACHE.delete(svc.name);
+    await SERVICE_DNS.service(svc.name, null, [...(LOWERED.aliasesByService[svc.name] ?? []), ...extraAliases]);
     STOPPED_LOG_SERVICES.delete(svc.name);
     LOG_MARKERS.delete(`${svc.name}\0stdout`);
     LOG_MARKERS.delete(`${svc.name}\0stderr`);
@@ -1243,6 +1245,11 @@ extraAliases = []) {
     if (r.code !== 0) {
         throw new Error(`docker run ${svc.name} failed: ${r.stderr.trim() || r.stdout.trim()}`);
     }
+    const ip = await serviceContainerIp(svc.name);
+    if (!ip)
+        throw new Error(`Service ${svc.name} has no IP on ${NETWORK_NAME} after docker run`);
+    await SERVICE_DNS.service(svc.name, ip);
+    PROXY_IP_CACHE.set(svc.name, ip);
 }
 async function probeTcp(host, port) {
     return new Promise((resolve) => {
@@ -1403,13 +1410,12 @@ async function withContainerPostMortem(name, err) {
 //     same root CA, so `ctx.browser()` and peer services trust it.
 //
 // Both listeners bind on 0.0.0.0 so containers reach them via the
-// bridge gateway IP (also written into /run/spectest-fakes.json for
+// bridge gateway IP (also published in the DNS registry for
 // spectest-resolver and injected as --add-host on every container).
 //
 // Per-fake `state` is plain JS memory and lives across snapshot/fork
 // along with the rest of the daemon — every fork sees its own copy.
 // ────────────────────────────────────────────────────────────────────────
-const FAKES_REGISTRY_PATH = process.env.SPECTEST_FAKES_REGISTRY ?? "/run/spectest-fakes.json";
 const DEFAULT_FAKE_PORT = 80;
 /** All loaded fakes, keyed by stable name (the `fakes` map key). Holds the
  *  in-daemon handler, forked state, and helpers — the parts intrinsic to a
@@ -1581,9 +1587,7 @@ async function startIngress() {
         LOWERED.wildcards.length > 0;
     if (!hasIngress) {
         // Make sure the resolver doesn't see stale entries from a prior project.
-        REGISTRY.hosts = {};
-        REGISTRY.wildcards = [];
-        await writeRegistry();
+        await seedNamesRegistry();
         return;
     }
     const gw = await bridgeGatewayIp();
@@ -1671,9 +1675,9 @@ async function startIngress() {
         await ensureHttpsIngress();
     // Seed the resolver's names registry: ingress hostnames (fakes, TLS
     // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
-    // wildcards. Service-targeted wildcards wait for the post-container pass
-    // (their containers aren't up yet). Dynamic ctx.dnsName calls extend this.
-    await seedNamesRegistry({ servicesUp: false });
+    // wildcards. Service-targeted names are reserved until runContainer
+    // publishes their IPs. Dynamic ctx.dnsName calls extend this.
+    await seedNamesRegistry();
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function requireBun() {
@@ -1804,7 +1808,10 @@ function certCovers(hostname) {
  * per-test snapshot exactly like fake state — a `dependsOn` child inherits
  * it, siblings forked from an earlier snapshot never see it.
  */
-async function bindRuntimeTls(hostname, service, port, http2, cors) {
+function bindRuntimeTls(hostname, service, port, http2, cors) {
+    return TLS_OPERATIONS.run(hostname.toLowerCase(), () => bindRuntimeTlsUnlocked(hostname, service, port, http2, cors));
+}
+async function bindRuntimeTlsUnlocked(hostname, service, port, http2, cors) {
     // Reuse the boot primitives for validation + lowercasing; throws on a
     // malformed hostname / upstream just like a boot `tls` would at load.
     const decl = makeProxyDecl(hostname, { service, port, http2, cors });
@@ -1839,15 +1846,7 @@ async function bindRuntimeTls(hostname, service, port, http2, cors) {
     // Resolve the hostname to the daemon gateway (where :443/:80 listen).
     // A wildcard can only live in the resolver's suffix table.
     const gw = await bridgeGatewayIp();
-    const target = registryTarget(host);
-    if (target.wildcard) {
-        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== target.suffix);
-        REGISTRY.wildcards.push({ suffix: target.suffix, ip: gw });
-    }
-    else {
-        REGISTRY.hosts[target.host] = gw;
-    }
-    await writeRegistry();
+    await SERVICE_DNS.bind(host, { ip: gw }, `tls:${service}`);
     // eslint-disable-next-line no-console
     console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
 }
@@ -1857,20 +1856,16 @@ async function bindRuntimeTls(hostname, service, port, http2, cors) {
  * left in the SNI table — harmless without a route, and removing it would
  * mean an avoidable :443 rebind.
  */
-async function unbindRuntimeTls(hostname) {
+function unbindRuntimeTls(hostname, service) {
+    return TLS_OPERATIONS.run(hostname.toLowerCase(), () => unbindRuntimeTlsUnlocked(hostname, service));
+}
+async function unbindRuntimeTlsUnlocked(hostname, service) {
     const host = hostname.toLowerCase();
-    unbindRoute(INGRESS, host);
-    const target = registryTarget(host);
-    if (target.wildcard) {
-        const before = REGISTRY.wildcards.length;
-        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== target.suffix);
-        if (REGISTRY.wildcards.length !== before)
-            await writeRegistry();
-    }
-    else if (target.host in REGISTRY.hosts) {
-        delete REGISTRY.hosts[target.host];
-        await writeRegistry();
-    }
+    // A newer service may have taken this route/name. Do not remove its route.
+    const route = INGRESS.routesByPort.get(INGRESS_HTTP_PORT)?.get(host);
+    if (route?.kind === "proxy" && route.service === service)
+        unbindRoute(INGRESS, host);
+    await SERVICE_DNS.retire(host, `tls:${service}`);
 }
 /** Concurrent runtime routes must share the asynchronous first bind. */
 async function ensureHttpIngress(port, byHost) {
@@ -2125,30 +2120,10 @@ server, service, port, listenerLabel, proto) {
     const e = lastErr;
     return new Response(`spectest-daemon: upstream ${service}:${port} unreachable: ${e?.message ?? String(lastErr)}\n`, { status: 502, headers: { "content-type": "text/plain" } });
 }
-/**
- * In-memory names registry, serialised to FAKES_REGISTRY_PATH for the
- * resolver. `startIngress` seeds it from LOWERED (the static
- * tls/hostnames/fakes/wildcard decls); `registerDnsName` mutates it live
- * when a test calls `ctx.dnsName`. It lives in daemon memory, so it forks
- * with the rest of the snapshot — a test's dynamic registration is
- * isolated to its own fork, exactly like fake state.
- */
-const REGISTRY = { hosts: {}, wildcards: [] };
-async function writeRegistry() {
-    // Format + lookup semantics live in `harness/names-registry.ts`, shared
-    // with the resolver that reads this file.
-    const body = encodeRegistry(REGISTRY, Date.now());
-    try {
-        await fs.mkdir(path.dirname(FAKES_REGISTRY_PATH), { recursive: true });
-        await fs.writeFile(FAKES_REGISTRY_PATH, body);
-    }
-    catch (err) {
-        // Resolver gracefully degrades; just log.
-        // eslint-disable-next-line no-console
-        console.warn(`[names] failed to write registry at ${FAKES_REGISTRY_PATH}:`, err);
-    }
-}
-/** `*.example.com` → `.example.com` — the suffix the resolver matches. */
+// The SDK owns desired DNS state; the platform owns serving and persistence.
+const SERVICE_DNS = new ServiceDns();
+const SERVICE_OPERATIONS = new ServiceOperations();
+const TLS_OPERATIONS = new ServiceOperations();
 /** A service container's IP on spectest-net. `null` if the container isn't
  *  up or isn't attached to the network yet. */
 async function serviceContainerIp(name) {
@@ -2190,44 +2165,25 @@ async function proxyUpstreamHost(service) {
 async function resolveDnsTarget(target) {
     if ("ingress" in target)
         return bridgeGatewayIp();
-    const ip = await serviceContainerIp(target.service);
+    const ip = SERVICE_DNS.address(target.service);
     if (!ip) {
         throw new Error(`dnsName target service ${JSON.stringify(target.service)} has no IP on ${NETWORK_NAME} (is it a running service?)`);
     }
     return ip;
 }
-/**
- * Seed REGISTRY from the static lowered decls and write it. Run twice per
- * /bootstrap: once from startIngress (`servicesUp: false`) so ingress
- * hostnames answer during container startup, then once after every
- * container is up (`servicesUp: true`) so service-targeted wildcards (e.g.
- * k3s `ingressDomains`) can resolve their container IPs. The post-container
- * pass is what's captured into the warm template.
- */
-async function seedNamesRegistry(opts) {
+/** Reserve all declared names before containers start. Each runContainer
+ * publishes its IP before readiness/setup; there is no destructive final reseed. */
+async function seedNamesRegistry() {
     const gw = await bridgeGatewayIp();
-    REGISTRY.hosts = {};
-    REGISTRY.wildcards = [];
-    for (const h of LOWERED.ingressHosts)
-        REGISTRY.hosts[h] = gw;
-    for (const w of LOWERED.wildcards) {
-        if ("ingress" in w.target) {
-            REGISTRY.wildcards.push({ suffix: wildcardSuffix(w.pattern), ip: gw });
-            continue;
-        }
-        // Service target — only resolvable once the container has an IP.
-        if (!opts.servicesUp)
-            continue;
-        const ip = await serviceContainerIp(w.target.service);
-        if (ip) {
-            REGISTRY.wildcards.push({ suffix: wildcardSuffix(w.pattern), ip });
-        }
-        else {
-            // eslint-disable-next-line no-console
-            console.warn(`[names] wildcard ${w.pattern}: service ${JSON.stringify(w.target.service)} has no IP on ${NETWORK_NAME}`);
-        }
-    }
-    await writeRegistry();
+    const services = namedServices(requireLoaded().project.environment).map(svc => ({
+        name: svc.name, aliases: LOWERED.aliasesByService[svc.name] ?? [],
+    }));
+    const bindings = [
+        ...LOWERED.ingressHosts.map(name => ({ name, target: { ip: gw } })),
+        ...LOWERED.wildcards.map(w => ({ name: w.pattern,
+            target: "ingress" in w.target ? { ip: gw } : { service: w.target.service } })),
+    ];
+    await SERVICE_DNS.reset(services, bindings);
 }
 /**
  * The live interceptors (`ctx.intercept`). Module memory, so they fork with
@@ -2399,9 +2355,8 @@ function registerInterceptor(target, description, handler) {
  * Register a hostname at runtime — the implementation behind `ctx.dnsName`.
  * Validates via the same `dnsName` primitive the static path uses, resolves
  * the target to an IP, and updates + persists the registry. Exact names go
- * in `hosts`; `*.suffix` wildcards in `wildcards`. The resolver re-reads on
- * the next query (it watches the file's mtime), so the name is live
- * immediately — answered for VM-host/test/browser code and for peer
+ * in `hosts`; `*.suffix` wildcards in `wildcards`. The resolver acknowledges
+ * activation before this returns, so the name is live immediately — answered for VM-host/test/browser code and for peer
  * containers (Docker forwards unknown names to the host resolver). It does
  * NOT land in any container's /etc/hosts.
  */
@@ -2410,15 +2365,7 @@ async function registerDnsName(hostname, target) {
     // Reuse the primitive purely for validation + lowercasing.
     const decl = makeDnsDecl(hostname, target);
     const ip = await resolveDnsTarget(target);
-    if (isWildcard(decl.hostname)) {
-        const suffix = wildcardSuffix(decl.hostname);
-        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
-        REGISTRY.wildcards.push({ suffix, ip });
-    }
-    else {
-        REGISTRY.hosts[decl.hostname] = ip;
-    }
-    await writeRegistry();
+    await SERVICE_DNS.bind(decl.hostname, "service" in target ? { service: target.service } : { ip });
     recordEnv({ op: "dnsName", hostname: decl.hostname, ip, durationMs: 0 }, resv);
 }
 /**
@@ -2480,7 +2427,10 @@ function specToNamedService(spec) {
  *  Prepares the image (pulling on first use through the host cache), runs
  *  the container on spectest-net, and waits for its readyCheck. Returns the
  *  container's name + IP. */
-async function startRuntimeService(spec) {
+function startRuntimeService(spec) {
+    return SERVICE_OPERATIONS.run(spec.name, () => startRuntimeServiceUnlocked(spec));
+}
+async function startRuntimeServiceUnlocked(spec) {
     if (!spec.name || spec.name.length === 0) {
         throw new Error("startService: `name` is required");
     }
@@ -2499,14 +2449,14 @@ async function startRuntimeService(spec) {
             ...(await ensureCoverage(svc)),
         ];
         await runContainer(svc, tag, flags, aliases);
+        RUNTIME_SERVICES.set(svc.name, svc);
         await waitForReady(svc);
-        const ip = (await serviceContainerIp(svc.name)) ?? "";
+        const ip = SERVICE_DNS.address(svc.name);
         // `tls` is the runtime twin of a boot service's: stand up a
         // TLS-terminating reverse proxy at https://<hostname>/ → this container.
         for (const entry of svc.tls ?? []) {
             await bindRuntimeTls(entry.hostname, svc.name, entry.port, entry.http2, entry.cors);
         }
-        RUNTIME_SERVICES.set(svc.name, svc);
         recordEnv({
             op: "startService",
             service: svc.name,
@@ -2529,10 +2479,15 @@ async function startRuntimeService(spec) {
 }
 /** Implementation behind `ctx.stopService`. Removes the container and drops
  *  it from the runtime registry. No-op (rc ignored) if it's already gone. */
-async function stopRuntimeService(name) {
+function stopRuntimeService(name) {
+    return SERVICE_OPERATIONS.run(name, () => stopRuntimeServiceUnlocked(name));
+}
+async function stopRuntimeServiceUnlocked(name) {
     const t0 = Date.now();
     const resv = reserveEvent();
     const svc = RUNTIME_SERVICES.get(name);
+    await SERVICE_DNS.service(name, null);
+    PROXY_IP_CACHE.delete(name);
     // Freeze log production before reading, while Docker still owns the logs.
     // Keep force-stop semantics; removing first destroys the only copy.
     await docker(["kill", name], 30_000);
@@ -2545,7 +2500,7 @@ async function stopRuntimeService(name) {
     await docker(["rm", "-f", name], 30_000);
     RUNTIME_SERVICES.delete(name);
     for (const entry of svc?.tls ?? [])
-        await unbindRuntimeTls(entry.hostname);
+        await unbindRuntimeTls(entry.hostname, name);
     recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
 }
 /** The runtime environment-control handle handed to fakes (3rd handler arg /
@@ -2835,10 +2790,6 @@ async function bootstrapInner(prepared, identity) {
         }
     });
     await ensureStickyBuildHeadroom();
-    // Containers now have IPs — re-seed so service-targeted wildcards (e.g.
-    // k3s ingressDomains → the cluster container) resolve. Captured into the
-    // warm template, so warm starts inherit the resolved entries.
-    await seedNamesRegistry({ servicesUp: true });
     // Browser pre-warm DISABLED (2026-06-08). We used to pre-open one view
     // into the pool (browser.ts VIEW_POOL) here so every fork inherited a
     // live renderer and the first ctx.browser() skipped the ~1.2-1.5s spawn.

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

@@ -0,0 +1,23 @@
+export declare const DNS_SOCKET: string;
+export declare const DNS_REGISTRY_PATH: string;
+export declare const MAX_REGISTRY_BYTES: number;
+export interface DnsRegistry {
+    version: 1;
+    /** Opaque transaction ID, echoed in the acknowledgement. */
+    generation: string;
+    /** null reserves an unavailable name: it must never escape upstream. */
+    hosts: Record<string, string | null>;
+    wildcards: Array<{
+        suffix: string;
+        ip: string | null;
+    }>;
+}
+export declare function parseDnsRegistry(text: string): DnsRegistry;
+/** Compile once per update. undefined = unknown; null = owned but unavailable. */
+export declare function compileDnsRegistry(doc: DnsRegistry): (name: string) => string | null | undefined;
+/** Restore before binding DNS. A corrupt persisted registry is fatal, because
+ * silently forgetting owned domains could send fake traffic to real services. */
+export declare function serveDnsRegistry(activate: (doc: DnsRegistry) => void): Promise<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>>;
+/** Unix HTTP bypasses the SDK's instrumented fetch. A missing platform feature
+ * fails bootstrap explicitly; never silently switch back to discovery. */
+export declare function publishDnsRegistry(doc: DnsRegistry, socketPath?: string): Promise<void>;

package/dist/harness/dns-registry.js

@@ -0,0 +1,129 @@
+/** Platform/SDK DNS control protocol. The platform persists and activates each
+ * complete registry before acknowledging it. No project code runs in DNS. */
+import { isIPv4 } from "node:net";
+import { createServer, request } from "node:http";
+import { mkdir, readFile, rename, rm, writeFile, chmod } from "node:fs/promises";
+import { dirname } from "node:path";
+export const DNS_SOCKET = process.env.SPECTEST_DNS_SOCKET ?? "/run/spectest-dns.sock";
+export const DNS_REGISTRY_PATH = process.env.SPECTEST_DNS_REGISTRY ?? "/run/spectest-dns.json";
+export const MAX_REGISTRY_BYTES = 4 * 1024 * 1024;
+function validName(name) {
+    return name.length > 0 && name.length <= 253 && name === name.toLowerCase() &&
+        name.split(".").every(label => /^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/.test(label));
+}
+export function parseDnsRegistry(text) {
+    if (Buffer.byteLength(text) > MAX_REGISTRY_BYTES)
+        throw new Error("DNS registry too large");
+    const doc = JSON.parse(text);
+    if (!doc || doc.version !== 1 || typeof doc.generation !== "string" || !doc.generation.length || doc.generation.length > 128 ||
+        !doc.hosts || typeof doc.hosts !== "object" || Array.isArray(doc.hosts) || !Array.isArray(doc.wildcards))
+        throw new Error("Unsupported or malformed DNS registry (expected version 1)");
+    const address = (ip) => ip === null || (typeof ip === "string" && isIPv4(ip));
+    for (const [name, ip] of Object.entries(doc.hosts))
+        if (!validName(name) || !address(ip))
+            throw new Error(`Invalid DNS host: ${name}`);
+    const suffixes = new Set();
+    for (const w of doc.wildcards) {
+        if (!w || typeof w.suffix !== "string" || !w.suffix.startsWith(".") || !validName(w.suffix.slice(1)) || !address(w.ip) || suffixes.has(w.suffix))
+            throw new Error("Invalid or duplicate DNS wildcard");
+        suffixes.add(w.suffix);
+    }
+    return { version: 1, generation: doc.generation, hosts: doc.hosts, wildcards: doc.wildcards };
+}
+/** Compile once per update. undefined = unknown; null = owned but unavailable. */
+export function compileDnsRegistry(doc) {
+    const hosts = new Map(Object.entries(doc.hosts));
+    const wildcards = new Map(doc.wildcards.map(w => [w.suffix, w.ip]));
+    return name => {
+        if (hosts.has(name))
+            return hosts.get(name);
+        for (let i = name.indexOf("."); i !== -1; i = name.indexOf(".", i + 1)) {
+            const suffix = name.slice(i);
+            if (wildcards.has(suffix))
+                return wildcards.get(suffix);
+        }
+        return undefined;
+    };
+}
+/** Restore before binding DNS. A corrupt persisted registry is fatal, because
+ * silently forgetting owned domains could send fake traffic to real services. */
+export async function serveDnsRegistry(activate) {
+    try {
+        activate(parseDnsRegistry(await readFile(DNS_REGISTRY_PATH, "utf8")));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await mkdir(dirname(DNS_SOCKET), { recursive: true });
+    await rm(DNS_SOCKET, { force: true });
+    let pending = Promise.resolve();
+    const server = createServer(async (req, res) => {
+        if (req.method !== "PUT" || req.url !== "/v1/registry") {
+            res.writeHead(404).end();
+            return;
+        }
+        try {
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > MAX_REGISTRY_BYTES) {
+                    res.writeHead(413).end();
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+            const doc = parseDnsRegistry(Buffer.concat(chunks).toString("utf8"));
+            const update = pending.then(async () => {
+                await mkdir(dirname(DNS_REGISTRY_PATH), { recursive: true });
+                const tmp = `${DNS_REGISTRY_PATH}.tmp`;
+                await writeFile(tmp, JSON.stringify(doc), { mode: 0o600 });
+                await rename(tmp, DNS_REGISTRY_PATH);
+                activate(doc);
+            });
+            pending = update.catch(() => { });
+            await update;
+            res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ version: 1, generation: doc.generation }));
+        }
+        catch (error) {
+            res.writeHead(400, { "content-type": "text/plain" }).end(String(error));
+        }
+    });
+    server.requestTimeout = 10_000;
+    await new Promise((resolve, reject) => { server.once("error", reject); server.listen(DNS_SOCKET, resolve); });
+    await chmod(DNS_SOCKET, 0o600);
+    return server;
+}
+/** Unix HTTP bypasses the SDK's instrumented fetch. A missing platform feature
+ * fails bootstrap explicitly; never silently switch back to discovery. */
+export async function publishDnsRegistry(doc, socketPath = DNS_SOCKET) {
+    const body = JSON.stringify(doc);
+    parseDnsRegistry(body);
+    await new Promise((resolve, reject) => {
+        const req = request({ socketPath, method: "PUT", path: "/v1/registry", agent: false,
+            headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body) } }, res => {
+            let text = "";
+            res.setEncoding("utf8");
+            res.on("data", chunk => { text += chunk; });
+            res.on("error", reject);
+            res.on("end", () => {
+                try {
+                    if (res.statusCode !== 200)
+                        throw new Error(`DNS update rejected (${res.statusCode}): ${text}`);
+                    const ack = JSON.parse(text);
+                    if (ack.version !== 1 || ack.generation !== doc.generation)
+                        throw new Error("DNS acknowledgement mismatch");
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        const timer = setTimeout(() => req.destroy(new Error("DNS registry acknowledgement timed out")), 10_000);
+        req.on("close", () => clearTimeout(timer));
+        req.on("error", error => reject(new Error(`Cannot publish DNS registry; this SDK requires a platform with DNS registry v1: ${error.message}`)));
+        req.end(body);
+    });
+}

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

@@ -1,22 +1,7 @@
 /**
- * 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.
+ * Legacy names-file format used by SDKs before 0.131.20. The platform retains
+ * its lookup semantics for pinned SDKs that do not publish a complete registry.
+ * New SDKs use dns-registry.ts (control protocol) and service-dns.ts (ownership).
  */
 export interface RegistryDoc {
     /** Exact name → IP. */

package/dist/harness/names-registry.js

@@ -1,22 +1,7 @@
 /**
- * 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.
+ * Legacy names-file format used by SDKs before 0.131.20. The platform retains
+ * its lookup semantics for pinned SDKs that do not publish a complete registry.
+ * New SDKs use dns-registry.ts (control protocol) and service-dns.ts (ownership).
  */
 export const EMPTY_REGISTRY = { hosts: {}, wildcards: [] };
 /** Serialise for the resolver. */

package/dist/harness/service-dns.d.ts

@@ -0,0 +1,35 @@
+import { type DnsRegistry } from "./dns-registry.js";
+export type NameTarget = {
+    service: string;
+} | {
+    ip: string | null;
+};
+/** SDK-owned desired state. Updates are serialized and publish the whole view.
+ * Service bindings retain their target, so replacement IPs and stops also
+ * update ctx.dnsName aliases. State and the publication queue fork with the VM. */
+export declare class ServiceDns {
+    private publish;
+    private services;
+    private bindings;
+    private pending;
+    constructor(publish?: (doc: DnsRegistry) => Promise<void>);
+    private update;
+    private document;
+    address(name: string): string | null;
+    reset(services: Array<{
+        name: string;
+        aliases: string[];
+    }>, bindings: Array<{
+        name: string;
+        target: NameTarget;
+    }>): Promise<void>;
+    service(name: string, ip: string | null, aliases?: string[]): Promise<void>;
+    bind(name: string, target: NameTarget, owner?: string): Promise<void>;
+    retire(name: string, owner: string): Promise<void>;
+}
+/** Serialize same-name start/stop operations, while different services can
+ * start concurrently. Prevents stale teardown deleting a replacement. */
+export declare class ServiceOperations {
+    private pending;
+    run<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/harness/service-dns.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { publishDnsRegistry, parseDnsRegistry } from "./dns-registry.js";
+/** SDK-owned desired state. Updates are serialized and publish the whole view.
+ * Service bindings retain their target, so replacement IPs and stops also
+ * update ctx.dnsName aliases. State and the publication queue fork with the VM. */
+export class ServiceDns {
+    publish;
+    services = new Map();
+    bindings = new Map();
+    pending = Promise.resolve();
+    constructor(publish = publishDnsRegistry) {
+        this.publish = publish;
+    }
+    update(change) {
+        const next = this.pending.then(async () => {
+            const services = this.services;
+            const bindings = this.bindings;
+            this.services = new Map(services);
+            this.bindings = new Map(bindings);
+            let doc;
+            try {
+                change();
+                doc = parseDnsRegistry(JSON.stringify(this.document()));
+            }
+            catch (error) {
+                this.services = services;
+                this.bindings = bindings;
+                throw error;
+            }
+            await this.publish(doc);
+        });
+        // Preserve desired state after failure; the caller gets an error and the
+        // next full publication repairs an uncertain/lost acknowledgement.
+        this.pending = next.catch(() => { });
+        return next;
+    }
+    document() {
+        const hosts = Object.create(null);
+        const suffixes = new Map();
+        const put = (name, ip) => {
+            if (name.startsWith("*."))
+                suffixes.set(name.slice(1), ip);
+            else
+                hosts[name] = ip;
+        };
+        for (const [name, svc] of this.services)
+            for (const alias of [name, `${name}.internal`, ...svc.aliases])
+                put(alias.toLowerCase(), svc.ip);
+        for (const [name, { target }] of this.bindings)
+            put(name, "service" in target ? this.services.get(target.service)?.ip ?? null : target.ip);
+        return { version: 1, generation: randomUUID(), hosts, wildcards: [...suffixes].map(([suffix, ip]) => ({ suffix, ip })) };
+    }
+    address(name) { return this.services.get(name)?.ip ?? null; }
+    reset(services, bindings) {
+        return this.update(() => {
+            this.services = new Map(services.map(svc => [svc.name, { aliases: svc.aliases, ip: null }]));
+            this.bindings = new Map(bindings.map(b => [b.name.toLowerCase(), { target: b.target, owner: "static" }]));
+        });
+    }
+    service(name, ip, aliases) {
+        return this.update(() => {
+            const previous = this.services.get(name);
+            // Retire removed aliases as owned/unavailable as well.
+            for (const old of previous?.aliases ?? []) {
+                if (aliases && !aliases.includes(old) && !this.bindings.has(old))
+                    this.bindings.set(old, { target: { ip: null }, owner: `retired:${name}` });
+            }
+            for (const alias of aliases ?? []) {
+                if (this.bindings.get(alias)?.owner === `retired:${name}`)
+                    this.bindings.delete(alias);
+            }
+            this.services.set(name, { ip, aliases: aliases ?? previous?.aliases ?? [] });
+        });
+    }
+    bind(name, target, owner = "explicit") {
+        return this.update(() => { this.bindings.set(name.toLowerCase(), { target, owner }); });
+    }
+    retire(name, owner) {
+        return this.update(() => {
+            const binding = this.bindings.get(name.toLowerCase());
+            if (binding?.owner === owner)
+                this.bindings.set(name.toLowerCase(), { target: { ip: null }, owner });
+        });
+    }
+}
+/** Serialize same-name start/stop operations, while different services can
+ * start concurrently. Prevents stale teardown deleting a replacement. */
+export class ServiceOperations {
+    pending = new Map();
+    run(name, fn) {
+        const next = (this.pending.get(name) ?? Promise.resolve()).catch(() => { }).then(fn);
+        this.pending.set(name, next);
+        void next.finally(() => { if (this.pending.get(name) === next)
+            this.pending.delete(name); }).catch(() => { });
+        return next;
+    }
+}