@specific.dev/spectest 0.91.2 → 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,13 +40,15 @@ 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";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
-import { fsUsageDiagnostics, runWrapperRules } from "./harness/wrapper-rules.js";
+import { fsUsageDiagnostics } from "./harness/wrapper-rules.js";
+import { runTypecheck } from "./harness/typecheck.js";
+import { evaluateChecked } from "./harness/eval-typecheck.js";
 import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
 import { compactReach, projectReach, renderReachRules, renderReadsLcov } from "./harness/reach.js";
@@ -1451,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.
 //
@@ -1623,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. */
@@ -1717,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 ||
@@ -2940,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();
     }
 }
@@ -3109,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)
@@ -4011,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,
@@ -5209,7 +5141,8 @@ async function evalCode(code) {
         filePath = path.join(EVAL_DIR, `${randomUUID()}.ts`);
         await fs.writeFile(filePath, prepared.code);
         const moduleUrl = pathToFileURL(filePath).href;
-        const mod = (await runInstrumented(fetchScope, () => import(moduleUrl)));
+        const mod = await evaluateChecked({ file: filePath, appDir: APP_DIR, typecheckDir: TYPECHECK_DIR, run: shx,
+            projectEntry: loaded ? resolveEntry() : undefined }, (text) => { chunks.push(text); }, () => runInstrumented(fetchScope, () => import(moduleUrl)));
         outcome = { ok: true, result: safeSerialize(mod.default) };
     }
     catch (err) {
@@ -5292,12 +5225,10 @@ async function evalCode(code) {
  *  blocking rules, which always use THIS copy rather than the project's own —
  *  can be driven outside a VM. */
 const TYPECHECK_DIR = process.env.SPECTEST_TYPECHECK_DIR ?? "/opt/spectest/typecheck";
-/** Cap on errors shipped in the report; `totalErrors` carries the true count. */
-const TYPECHECK_ERROR_CAP = 50;
 let TYPECHECK = null;
 /** Fire-and-forget kickoff; the promise is parked for POST /typecheck. */
 function startTypecheck() {
-    TYPECHECK = runTypecheck().catch((err) => ({
+    TYPECHECK = runProjectTypecheck().catch((err) => ({
         status: "failed",
         errors: [],
         totalErrors: 0,
@@ -5307,141 +5238,9 @@ function startTypecheck() {
     // Parked promises must never surface as unhandled rejections.
     TYPECHECK.catch(() => { });
 }
-/** The tsconfig used when the project doesn't ship its own. `lib` is left to
- *  the target default (which includes DOM — browser.evaluate callbacks
- *  reference `document`); `types` pulls Bun's ambient globals from the baked
- *  install via `typeRoots` (the walk-up from APP_DIR never reaches it). */
-function generatedTsconfig() {
-    return JSON.stringify({
-        compilerOptions: {
-            target: "esnext",
-            module: "esnext",
-            moduleResolution: "bundler",
-            strict: true,
-            noEmit: true,
-            skipLibCheck: true,
-            esModuleInterop: true,
-            resolveJsonModule: true,
-            jsx: "react-jsx",
-            types: ["bun"],
-            typeRoots: [
-                path.join(APP_DIR, "node_modules", "@types"),
-                path.join(TYPECHECK_DIR, "node_modules", "@types"),
-            ],
-        },
-        include: ["**/*.ts", "**/*.tsx"],
-        exclude: ["node_modules"],
-    }, null, 2);
-}
-/** Parse `--pretty false` tsc output: `file(line,col): error TScode: msg`,
- *  with indented elaboration lines folded into the preceding error. */
-function parseTscOutput(output) {
-    const errors = [];
-    let total = 0;
-    let suppressed = 0;
-    let last = null;
-    for (const line of output.split("\n")) {
-        const m = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
-        if (!m) {
-            // Elaboration lines are indented; fold them into the last kept error.
-            if (last && /^\s+\S/.test(line))
-                last.message += `\n${line.trimEnd()}`;
-            continue;
-        }
-        const [, rawFile, ln, col, code, message] = m;
-        // Keep only diagnostics in the user's files. tsc runs with cwd=APP_DIR
-        // (the daemon's cwd), so project files come out relative ("tests/x.ts")
-        // and anything outside — the SDK at /opt/spectest/sdk, node_modules —
-        // is `../…` or absolute. Errors in our own SDK are ours to fix, not the
-        // user's to read.
-        const abs = path.resolve(APP_DIR, rawFile);
-        const inApp = abs.startsWith(APP_DIR + path.sep) && !abs.includes(`${path.sep}node_modules${path.sep}`);
-        if (!inApp) {
-            suppressed += 1;
-            last = null;
-            continue;
-        }
-        total += 1;
-        const err = {
-            file: path.relative(APP_DIR, abs),
-            line: Number(ln),
-            column: Number(col),
-            code: code,
-            message: message,
-        };
-        if (errors.length < TYPECHECK_ERROR_CAP) {
-            errors.push(err);
-            last = err;
-        }
-        else {
-            last = null;
-        }
-    }
-    return { errors, total, suppressed };
-}
-async function runTypecheck() {
-    const started = Date.now();
-    // The project's own typescript wins over the baked copy.
-    const tsc = [
-        path.join(APP_DIR, "node_modules", "typescript", "bin", "tsc"),
-        path.join(TYPECHECK_DIR, "node_modules", "typescript", "bin", "tsc"),
-    ].find((p) => existsSync(p));
-    if (!tsc) {
-        return {
-            status: "skipped",
-            errors: [],
-            totalErrors: 0,
-            durationMs: 0,
-            detail: "typescript is not installed (base image predates the baked typechecker)",
-        };
-    }
-    let config = path.join(APP_DIR, "tsconfig.json");
-    if (!existsSync(config)) {
-        config = path.join(APP_DIR, ".spectest-tsconfig.json");
-        await fs.writeFile(config, generatedTsconfig());
-    }
-    const res = await shx(process.execPath, [tsc, "--noEmit", "--pretty", "false", "-p", config], 120_000);
-    const durationMs = Date.now() - started;
-    if (res.code === 124) {
-        return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
-    }
-    const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
-    const wrapper = [...(await runWrapperRulesReport(config)), ...(await rawFsReport())];
-    const strip = ({ file, line, column, code, message }) => ({
-        file,
-        line,
-        column,
-        code,
-        message,
-    });
-    const blocking = wrapper.filter((d) => d.blocking).map(strip);
-    const advisory = wrapper.filter((d) => !d.blocking).map(strip);
-    if (errors.length === 0 && wrapper.length === 0) {
-        // Exit 0 → clean. Non-zero with no *user-file* diagnostics is either
-        // all-suppressed (still ok from the user's perspective) or a compiler
-        // crash (config not found, OOM) — surface the latter.
-        if (res.code !== 0 && suppressed === 0) {
-            const tail = (res.stderr || res.stdout).trim().split("\n").slice(-5).join("\n");
-            return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: tail || `tsc exited ${res.code}` };
-        }
-        if (suppressed > 0) {
-            console.warn(`[typecheck] ${suppressed} diagnostic(s) outside the project suppressed`);
-        }
-        return { status: "ok", errors: [], totalErrors: 0, durationMs };
-    }
-    // The wrapper findings ride the same list the CLI and the dashboard already
-    // render; `blocking` is a second view of the ones that also fail the run, so
-    // nothing has to learn a new shape to show them. Blocking leads, because
-    // `errors` is capped and the entries that stopped the run must never be the
-    // ones the cap drops.
-    const all = [...blocking, ...advisory, ...errors];
-    return {
-        status: "errors",
-        errors: all.slice(0, TYPECHECK_ERROR_CAP),
-        totalErrors: total + wrapper.length,
-        durationMs,
-        ...(blocking.length > 0 ? { blocking } : {}),
-    };
+async function runProjectTypecheck() {
+    return runTypecheck({ appDir: APP_DIR, typecheckDir: TYPECHECK_DIR, run: shx,
+        projectEntry: loaded ? resolveEntry() : undefined, extraDiagnostics: rawFsReport });
 }
 /**
  * The raw-fs rule (`SPECTEST2003`, advisory) over the test tree: a test
@@ -5468,38 +5267,6 @@ async function rawFsReport() {
         return [];
     }
 }
-/**
- * The blocking rules, run against the BAKED compiler whatever the project
- * pins. Best-effort in every direction: an install that predates the API, a
- * config the rules cannot open, or a throw from `typescript/unstable/*` all
- * yield no findings, so a run proceeds exactly as it does today. Only a
- * definite finding can stop one.
- */
-async function runWrapperRulesReport(config) {
-    const typescriptDir = path.join(TYPECHECK_DIR, "node_modules", "typescript");
-    if (!existsSync(path.join(typescriptDir, "dist", "api", "async", "api.js")))
-        return [];
-    try {
-        const run = await runWrapperRules({
-            typescriptDir,
-            configFile: config,
-            appDir: APP_DIR,
-            readFile: (f) => fs.readFile(f, "utf8"),
-            relative: path.relative,
-            join: path.join,
-            dirname: path.dirname,
-        });
-        if (run.status !== "ok") {
-            console.warn(`[typecheck] wrapper rules ${run.status}: ${run.detail ?? "no detail"}`);
-            return [];
-        }
-        return run.diagnostics;
-    }
-    catch (err) {
-        console.warn(`[typecheck] wrapper rules threw: ${err?.message ?? err}`);
-        return [];
-    }
-}
 /** Run `job` under a mutual-exclusion slot, refusing if one is held. */
 async function exclusive(state, slot, busy, job) {
     if (state[slot])

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/eval-typecheck.d.ts

@@ -0,0 +1,9 @@
+import { type TypecheckOptions, type TypecheckReport } from "./typecheck.js";
+interface EvalTypecheckOptions extends Pick<TypecheckOptions, "appDir" | "typecheckDir" | "run"> {
+    file: string;
+    projectEntry?: string;
+}
+export declare function checkEval(opts: EvalTypecheckOptions): Promise<TypecheckReport>;
+/** The same advisory/blocking policy as a managed test, before module import. */
+export declare function evaluateChecked<T>(opts: EvalTypecheckOptions, log: (text: string) => void, evaluate: () => Promise<T>): Promise<T>;
+export {};

package/dist/harness/eval-typecheck.js

@@ -0,0 +1,93 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { generatedTsconfig, projectTypecheckConfig, runTypecheck } from "./typecheck.js";
+/** Describe the globals installed by evalCode, without importing/executing the project. */
+function globals(projectEntry) {
+    return `import type * as SDK from "@specific.dev/spectest";
+${projectEntry ? `import type project from ${JSON.stringify(projectEntry)};` : ""}
+type EvalContext = ${projectEntry
+        ? "typeof project extends SDK.Project<infer S, infer F> ? SDK.TestContext<undefined, S, F> : SDK.TestContext<undefined>"
+        : "SDK.TestContext<undefined>"};
+declare global {
+  var ctx: EvalContext;
+  var expect: typeof SDK.expect;
+  var expectRaw: typeof SDK.expectRaw;
+  var assert: typeof SDK.assert;
+  var state: Record<string, unknown>;
+}
+`;
+}
+export async function checkEval(opts) {
+    const started = Date.now();
+    let scratch;
+    try {
+        scratch = await fs.mkdtemp(path.join(path.dirname(opts.file), "check-"));
+        const declarations = path.join(scratch, "globals.d.ts");
+        await fs.writeFile(declarations, globals(opts.projectEntry));
+        const projectConfig = projectTypecheckConfig(opts);
+        const defaults = JSON.parse(generatedTsconfig(opts.appDir, opts.typecheckDir));
+        const config = {
+            ...(projectConfig ? { extends: projectConfig } : defaults),
+            compilerOptions: {
+                ...(!projectConfig ? defaults.compilerOptions : {}),
+                // Bun runs eval as ESM TypeScript, regardless of the app's build output.
+                noEmit: true,
+                skipLibCheck: true,
+                target: "esnext",
+                module: "esnext",
+                moduleResolution: "bundler",
+                moduleDetection: "force",
+                allowImportingTsExtensions: true,
+                composite: false,
+                incremental: false,
+                rootDir: opts.appDir,
+            },
+            // Project includes/excludes may omit hidden files or include the entire
+            // application. Check this snippet, with imports resolved normally.
+            files: [opts.file, declarations],
+            include: [],
+            exclude: [],
+        };
+        const configFile = path.join(scratch, "tsconfig.json");
+        await fs.writeFile(configFile, JSON.stringify(config));
+        const report = await runTypecheck({ ...opts, configFile, diagnosticFile: opts.file });
+        // Stable, snippet-relative locations; don't expose random temporary paths.
+        const normalize = (d) => ({ ...d, file: "eval.ts" });
+        return {
+            ...report,
+            errors: report.errors.map(normalize),
+            ...(report.blocking ? { blocking: report.blocking.map(normalize) } : {}),
+        };
+    }
+    catch (error) {
+        // Match managed tests: unavailable/broken checkers report their failure,
+        // while only a definite blocking finding prevents execution.
+        return {
+            status: "failed", errors: [], totalErrors: 0, durationMs: Date.now() - started,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        if (scratch)
+            await fs.rm(scratch, { recursive: true, force: true });
+    }
+}
+/** The same advisory/blocking policy as a managed test, before module import. */
+export async function evaluateChecked(opts, log, evaluate) {
+    const report = await checkEval(opts);
+    if (report.status === "failed" || report.status === "skipped") {
+        log(`[typecheck] ${report.status}: ${report.detail ?? "unavailable"}\n`);
+    }
+    else if (report.totalErrors > 0) {
+        log(`[typecheck] ${report.totalErrors} diagnostic(s)${report.blocking?.length ? "" : " (advisory)"}\n`);
+        for (const d of report.errors)
+            log(`${d.file}:${d.line}:${d.column}: ${d.code}: ${d.message}\n`);
+        if (report.totalErrors > report.errors.length) {
+            log(`[typecheck] ${report.totalErrors - report.errors.length} more diagnostic(s)\n`);
+        }
+    }
+    if (report.blocking?.length) {
+        throw new Error(`Typecheck: ${report.blocking.length} blocking error(s) in eval — the snippet did not run. Fix the diagnostics above before retrying.`);
+    }
+    return evaluate();
+}

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));
+}