@specific.dev/spectest 0.92.0 → 0.92.1

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp } from "./android.js";
@@ -39,7 +40,7 @@ import { isDesktopApp } from "./desktop.js";
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
-import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { startServices } from "./harness/service-graph.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
@@ -1453,29 +1454,6 @@ async function withContainerPostMortem(name, err) {
         return err;
     }
 }
-/** Validate the `dependsOn` graph and return the name→service map used to
- *  walk it. Rules live in `harness/service-graph.ts`. */
-function validateServiceGraph(services) {
-    return validateGraph(services);
-}
-async function startServices(services, startOne) {
-    const byName = validateServiceGraph(services);
-    const started = new Map();
-    const start = (svc) => {
-        const existing = started.get(svc.name);
-        if (existing)
-            return existing;
-        const p = (async () => {
-            await Promise.all((svc.dependsOn ?? [])
-                .filter((d) => byName.has(d))
-                .map((d) => start(byName.get(d))));
-            await startOne(svc);
-        })();
-        started.set(svc.name, p);
-        return p;
-    };
-    await Promise.all(services.map(start));
-}
 // ────────────────────────────────────────────────────────────────────────
 // Ingress — in-daemon HTTP/HTTPS listeners that route by Host header.
 //
@@ -1625,67 +1603,6 @@ function buildIngress(project) {
         });
     }
 }
-/**
- * Generate a leaf cert + key for one ingress route (fake or service
- * proxy), signed by the in-VM root CA at {CA_PATH}. SANs cover every
- * hostname the route answers to, so a client connecting with TLS
- * verifies cleanly regardless of which hostname it used. Shells out
- * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
- * bookworm ships 3.0.x).
- *
- * `label` is a short tag baked into the cert Subject CN and the temp
- * file names — only used for diagnostics, not for TLS verification.
- */
-async function generateHostCert(label, hostnames) {
-    const id = `spectest-host-${sanitizeSegment(label)}-${randomUUID().slice(0, 8)}`;
-    const keyPath = path.join("/tmp", `${id}.key`);
-    const crtPath = path.join("/tmp", `${id}.crt`);
-    const sans = hostnames.map((h) => `DNS:${h}`).join(",");
-    const args = [
-        "req",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        keyPath,
-        "-out",
-        crtPath,
-        "-x509",
-        "-CA",
-        CA_PATH,
-        "-CAkey",
-        CA_KEY_PATH,
-        "-days",
-        "3650",
-        "-subj",
-        `/CN=spectest-${label}`,
-        "-addext",
-        `subjectAltName=${sans}`,
-        "-addext",
-        "basicConstraints=CA:FALSE",
-        "-addext",
-        "extendedKeyUsage=serverAuth",
-        "-addext",
-        "keyUsage=digitalSignature,keyEncipherment",
-    ];
-    const r = await shx("openssl", args, 30_000);
-    if (r.code !== 0) {
-        throw new Error(`openssl req for ${label} failed (rc=${r.code}): ${r.stderr.trim() || r.stdout.trim()}`);
-    }
-    try {
-        const [cert, key] = await Promise.all([
-            fs.readFile(crtPath, "utf8"),
-            fs.readFile(keyPath, "utf8"),
-        ]);
-        return { cert, key };
-    }
-    finally {
-        await Promise.all([
-            fs.unlink(keyPath).catch(() => { }),
-            fs.unlink(crtPath).catch(() => { }),
-        ]);
-    }
-}
 /** Resolve the spectest-net bridge gateway IP — the address containers
  * use to reach the VM host. Asks dockerd via the docker CLI; cached for
  * the daemon's life because the network is recreated only on reload. */
