@specific.dev/spectest 0.131.18 → 0.131.20

package/src/browser-surface.test.ts

@@ -2,10 +2,13 @@ import { expect, test } from "bun:test";
 import { chromium } from "playwright-core";
 import { awaitBrowserSurface, captureBrowserScreenshot, reduceBrowserSurfaces } from "./browser-surface.js";
 
-const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? undefined;
-for (const mobile of [false, true]) {
-  test.skipIf(!executablePath)(`reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
-    const browser = await chromium.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+const engines = {
+  chromium: Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"),
+  shell: Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"),
+};
+for (const [engine, executablePath] of Object.entries(engines)) for (const mobile of [false, true]) {
+  test.skipIf(!executablePath)(`${engine}: reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
+    const browser = await chromium.launch({ executablePath: executablePath!, headless: true, args: ["--no-sandbox"] });
     const width = mobile ? 393 : 1280, height = mobile ? 852 : 720, dpr = mobile ? 3 : 1;
     try {
       const context = await browser.newContext({ viewport: { width, height }, isMobile: mobile, hasTouch: mobile, deviceScaleFactor: dpr });

package/src/browser-timezone.test.ts

@@ -21,7 +21,7 @@ async function settings(browser: Browser): Promise<Settings> {
   return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
 }
 
-describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("browser timezone and locale", () => {
+describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser timezone and locale", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => {
     server = Bun.serve({

package/src/browser.ts

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// driving the guest's Headless Shell (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -463,7 +463,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
 
-// Default sessions share one Chromium per daemon, launched lazily and kept
+// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -481,19 +481,18 @@ const VIEW_CLEANUPS = new WeakMap<BrowserContext, () => Promise<void>>();
 // the page only — cookies survived and the next session was still
 // authenticated.
 
-function chromiumPath(): string {
-  return (
-    Bun.which("chromium") ??
-    Bun.which("chromium-browser") ??
-    Bun.which("google-chrome") ??
-    "/usr/bin/chromium"
-  );
+function browserExecutable(): string {
+  const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+  if (!executable) {
+    throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+  }
+  return executable;
 }
 
 async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
   if (PW_BROWSER?.isConnected()) return PW_BROWSER;
   PW_BROWSER = await chromium.launch({
-    executablePath: chromiumPath(),
+    executablePath: browserExecutable(),
     headless: true,
     args: CHROME_ARGV,
   });
@@ -531,7 +530,7 @@ async function newViewContext(
   let browser: PlaywrightBrowser | undefined;
   try {
     browser = fixture ? await chromium.launch({
-      executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+      executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
     const context = await browser.newContext({
       ...(device

package/src/daemon.ts

@@ -131,7 +131,7 @@ import {
   runInstrumented,
   runUninstrumented,
 } from "./harness/instrumentation-scope.js";
-import { encodeRegistry } from "./harness/names-registry.js";
+import { ServiceDns, ServiceOperations, type NameTarget } from "./harness/service-dns.js";
 import {
   InterceptRegistry,
   parseTarget,
@@ -164,7 +164,6 @@ import {
   clearTables,
   emptyTables,
   planBind,
-  registryTarget,
   routesFor,
   unbindRoute,
   type Route as IngressRoute,
@@ -1543,7 +1542,9 @@ async function runContainer(
   extraAliases: string[] = [],
 ): Promise<void> {
   // Preserve the previous incarnation before the name is reused.
-  if (RUNTIME_SERVICES.has(svc.name)) await stopRuntimeService(svc.name);
+  if (RUNTIME_SERVICES.has(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`);
@@ -1572,6 +1573,10 @@ async function runContainer(
       `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);
 }
 
 /** What a readiness probe saw. `detail` is what the plain boolean used to
@@ -1762,15 +1767,13 @@ async function withContainerPostMortem(name: string, err: unknown): Promise<unkn
 //     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;
 
 /** Runtime record for one configured fake. */
@@ -1971,9 +1974,7 @@ async function startIngress(): Promise<void> {
     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();
@@ -2061,9 +2062,9 @@ async function startIngress(): Promise<void> {
 
   // 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
@@ -2199,7 +2200,11 @@ function certCovers(hostname: string): boolean {
  * 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: string, service: string, port: number, http2?: boolean, cors?: CorsMode): Promise<void> {
+function bindRuntimeTls(hostname: string, service: string, port: number, http2?: boolean, cors?: CorsMode): Promise<void> {
+  return TLS_OPERATIONS.run(hostname.toLowerCase(), () => bindRuntimeTlsUnlocked(hostname, service, port, http2, cors));
+}
+
+async function bindRuntimeTlsUnlocked(hostname: string, service: string, port: number, http2?: boolean, cors?: CorsMode): Promise<void> {
   // 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 });
@@ -2238,14 +2243,7 @@ async function bindRuntimeTls(hostname: string, service: string, port: number, h
   // 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}`);
 }
@@ -2256,18 +2254,16 @@ async function bindRuntimeTls(hostname: string, service: string, port: number, h
  * left in the SNI table — harmless without a route, and removing it would
  * mean an avoidable :443 rebind.
  */
-async function unbindRuntimeTls(hostname: string): Promise<void> {
+function unbindRuntimeTls(hostname: string, service: string): Promise<void> {
+  return TLS_OPERATIONS.run(hostname.toLowerCase(), () => unbindRuntimeTlsUnlocked(hostname, service));
+}
+
+async function unbindRuntimeTlsUnlocked(hostname: string, service: string): Promise<void> {
   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. */
@@ -2559,34 +2555,11 @@ async function proxyToService(
   );
 }
 
-/**
- * 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: Record<string, string>;
-  wildcards: Array<{ suffix: string; ip: string }>;
-} = { hosts: {}, wildcards: [] };
-
-async function writeRegistry(): Promise<void> {
-  // 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);
-  }
-}
+// 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();
 
-/** `*.example.com` → `.example.com` — the suffix the resolver matches. */
 /** 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: string): Promise<string | null> {
@@ -2631,7 +2604,7 @@ async function proxyUpstreamHost(service: string): Promise<string> {
  *  → that container's IP. Throws if a service target has no IP yet. */
 async function resolveDnsTarget(target: DnsTarget): Promise<string> {
   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?)`,
@@ -2640,37 +2613,19 @@ async function resolveDnsTarget(target: DnsTarget): Promise<string> {
   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: { servicesUp: boolean }): Promise<void> {
+/** Reserve all declared names before containers start. Each runContainer
+ * publishes its IP before readiness/setup; there is no destructive final reseed. */
+async function seedNamesRegistry(): Promise<void> {
   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: Array<{ name: string; target: NameTarget }> = [
+    ...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);
 }
 
 /**
@@ -2862,9 +2817,8 @@ function registerInterceptor(
  * 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.
  */
@@ -2873,14 +2827,7 @@ async function registerDnsName(hostname: string, target: DnsTarget): Promise<voi
   // 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);
 }
 
@@ -2952,7 +2899,11 @@ function specToNamedService(spec: RuntimeServiceSpec): NamedService {
  *  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: RuntimeServiceSpec): Promise<RuntimeServiceHandle> {
+function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle> {
+  return SERVICE_OPERATIONS.run(spec.name, () => startRuntimeServiceUnlocked(spec));
+}
+
+async function startRuntimeServiceUnlocked(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle> {
   if (!spec.name || spec.name.length === 0) {
     throw new Error("startService: `name` is required");
   }
@@ -2971,14 +2922,14 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
       ...(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,
@@ -3001,10 +2952,16 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
 
 /** 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: string): Promise<void> {
+function stopRuntimeService(name: string): Promise<void> {
+  return SERVICE_OPERATIONS.run(name, () => stopRuntimeServiceUnlocked(name));
+}
+
+async function stopRuntimeServiceUnlocked(name: string): Promise<void> {
   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);
@@ -3016,7 +2973,7 @@ async function stopRuntimeService(name: string): Promise<void> {
   }
   await docker(["rm", "-f", name], 30_000);
   RUNTIME_SERVICES.delete(name);
-  for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname);
+  for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname, name);
   recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
 }
 
@@ -3329,11 +3286,6 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
 
   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/src/harness/dns-registry.ts

@@ -0,0 +1,121 @@
+/** 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;
+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 }>;
+}
+
+function validName(name: string): boolean {
+  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: string): DnsRegistry {
+  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: unknown) => 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<string>();
+  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: DnsRegistry): (name: string) => string | null | undefined {
+  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: (doc: DnsRegistry) => void) {
+  try { activate(parseDnsRegistry(await readFile(DNS_REGISTRY_PATH, "utf8"))); }
+  catch (error) { if ((error as NodeJS.ErrnoException).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: Buffer[] = [];
+      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<void>((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: DnsRegistry, socketPath = DNS_SOCKET): Promise<void> {
+  const body = JSON.stringify(doc);
+  parseDnsRegistry(body);
+  await new Promise<void>((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/src/harness/names-registry.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 {

package/src/harness/service-dns.test.ts

@@ -0,0 +1,94 @@
+import { expect, test } from "bun:test";
+import { ServiceDns, ServiceOperations } from "./service-dns";
+import { compileDnsRegistry, parseDnsRegistry, type DnsRegistry } from "./dns-registry";
+
+function fixture() {
+  const docs: DnsRegistry[] = [];
+  const dns = new ServiceDns(async doc => { docs.push(parseDnsRegistry(JSON.stringify(doc))); });
+  return { dns, docs, lookup: (name: string) => compileDnsRegistry(docs.at(-1)!)(name) };
+}
+
+test("reserve startup names, publish before setup, retain setup registrations and follow service recreation", async () => {
+  const f = fixture();
+  await f.dns.reset([{ name: "api", aliases: ["api.example.com"] }, { name: "db", aliases: [] }], [
+    { name: "*.cluster.test", target: { service: "api" } },
+    { name: "fake.example.com", target: { ip: "10.0.0.1" } },
+  ]);
+  expect(f.lookup("api.internal")).toBeNull();
+  expect(f.lookup("api.example.com")).toBeNull();
+  expect(f.lookup("app.cluster.test")).toBeNull();
+  await f.dns.service("api", "10.0.0.2");
+  await f.dns.bind("setup.test", { service: "api" });
+  await f.dns.service("db", "10.0.0.3");
+  expect(f.lookup("setup.test")).toBe("10.0.0.2");
+  expect(f.lookup("app.cluster.test")).toBe("10.0.0.2");
+  await f.dns.service("api", null);
+  expect(f.lookup("setup.test")).toBeNull();
+  expect(f.lookup("api.example.com")).toBeNull();
+  await f.dns.service("api", "10.0.0.4");
+  expect(f.lookup("setup.test")).toBe("10.0.0.4");
+  expect(f.lookup("app.cluster.test")).toBe("10.0.0.4");
+  expect(f.lookup("fake.example.com")).toBe("10.0.0.1");
+});
+
+test("explicit names beat aliases; retiring old ownership cannot delete a replacement", async () => {
+  const f = fixture();
+  await f.dns.service("api", "10.0.0.2", ["shared.test", "old.test"]);
+  await f.dns.bind("shared.test", { ip: "10.0.0.1" }, "tls:api");
+  await f.dns.bind("shared.test", { ip: "10.0.0.3" }, "tls:other");
+  await f.dns.retire("shared.test", "tls:api");
+  expect(f.lookup("shared.test")).toBe("10.0.0.3");
+  await f.dns.retire("shared.test", "tls:other");
+  expect(f.lookup("shared.test")).toBeNull();
+  await f.dns.service("api", "10.0.0.4", ["new.test"]);
+  expect(f.lookup("old.test")).toBeNull();
+  expect(f.lookup("new.test")).toBe("10.0.0.4");
+  await f.dns.service("api", "10.0.0.5", ["old.test"]);
+  expect(f.lookup("old.test")).toBe("10.0.0.5");
+});
+
+test("concurrent publications wait for acknowledgement, reject failures and repair with a full view", async () => {
+  const docs: DnsRegistry[] = [];
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  let first = true;
+  const dns = new ServiceDns(async doc => {
+    docs.push(doc);
+    if (first) { first = false; await gate; throw new Error("lost acknowledgement"); }
+  });
+  const a = dns.service("a", "10.0.0.2");
+  const failed = a.catch(error => error);
+  const b = dns.service("b", "10.0.0.3");
+  await Bun.sleep(0);
+  expect(docs).toHaveLength(1);
+  release(); expect((await failed).message).toBe("lost acknowledgement"); await b;
+  expect(docs).toHaveLength(2);
+  expect(docs[1].hosts).toMatchObject({ a: "10.0.0.2", b: "10.0.0.3" });
+  expect(docs[0].hosts.b).toBeUndefined();
+  expect(docs[1].generation).not.toBe(docs[0].generation);
+});
+
+test("same-service operations serialize through failure without blocking independent services", async () => {
+  const ops = new ServiceOperations();
+  const events: string[] = [];
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  const first = ops.run("api", async () => { events.push("start"); await gate; throw new Error("failed start"); });
+  const failed = first.catch(error => error);
+  const stopped = ops.run("api", async () => { events.push("stop"); });
+  await ops.run("db", async () => { events.push("db"); });
+  expect(events).toEqual(["start", "db"]);
+  release(); expect((await failed).message).toBe("failed start"); await stopped;
+  expect(events).toEqual(["start", "db", "stop"]);
+});
+
+
+test("invalid desired state cannot poison later unrelated updates", async () => {
+  const f = fixture();
+  await f.dns.service("api", "10.0.0.2");
+  await expect(f.dns.service("invalid name", "10.0.0.3")).rejects.toThrow("Invalid DNS host");
+  await f.dns.service("db", "10.0.0.4");
+  expect(f.lookup("api")).toBe("10.0.0.2");
+  expect(f.lookup("db")).toBe("10.0.0.4");
+  expect(f.docs.at(-1)?.hosts["invalid name"]).toBeUndefined();
+});