@@ -1719,7 +1636,10 @@ async function bridgeGatewayIp() {
  * that don't pass through as primitives.
  */
 const NATIVE_FETCH = globalThis.fetch.bind(globalThis);
-/** Hop-by-hop headers per RFC 7230 §6.1 — never forwarded by a proxy. */
+/** Mint ingress and container certificates with the environment CA. */
+function generateHostCert(label, hostnames) {
+    return mintHostCert(label, hostnames, CA_PATH, CA_KEY_PATH);
+}
 async function startIngress() {
     const hasIngress = FAKES.size > 0 ||
         LOWERED.proxies.length > 0 ||
@@ -2942,10 +2862,14 @@ async function bootstrap(prepared) {
     // hook's — into the boot log, so GET /boot-log can explain a slow or
     // finished boot. Restored in the finally at the end.
     const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+    // One dispatcher for the whole bootstrap: service hooks run concurrently.
+    // Only each hook's async scope opts into wrapped fetch responses.
+    const restoreFetch = installFetchWrapper();
     try {
         return await bootstrapInner(prepared);
     }
     finally {
+        restoreFetch();
         restoreBootLog();
     }
 }
@@ -3111,22 +3035,28 @@ async function bootstrapInner(prepared, identity) {
         await waitForAll([...builds.map(task => prep.get(task.name)), (async () => {
                 if (svc.setup) {
                     progressService(svc.name, { status: "probing", detail: "running setup" });
-                    const helpers = await ensureHelpers(svc.name, svc);
+                    const fetchScope = createInstrumentationScope(false);
                     try {
-                        await svc.setup({
-                            name: svc.name,
-                            helpers,
-                            ...(await spectestContext({ service: svc.name, includeSelf: true })),
-                            ...{ [COMPONENT_RUNTIME]: {
-                                    images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name) })),
-                                    gateway: await bridgeGatewayIp(),
-                                    caBundle: await ensureCaBundle(),
-                                } },
+                        await runInstrumented(fetchScope, async () => {
+                            const helpers = await ensureHelpers(svc.name, svc);
+                            await svc.setup({
+                                name: svc.name,
+                                helpers,
+                                ...(await spectestContext({ service: svc.name, includeSelf: true })),
+                                ...{ [COMPONENT_RUNTIME]: {
+                                        images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name) })),
+                                        gateway: await bridgeGatewayIp(),
+                                        caBundle: await ensureCaBundle(),
+                                    } },
+                            });
                         });
                     }
                     catch (err) {
                         throw await withContainerPostMortem(svc.name, err);
                     }
+                    finally {
+                        fetchScope.active = false;
+                    }
                 }
             })()]);
         for (const task of builds)
@@ -4013,7 +3943,7 @@ async function spectestContext(scope = {}) {
         readProjectFileBytes: async (p) => new Uint8Array(await fs.readFile(resolveProjectPath(p))),
         exec: (service, command, opts) => componentExec(service, command, opts, execTimeoutMs),
         // Read `globalThis.fetch` at call time: the wrapper is installed for
-        // the duration of a test / eval / project setup, so a context built
+        // the duration of bootstrap / a test / eval / project setup, so a context built
         // before it lands still gets the wrapped one.
         fetch: ((input, init) => globalThis.fetch(input, init)),
         svc: handles,

package/dist/harness/certificate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generate a leaf cert + key for one ingress route (fake or service
+ * proxy), signed by the in-VM root CA. SANs cover every
+ * hostname the route answers to, so a client connecting with TLS
+ * verifies cleanly regardless of which hostname it used. Shells out
+ * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
+ * bookworm ships 3.0.x).
+ *
+ * `label` is a diagnostic tag baked into the cert Subject CN and the temp
+ * file names — only used for diagnostics, not for TLS verification.
+ */
+export declare function generateHostCert(label: string, hostnames: string[], caPath: string, caKeyPath: string): Promise<{
+    cert: string;
+    key: string;
+}>;

package/dist/harness/certificate.js

@@ -0,0 +1,67 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Generate a leaf cert + key for one ingress route (fake or service
+ * proxy), signed by the in-VM root CA. SANs cover every
+ * hostname the route answers to, so a client connecting with TLS
+ * verifies cleanly regardless of which hostname it used. Shells out
+ * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
+ * bookworm ships 3.0.x).
+ *
+ * `label` is a diagnostic tag baked into the cert Subject CN and the temp
+ * file names — only used for diagnostics, not for TLS verification.
+ */
+export async function generateHostCert(label, hostnames, caPath, caKeyPath) {
+    // CN is diagnostic only; SANs retain the full hostnames. Bound the label
+    // for both OpenSSL's 64-byte CN limit and filesystem component limits.
+    const commonName = `spectest-${label.replace(/[^a-zA-Z0-9.-]/g, "_").slice(0, 55)}`;
+    const id = `${commonName}-${randomUUID()}`;
+    const keyPath = path.join("/tmp", `${id}.key`);
+    const crtPath = path.join("/tmp", `${id}.crt`);
+    const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+    const args = [
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        keyPath,
+        "-out",
+        crtPath,
+        "-x509",
+        "-CA",
+        caPath,
+        "-CAkey",
+        caKeyPath,
+        "-days",
+        "3650",
+        "-subj",
+        `/CN=${commonName}`,
+        "-addext",
+        `subjectAltName=${sans}`,
+        "-addext",
+        "basicConstraints=CA:FALSE",
+        "-addext",
+        "extendedKeyUsage=serverAuth",
+        "-addext",
+        "keyUsage=digitalSignature,keyEncipherment",
+    ];
+    try {
+        await execFileAsync("openssl", args, { timeout: 30_000 });
+        const [cert, key] = await Promise.all([
+            fs.readFile(crtPath, "utf8"),
+            fs.readFile(keyPath, "utf8"),
+        ]);
+        return { cert, key };
+    }
+    finally {
+        await Promise.all([
+            fs.unlink(keyPath).catch(() => { }),
+            fs.unlink(crtPath).catch(() => { }),
+        ]);
+    }
+}

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

@@ -27,3 +27,6 @@ export declare function validateServiceGraph<T extends GraphNode>(services: read
  * graph is walkable at all.
  */
 export declare function topologicalOrder<T extends GraphNode>(services: readonly T[]): T[];
+/** Start each service after its dependencies finish setup. Drain all branches
+ * before reporting failure so teardown cannot race containers or hooks. */
+export declare function startServices<T extends GraphNode>(services: readonly T[], startOne: (svc: T) => Promise<void>): Promise<void>;

package/dist/harness/service-graph.js

@@ -1,12 +1,4 @@
-/**
- * The `dependsOn` graph: validation, and the traversal order bring-up
- * uses.
- *
- * Ported out of `daemon.ts`. Validation runs before anything starts, so
- * the DAG runner can assume a clean graph — an unknown dependency or a
- * cycle must be a clear error at load, not a container that never becomes
- * ready and eventually times out with no explanation.
- */
+import { waitForAll } from "./concurrency.js";
 /**
  * Check the graph and return the name→node map used to walk it.
  *
@@ -90,3 +82,21 @@ export function topologicalOrder(services) {
         visit(s.name);
     return out;
 }
+/** Start each service after its dependencies finish setup. Drain all branches
+ * before reporting failure so teardown cannot race containers or hooks. */
+export async function startServices(services, startOne) {
+    const byName = validateServiceGraph(services);
+    const started = new Map();
+    const start = (svc) => {
+        const existing = started.get(svc.name);
+        if (existing)
+            return existing;
+        const pending = (async () => {
+            await Promise.all((svc.dependsOn ?? []).map(name => start(byName.get(name))));
+            await startOne(svc);
+        })();
+        started.set(svc.name, pending);
+        return pending;
+    };
+    await waitForAll(services.map(start));
+}

package/dist/index.d.ts

@@ -590,11 +590,10 @@ export interface ServiceDefinition<H extends Record<string, any> = Record<string
  * the typecheck on any service declaring a hook, while the same literal
  * written inline passed. */
 export type ServicesMap = Record<string, ServiceDefinition<any>>;
-/** Awaited return type of a service's `helpers` factory, or `never` if
- * the service doesn't ship one. */
-type HelpersOf<D> = D extends {
-    helpers: (...args: any) => infer R;
-} ? Awaited<R> : never;
+/** Awaited return type of a service's helpers factory. Check key presence
+ * before removing optionality: annotations keep `helpers?`, while plain
+ * service literals with no factory must stay out of ctx.svc. */
+type HelpersOf<D> = "helpers" extends keyof D ? [NonNullable<D["helpers"]>] extends [never] ? never : NonNullable<D["helpers"]> extends (...args: any[]) => infer R ? Awaited<R> : never : never;
 /**
  * Per-service handles derived from a concrete services map. Only
  * services that ship a `helpers` factory appear here; `ctx.svc.<name>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.92.0",
+  "version": "0.92.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp, type AndroidRecording } from "./android.js";
@@ -89,7 +90,7 @@ import {
   serviceDockerignore as composeServiceDockerignore,
   unionDockerignore,
 } from "./harness/build-context.js";
-import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { startServices } from "./harness/service-graph.js";
 import {
   casesMetadata as catalogueCases,
   groupsMetadata as catalogueGroups,
@@ -1859,35 +1860,6 @@ async function withContainerPostMortem(name: string, err: unknown): Promise<unkn
   }
 }
 
-/** Validate the `dependsOn` graph and return the name→service map used to
- *  walk it. Rules live in `harness/service-graph.ts`. */
-function validateServiceGraph(services: NamedService[]): Map<string, NamedService> {
-  return validateGraph(services);
-}
-
-async function startServices(
-  services: NamedService[],
-  startOne: (svc: NamedService) => Promise<void>,
-): Promise<void> {
-  const byName = validateServiceGraph(services);
-  const started = new Map<string, Promise<void>>();
-  const start = (svc: NamedService): Promise<void> => {
-    const existing = started.get(svc.name);
-    if (existing) return existing;
-    const p = (async () => {
-      await Promise.all(
-        (svc.dependsOn ?? [])
-          .filter((d) => byName.has(d))
-          .map((d) => start(byName.get(d)!)),
-      );
-      await startOne(svc);
-    })();
-    started.set(svc.name, p);
-    return p;
-  };
-  await Promise.all(services.map(start));
-}
-
 // ────────────────────────────────────────────────────────────────────────
 // Ingress — in-daemon HTTP/HTTPS listeners that route by Host header.
 //
@@ -2057,72 +2029,6 @@ function buildIngress(project: Project): void {
   }
 }
 
-/**
- * Generate a leaf cert + key for one ingress route (fake or service
- * proxy), signed by the in-VM root CA at {CA_PATH}. SANs cover every
- * hostname the route answers to, so a client connecting with TLS
- * verifies cleanly regardless of which hostname it used. Shells out
- * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
- * bookworm ships 3.0.x).
- *
- * `label` is a short tag baked into the cert Subject CN and the temp
- * file names — only used for diagnostics, not for TLS verification.
- */
-async function generateHostCert(
-  label: string,
-  hostnames: string[],
-): Promise<{ cert: string; key: string }> {
-  const id = `spectest-host-${sanitizeSegment(label)}-${randomUUID().slice(0, 8)}`;
-  const keyPath = path.join("/tmp", `${id}.key`);
-  const crtPath = path.join("/tmp", `${id}.crt`);
-  const sans = hostnames.map((h) => `DNS:${h}`).join(",");
-  const args = [
-    "req",
-    "-newkey",
-    "rsa:2048",
-    "-nodes",
-    "-keyout",
-    keyPath,
-    "-out",
-    crtPath,
-    "-x509",
-    "-CA",
-    CA_PATH,
-    "-CAkey",
-    CA_KEY_PATH,
-    "-days",
-    "3650",
-    "-subj",
-    `/CN=spectest-${label}`,
-    "-addext",
-    `subjectAltName=${sans}`,
-    "-addext",
-    "basicConstraints=CA:FALSE",
-    "-addext",
-    "extendedKeyUsage=serverAuth",
-    "-addext",
-    "keyUsage=digitalSignature,keyEncipherment",
-  ];
-  const r = await shx("openssl", args, 30_000);
-  if (r.code !== 0) {
-    throw new Error(
-      `openssl req for ${label} failed (rc=${r.code}): ${r.stderr.trim() || r.stdout.trim()}`,
-    );
-  }
-  try {
-    const [cert, key] = await Promise.all([
-      fs.readFile(crtPath, "utf8"),
-      fs.readFile(keyPath, "utf8"),
-    ]);
-    return { cert, key };
-  } finally {
-    await Promise.all([
-      fs.unlink(keyPath).catch(() => {}),
-      fs.unlink(crtPath).catch(() => {}),
-    ]);
-  }
-}
-
 /** Resolve the spectest-net bridge gateway IP — the address containers
  * use to reach the VM host. Asks dockerd via the docker CLI; cached for
  * the daemon's life because the network is recreated only on reload. */
@@ -2165,7 +2071,11 @@ type Route = IngressRoute<FakeRuntime>;
  */
 const NATIVE_FETCH: typeof fetch = globalThis.fetch.bind(globalThis);
 
-/** Hop-by-hop headers per RFC 7230 §6.1 — never forwarded by a proxy. */
+/** Mint ingress and container certificates with the environment CA. */
+function generateHostCert(label: string, hostnames: string[]): Promise<{ cert: string; key: string }> {
+  return mintHostCert(label, hostnames, CA_PATH, CA_KEY_PATH);
+}
+
 async function startIngress(): Promise<void> {
   const hasIngress =
     FAKES.size > 0 ||
@@ -3519,9 +3429,13 @@ async function bootstrap(prepared?: PreparedImages): Promise<BootstrapTimings> {
   // hook's — into the boot log, so GET /boot-log can explain a slow or
   // finished boot. Restored in the finally at the end.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+  // One dispatcher for the whole bootstrap: service hooks run concurrently.
+  // Only each hook's async scope opts into wrapped fetch responses.
+  const restoreFetch = installFetchWrapper();
   try {
     return await bootstrapInner(prepared);
   } finally {
+    restoreFetch();
     restoreBootLog();
   }
 }
@@ -3695,20 +3609,25 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
     await waitForAll([...builds.map(task => prep.get(task.name)!), (async () => {
       if (svc.setup) {
         progressService(svc.name, { status: "probing", detail: "running setup" });
-        const helpers = await ensureHelpers(svc.name, svc);
+        const fetchScope = createInstrumentationScope(false);
         try {
-          await svc.setup({
-            name: svc.name,
-            helpers,
-            ...(await spectestContext({ service: svc.name, includeSelf: true })),
-            ...{ [COMPONENT_RUNTIME]: {
-              images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name)! })),
-              gateway: await bridgeGatewayIp(),
-              caBundle: await ensureCaBundle(),
-            } },
+          await runInstrumented(fetchScope, async () => {
+            const helpers = await ensureHelpers(svc.name, svc);
+            await svc.setup!({
+              name: svc.name,
+              helpers,
+              ...(await spectestContext({ service: svc.name, includeSelf: true })),
+              ...{ [COMPONENT_RUNTIME]: {
+                images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name)! })),
+                gateway: await bridgeGatewayIp(),
+                caBundle: await ensureCaBundle(),
+              } },
+            });
           });
         } catch (err) {
           throw await withContainerPostMortem(svc.name, err);
+        } finally {
+          fetchScope.active = false;
         }
       }
     })()]);
@@ -4857,7 +4776,7 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
     exec: (service, command, opts) =>
       componentExec(service, command, opts, execTimeoutMs),
     // Read `globalThis.fetch` at call time: the wrapper is installed for
-    // the duration of a test / eval / project setup, so a context built
+    // the duration of bootstrap / a test / eval / project setup, so a context built
     // before it lands still gets the wrapped one.
     fetch: ((input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) =>
       globalThis.fetch(input, init)) as unknown as SpectestContext["fetch"],

package/src/harness/certificate.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateHostCert } from "./certificate.js";
+
+test("long ingress names retain their full SAN while the diagnostic CN stays bounded", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-leaf-"));
+  const ca = join(dir, "ca.crt");
+  const key = join(dir, "ca.key");
+  try {
+    const root = Bun.spawnSync(["openssl", "req", "-x509", "-newkey", "rsa:2048",
+      "-nodes", "-days", "1", "-subj", "/CN=test-ca", "-keyout", key, "-out", ca]);
+    expect(root.exitCode, root.stderr.toString()).toBe(0);
+    // Long enough to exceed both the former CN and temporary filename limits.
+    const host = `${"a".repeat(63)}.${"b".repeat(63)}.${"c".repeat(63)}.${"d".repeat(61)}`;
+    const { cert, key: leafKey } = await generateHostCert(host, [host, "*.example.test"], ca, key);
+    const leaf = new X509Certificate(cert);
+    expect(leaf.subject.length).toBeLessThanOrEqual(67); // "CN=" + 64 bytes
+    expect(leaf.checkHost(host)).toBe(host);
+    expect(leaf.checkHost("api.example.test")).toBe("*.example.test");
+    expect(leafKey).toContain("PRIVATE KEY");
+    const file = join(dir, "leaf.crt");
+    await writeFile(file, cert);
+    const verified = Bun.spawnSync(["openssl", "verify", "-CAfile", ca, "-verify_hostname", host, file]);
+    expect(verified.exitCode, verified.stderr.toString()).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);

package/src/harness/certificate.ts

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Generate a leaf cert + key for one ingress route (fake or service
+ * proxy), signed by the in-VM root CA. SANs cover every
+ * hostname the route answers to, so a client connecting with TLS
+ * verifies cleanly regardless of which hostname it used. Shells out
+ * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
+ * bookworm ships 3.0.x).
+ *
+ * `label` is a diagnostic tag baked into the cert Subject CN and the temp
+ * file names — only used for diagnostics, not for TLS verification.
+ */
+export async function generateHostCert(
+  label: string,
+  hostnames: string[],
+  caPath: string,
+  caKeyPath: string,
+): Promise<{ cert: string; key: string }> {
+  // CN is diagnostic only; SANs retain the full hostnames. Bound the label
+  // for both OpenSSL's 64-byte CN limit and filesystem component limits.
+  const commonName = `spectest-${label.replace(/[^a-zA-Z0-9.-]/g, "_").slice(0, 55)}`;
+  const id = `${commonName}-${randomUUID()}`;
+  const keyPath = path.join("/tmp", `${id}.key`);
+  const crtPath = path.join("/tmp", `${id}.crt`);
+  const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+  const args = [
+    "req",
+    "-newkey",
+    "rsa:2048",
+    "-nodes",
+    "-keyout",
+    keyPath,
+    "-out",
+    crtPath,
+    "-x509",
+    "-CA",
+    caPath,
+    "-CAkey",
+    caKeyPath,
+    "-days",
+    "3650",
+    "-subj",
+    `/CN=${commonName}`,
+    "-addext",
+    `subjectAltName=${sans}`,
+    "-addext",
+    "basicConstraints=CA:FALSE",
+    "-addext",
+    "extendedKeyUsage=serverAuth",
+    "-addext",
+    "keyUsage=digitalSignature,keyEncipherment",
+  ];
+  try {
+    await execFileAsync("openssl", args, { timeout: 30_000 });
+    const [cert, key] = await Promise.all([
+      fs.readFile(crtPath, "utf8"),
+      fs.readFile(keyPath, "utf8"),
+    ]);
+    return { cert, key };
+  } finally {
+    await Promise.all([
+      fs.unlink(keyPath).catch(() => {}),
+      fs.unlink(crtPath).catch(() => {}),
+    ]);
+  }
+}

package/src/harness/eval-typecheck.test.ts

@@ -50,6 +50,34 @@ function run(command: string, args: string[], timeout: number): Promise<{ code:
 const opts = () => ({ appDir, file, projectEntry, typecheckDir, run });
 const query = 'const rows = await ctx.svc.supabase.sql<{ analyzed: boolean }>`SELECT true AS analyzed`;';
 
+test("annotated services keep helper types while literals without helpers stay absent", async () => {
+  await fs.writeFile(projectEntry, `
+import { defineEnvironment, type ServiceDefinition } from "@specific.dev/spectest";
+interface Helpers { value(): number }
+const annotated: ServiceDefinition<Helpers> = {
+  image: "example:latest", helpers: async () => ({ value: () => 42 }),
+};
+const checked = { image: "example:latest", helpers: () => ({ value: () => 42 }) } satisfies ServiceDefinition<Helpers>;
+const env = defineEnvironment({ name: "helpers", services: {
+  annotated, checked, plain: { image: "example:latest" },
+  absent: { image: "example:latest", helpers: undefined },
+} });
+export default env.project([]);
+`);
+  await fs.writeFile(file, `
+const a: number = ctx.svc.annotated.value();
+const b: number = ctx.svc.checked.value();
+// @ts-expect-error plain services have no handle
+ctx.svc.plain;
+// @ts-expect-error explicitly absent helpers have no handle either
+ctx.svc.absent;
+// @ts-expect-error helper return type must not widen to any
+const wrong: string = ctx.svc.annotated.value();
+export default a + b;
+`);
+  expect(await checkEval(opts())).toMatchObject({ status: "ok", errors: [], totalErrors: 0 });
+}, 30_000);
+
 test("eval receives the default-exported project's service/fake types and globals", async () => {
   await fs.writeFile(file, `${query}
 const ready: boolean = rows[0].analyzed.unwrap();

package/src/harness/fetch.test.ts

@@ -3,6 +3,7 @@ import { expect as assertValue } from "../index.js";
 import { readRaw, readTag, type SpectestFetch, type WrappedResponse } from "../inspect.js";
 import { recordFake, startRecording, stopRecording, type HttpEvent } from "../recorder.js";
 import { installFetchWrapper, isTransportError } from "./fetch.js";
+import { startServices } from "./service-graph.js";
 import {
   bindInstrumentationScope,
   createInstrumentationScope,
@@ -356,4 +357,31 @@ describe("fetch execution scopes", () => {
       setup.active = false;
     }
   });
+
+  test("parallel service setup scopes keep wrapping after a sibling fails", async () => {
+    const gate = deferred();
+    const slowStarted = deferred();
+    const setup = startServices([{ name: "bad" }, { name: "slow" }], async ({ name }) => {
+      const hookScope = createInstrumentationScope(false);
+      try {
+        await runInstrumented(hookScope, async () => {
+          if (name === "bad") { await slowStarted.promise; throw new Error("failed hook"); }
+          slowStarted.resolve();
+          await gate.promise;
+          const res = await fetch(url("/service-setup")) as unknown as WrappedResponse;
+          expect(res.status.unwrap()).toBe(200);
+          expect((await res.json<{ value: number }>()).value.unwrap()).toBe(42);
+          await runUninstrumented(async () => {
+            expect((await fetch(url("/fake"))).status).toBe(200);
+          });
+        });
+      } finally { hookScope.active = false; }
+    });
+    const outcome = setup.catch(error => error);
+    await slowStarted.promise;
+    expect((await fetch(url("/background"))).status).toBe(200);
+    gate.resolve();
+    expect((await outcome).message).toBe("failed hook");
+    expect(stopRecording()).toEqual([]);
+  });
 });

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

@@ -1,9 +1,39 @@
 import { describe, expect, test } from "bun:test";
 
-import { topologicalOrder, validateServiceGraph } from "./service-graph";
+import { startServices, topologicalOrder, validateServiceGraph } from "./service-graph";
 
 const svc = (name: string, dependsOn?: string[]) => ({ name, dependsOn });
 
+test("bootstrap waits for sibling hooks after a failure and never starts failed dependents", async () => {
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  const started: string[] = [];
+  let completed = false;
+  let settled = false;
+  const failed = new Error("setup failed");
+  const result = startServices([svc("bad"), svc("slow"), svc("child", ["bad"])], async ({ name }) => {
+    started.push(name);
+    if (name === "bad") throw failed;
+    if (name === "slow") { await gate; completed = true; }
+  }).then(() => { settled = true; return undefined; }, error => { settled = true; return error; });
+  await new Promise(resolve => setTimeout(resolve, 0));
+  expect(started).toEqual(["bad", "slow"]);
+  expect(settled).toBe(false);
+  release();
+  const error = await result;
+  expect(completed).toBe(true);
+  expect(error instanceof AggregateError ? error.errors : [error]).toContain(failed);
+});
+
+test("shared dependencies complete setup once before either dependent starts", async () => {
+  const started: string[] = [];
+  await startServices([svc("a", ["db"]), svc("b", ["db"]), svc("db")], async ({ name }) => {
+    await Promise.resolve();
+    started.push(name);
+  });
+  expect(started).toEqual(["db", "a", "b"]);
+});
+
 describe("validateServiceGraph", () => {
   test("returns a name→service map for a clean graph", () => {
     const map = validateServiceGraph([svc("db"), svc("api", ["db"])]);

package/src/harness/service-graph.ts

@@ -1,3 +1,5 @@
+import { waitForAll } from "./concurrency.js";
+
 /**
  * The `dependsOn` graph: validation, and the traversal order bring-up
  * uses.
@@ -95,3 +97,24 @@ export function topologicalOrder<T extends GraphNode>(services: readonly T[]): T
   for (const s of services) visit(s.name);
   return out;
 }
+
+/** Start each service after its dependencies finish setup. Drain all branches
+ * before reporting failure so teardown cannot race containers or hooks. */
+export async function startServices<T extends GraphNode>(
+  services: readonly T[],
+  startOne: (svc: T) => Promise<void>,
+): Promise<void> {
+  const byName = validateServiceGraph(services);
+  const started = new Map<string, Promise<void>>();
+  const start = (svc: T): Promise<void> => {
+    const existing = started.get(svc.name);
+    if (existing) return existing;
+    const pending = (async () => {
+      await Promise.all((svc.dependsOn ?? []).map(name => start(byName.get(name)!)));
+      await startOne(svc);
+    })();
+    started.set(svc.name, pending);
+    return pending;
+  };
+  await waitForAll(services.map(start));
+}

package/src/index.ts

@@ -796,13 +796,16 @@ export interface ServiceDefinition<
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ServicesMap = Record<string, ServiceDefinition<any>>;
 
-/** Awaited return type of a service's `helpers` factory, or `never` if
- * the service doesn't ship one. */
-type HelpersOf<D> = D extends {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  helpers: (...args: any) => infer R;
-}
-  ? Awaited<R>
+/** Awaited return type of a service's helpers factory. Check key presence
+ * before removing optionality: annotations keep `helpers?`, while plain
+ * service literals with no factory must stay out of ctx.svc. */
+type HelpersOf<D> = "helpers" extends keyof D
+  ? [NonNullable<D["helpers"]>] extends [never]
+    ? never
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    : NonNullable<D["helpers"]> extends (...args: any[]) => infer R
+      ? Awaited<R>
+      : never
   : never;
 
 /**