@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

package/src/tests/api_tests/welle_partner_token.test.ts

@@ -3,17 +3,18 @@ require('source-map-support').install();
 import { createHmac } from "crypto"
 
 import { Session, EnduserSession } from "../../sdk"
-import {
-  assert,
-  async_test,
-  log_header,
-  wait,
-} from "@tellescope/testing"
 import { HEALTHIE_TITLE, WELLE_TITLE } from "@tellescope/constants"
-import { authenticate_enduser_via_token, setup_tests } from "../setup"
+import {
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
 const SIGNING_KEY = 'welle_test_signing_key_do_not_use_in_prod'
 const HEALTHIE_PATIENT_ID = '999888777'
 
@@ -36,9 +37,17 @@ const sign_hs256 = (signingInput: string, key: string) => (
   createHmac('sha256', key).update(signingInput).digest('base64url')
 )
 
-// reset_db does NOT clear integrations, so a crashed prior run can leave a Welle record behind.
-// The partner-token branch does findOne({ title: WELLE_TITLE }), so a stray record would make the
-// "disconnected" assertion pass spuriously — clear them all rather than only the one we created.
+/**
+ * Deletes this tenant's Welle integration records.
+ *
+ * Scenario 7 below (the "disconnected" rejection) is what needs it: the partner-token branch does
+ * findOne({ title: WELLE_TITLE }), so the record has to be gone for that assertion to mean anything.
+ * It is deliberately a delete-by-title rather than a delete of the id created here, because
+ * add_api_key_integration later creates a second record the same way the product does.
+ *
+ * On a provisioned tenant it can only ever see this suite's own records — on the shared organization
+ * it deleted other suites' Welle integrations too, which is one of the reasons this suite moved.
+ */
 const delete_all_welle_integrations = async (sdk: Session) => {
   const existing = await sdk.api.integrations.getSome({})
   for (const integration of existing.filter(i => i.title === WELLE_TITLE)) {
@@ -46,10 +55,92 @@ const delete_all_welle_integrations = async (sdk: Session) => {
   }
 }
 
-export const welle_partner_token_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Welle Partner Token Tests")
+// Welle partner-token (SSO launch) coverage: HS256 claims for a Healthie-linked patient, jti
+// uniqueness, the 60s expiry, the non-forgeable subject, the disconnected / unlinked / staff-session
+// rejections, and the real add_api_key_integration / remove_api_key_integration connect paths.
+//
+// Runs on its own provisioned tenant, so no pre-run "clear every Welle record in the org" reset is
+// needed and no other suite's integrations are ever touched.
+export const welle_partner_token_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  // The raw value decides the fallback, not JSON.stringify of it — JSON.stringify('') is '""',
+  // which is truthy, so a `|| fallback` on the stringified form could never fire.
+  const describe = (value: any): string => {
+    if (value === undefined || value === null) return String(value)
+    const stringified = JSON.stringify(value)
+    return stringified === undefined ? String(value) : stringified
+  }
+  const errorMessage = (e: any): string => (
+    typeof e?.message === 'string' && e.message !== '' ? e.message : describe(e)
+  )
+
+  /**
+   * The async_test({ onResult }) equivalent, as a soft Check: a call that REJECTS is a failure
+   * (async_test treats it the same way), and a resolved call passes only when onResult agrees.
+   *
+   * The call and the predicate are caught separately, so a predicate that throws (a malformed token
+   * handed to decode_jwt_payload, say) fails THIS check with its own detail instead of escaping
+   * `run` — an escape would fail the whole batch rather than one check.
+   */
+  const expect_result = async <T,>(label: string, fn: () => Promise<T>, onResult: (r: T) => boolean) => {
+    let resolved: { value: T }
+    try {
+      resolved = { value: await fn() }
+    } catch (e: any) {
+      record(label, false, `rejected instead of resolving: ${errorMessage(e)}`)
+      return
+    }
+
+    const { value } = resolved
+    try {
+      record(label, onResult(value), `result=${describe(value)}`)
+    } catch (predicateError: any) {
+      record(label, false, `predicate threw on result=${describe(value)}: ${errorMessage(predicateError)}`)
+    }
+  }
+
+  /**
+   * The async_test({ shouldError: true, onError }) equivalent: a call that RESOLVES is a failure
+   * (async_test treats it the same way), and a rejection passes only when onError agrees.
+   */
+  const expect_rejected = async (label: string, fn: () => Promise<any>, onError: (e: any) => boolean = () => true) => {
+    let rejection: { e: any }
+    try {
+      const unexpected = await fn()
+      record(label, false, `resolved instead of rejecting; result=${describe(unexpected)}`)
+      return
+    } catch (e: any) {
+      rejection = { e }
+    }
+
+    // Outside the catch on purpose: a predicate that throws here would otherwise escape the suite
+    // and, per run_isolated_in_parallel, abort every remaining batch instead of failing one check.
+    try {
+      record(label, onError(rejection.e), `rejected with ${errorMessage(rejection.e)}`)
+    } catch (predicateError: any) {
+      record(
+        label,
+        false,
+        `predicate threw on rejection ${errorMessage(rejection.e)}: ${errorMessage(predicateError)}`,
+      )
+    }
+  }
+
+  /** A synchronous assertion over values already in hand (the former bare `assert` calls). */
+  const record_sync = (label: string, evaluate: () => { pass: boolean, detail: string }) => {
+    try {
+      const { pass, detail } = evaluate()
+      record(label, pass, detail)
+    } catch (e: any) {
+      record(label, false, `evaluation threw: ${errorMessage(e)}`)
+    }
+  }
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
 
-  const suffix = Math.random().toString(36).slice(2, 10)
+  const suffix = RAND()
   const linkedEmail = `welle.linked.${suffix}@tellescope.com`
   const unlinkedEmail = `welle.unlinked.${suffix}@tellescope.com`
 
@@ -57,7 +148,13 @@ export const welle_partner_token_tests = async ({ sdk, sdkNonAdmin } : { sdk: Se
   let unlinkedId = ''
 
   try {
-    await delete_all_welle_integrations(sdk)
+    // the default user spec provisions an Admin plus a non-admin — sdkNonAdmin is the staff session
+    // checked below, which must also not be served a partner token
+    tenant = await setup_isolated_tenant({
+      name: `Welle partner token ${RAND()}`,
+      apiKeys: 0,
+    })
+    const { sdk, sdkNonAdmin, businessId } = tenant
 
     await sdk.api.integrations.createOne({
       title: WELLE_TITLE,
@@ -86,18 +183,29 @@ export const welle_partner_token_tests = async ({ sdk, sdkNonAdmin } : { sdk: Se
     const unlinked = await sdk.api.endusers.createOne({ email: unlinkedEmail, fname: 'Welle', lname: 'Unlinked' })
     unlinkedId = unlinked.id
 
-    const linkedSDK = new EnduserSession({ host, businessId: sdk.userInfo.businessId })
-    await authenticate_enduser_via_token(sdk, linkedSDK, { email: linkedEmail })
+    /**
+     * setup.ts's authenticate_enduser_via_token, inlined: it establishes an enduser session without
+     * hitting the IP-rate-limited /login-enduser endpoint. It is inlined rather than imported
+     * because setup.ts process.exit(1)s at MODULE SCOPE when the legacy TEST_EMAIL /
+     * NON_ADMIN_EMAIL credentials are unset, and suite discovery require()s every compiled test file
+     * — one surviving import would kill the whole discovery run on a checkout without them.
+     */
+    const enduser_session = async (filter: { id?: string, email?: string }) => {
+      const enduserSDK = new EnduserSession({ host, businessId })
+      const { authToken, enduser } = await sdk.api.endusers.generate_auth_token(filter)
+      await enduserSDK.handle_new_session({ authToken, enduser })
+      return enduserSDK
+    }
 
-    const unlinkedSDK = new EnduserSession({ host, businessId: sdk.userInfo.businessId })
-    await authenticate_enduser_via_token(sdk, unlinkedSDK, { email: unlinkedEmail })
+    const linkedSDK = await enduser_session({ email: linkedEmail })
+    const unlinkedSDK = await enduser_session({ email: unlinkedEmail })
 
     // 1) happy path — claims are correct
     let issuedToken = ''
-    await async_test(
+    await expect_result(
       `enduser can mint a Welle partner token with the expected claims`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { onResult: (r: any) => {
+      (r: any) => {
         issuedToken = r?.data?.token
         if (!issuedToken) return false
 
@@ -113,174 +221,193 @@ export const welle_partner_token_tests = async ({ sdk, sdkNonAdmin } : { sdk: Se
           && typeof payload.jti === 'string' && payload.jti.length > 0
           && Math.abs(payload.exp - expectedExp) < 10
         )
-      }},
+      },
     )
 
     // each launch gets a unique jti
-    await async_test(
+    await expect_result(
       `back-to-back tokens carry distinct jti values`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { onResult: (r: any) => {
+      (r: any) => {
         const second = r?.data?.token
-        if (!second) return false
+        if (!second || !issuedToken) return false
         return decode_jwt_payload(second).jti !== decode_jwt_payload(issuedToken).jti
-      }},
+      },
     )
 
     // optional deep-link target — allowlisted value is echoed as a claim
-    await async_test(
+    await expect_result(
       `target: 'plan' is included as a target claim`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token', target: 'plan' }),
-      { onResult: (r: any) => (
-        !!r?.data?.token && decode_jwt_payload(r.data.token).target === 'plan'
-      )},
+      (r: any) => !!r?.data?.token && decode_jwt_payload(r.data.token).target === 'plan',
     )
     // omitted target → no target claim at all (the happy-path token above was minted without one)
-    assert(
-      decode_jwt_payload(issuedToken).target === undefined,
-      "token minted without a target has a target claim",
-      "token minted without a target has no target claim",
+    record_sync(
+      `token minted without a target has no target claim`,
+      () => ({
+        pass: !!issuedToken && decode_jwt_payload(issuedToken).target === undefined,
+        detail: issuedToken
+          ? `target=${describe(decode_jwt_payload(issuedToken).target)}`
+          : 'no token was minted above, so the claim could not be read',
+      }),
     )
     // non-allowlisted target is rejected at the API boundary by schema validation
-    await async_test(
+    await expect_rejected(
       `invalid target is rejected by schema validation`,
       () => linkedSDK.api.integrations.proxy_read({
         integration: WELLE_TITLE,
         type: 'partner-redirect-token',
         target: 'admin' as any,
       }),
-      { shouldError: true, onError: () => true },
     )
 
     // 2) the signature is real — verifies against the stored signing key, and only that key
-    const [header, payload, signature] = issuedToken.split('.')
-    assert(
-      sign_hs256(`${header}.${payload}`, SIGNING_KEY) === signature,
-      "token signature does not verify against the stored Welle signing key",
-      "token is signed with the organization's Welle signing key",
+    record_sync(
+      `token is signed with the organization's Welle signing key`,
+      () => {
+        if (!issuedToken) return { pass: false, detail: 'no token was minted above, so the signature could not be checked' }
+        const [header, payload, signature] = issuedToken.split('.')
+        return {
+          pass: sign_hs256(`${header}.${payload}`, SIGNING_KEY) === signature,
+          detail: `signature=${describe(signature)}`,
+        }
+      },
     )
-    assert(
-      sign_hs256(`${header}.${payload}`, `${SIGNING_KEY}_wrong`) !== signature,
-      "token signature verified against the WRONG key",
-      "token signature does not verify against a different key",
+    record_sync(
+      `token signature does not verify against a different key`,
+      () => {
+        if (!issuedToken) return { pass: false, detail: 'no token was minted above, so the signature could not be checked' }
+        const [header, payload, signature] = issuedToken.split('.')
+        return {
+          pass: sign_hs256(`${header}.${payload}`, `${SIGNING_KEY}_wrong`) !== signature,
+          detail: `signature=${describe(signature)}`,
+        }
+      },
     )
 
     // 3) the subject is non-forgeable — the branch ignores the id param and uses the session's enduser
-    await async_test(
+    await expect_result(
       `enduser cannot mint a token for another enduser by passing id`,
       () => linkedSDK.api.integrations.proxy_read({
         integration: WELLE_TITLE,
         type: 'partner-redirect-token',
         id: unlinkedId,
       }),
-      { onResult: (r: any) => (
-        !!r?.data?.token && decode_jwt_payload(r.data.token).sub === HEALTHIE_PATIENT_ID
-      )},
+      (r: any) => !!r?.data?.token && decode_jwt_payload(r.data.token).sub === HEALTHIE_PATIENT_ID,
     )
 
     // 4) an enduser with no Healthie reference gets no token
-    await async_test(
+    await expect_rejected(
       `enduser without a Healthie reference cannot mint a token`,
       () => unlinkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { shouldError: true, onError: (e: any) => (e?.message || '').includes('enduser has no Healthie reference') },
+      (e: any) => (e?.message || '').includes('enduser has no Healthie reference'),
     )
 
     // 5) staff sessions are not served by this branch (it is enduser-gated) — falls through to an empty result
-    await async_test(
+    await expect_result(
       `admin user session is not issued a Welle partner token`,
       () => sdk.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { onResult: (r: any) => !r?.data?.token },
+      (r: any) => !r?.data?.token,
     )
-    await async_test(
+    await expect_result(
       `non-admin user session is not issued a Welle partner token`,
       () => sdkNonAdmin.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { onResult: (r: any) => !r?.data?.token },
+      (r: any) => !r?.data?.token,
     )
 
     // 6) no other Welle proxy_read type is reachable by an enduser
-    await async_test(
+    await expect_rejected(
       `enduser cannot read other Welle proxy types`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'anything-else' }),
-      { shouldError: true, onError: (e: any) => (
-        (e?.message || '').includes('enduser session type not valid for this integration type')
-      )},
+      (e: any) => (e?.message || '').includes('enduser session type not valid for this integration type'),
     )
 
     // 7) with the integration disconnected, no token can be minted
     await delete_all_welle_integrations(sdk)
-    await async_test(
+    await expect_rejected(
       `no token is issued once the Welle integration is disconnected`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { shouldError: true, onError: (e: any) => (e?.message || '').includes('Welle integration not found') },
+      (e: any) => (e?.message || '').includes('Welle integration not found'),
     )
 
     // 8) the real connect path — add_api_key_integration, not integrations.createOne.
     // Welle has no credential-validation branch (an opaque HMAC key has nothing to authenticate
     // against), so unlike Canvas/Candid/MDI this endpoint makes no upstream call and is testable.
-    await async_test(
+    await expect_result(
       `add_api_key_integration connects Welle`,
       () => sdk.api.integrations.add_api_key_integration({ integration: WELLE_TITLE, API_KEY: SIGNING_KEY }),
-      { onResult: (r: any) => r?.integration?.title === WELLE_TITLE },
+      (r: any) => r?.integration?.title === WELLE_TITLE,
     )
-    await async_test(
+    await expect_result(
       `add_api_key_integration sets hasConnectedWelle`,
-      () => sdk.api.organizations.getOne(sdk.userInfo.businessId),
-      { onResult: (o: any) => o?.hasConnectedWelle === true },
+      () => sdk.api.organizations.getOne(businessId),
+      (o: any) => o?.hasConnectedWelle === true,
     )
 
     // the key stored by add_api_key_integration must land in the field the proxy_read branch reads
     // (authentication.info.access_token) — minting a verifiable token proves the two paths agree
-    await async_test(
+    await expect_result(
       `token minted from the add_api_key_integration credential verifies`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { onResult: (r: any) => {
+      (r: any) => {
         const token = r?.data?.token
         if (!token) return false
         const [h, p, s] = token.split('.')
         return sign_hs256(`${h}.${p}`, SIGNING_KEY) === s
           && decode_jwt_payload(token).sub === HEALTHIE_PATIENT_ID
-      }},
+      },
     )
 
     // 9) the real disconnect path — remove_api_key_integration
-    await async_test(
+    await expect_result(
       `remove_api_key_integration disconnects Welle`,
       () => sdk.api.integrations.remove_api_key_integration({ integration: WELLE_TITLE }),
-      { onResult: () => true },
+      () => true,
     )
     // the org flag update is fire-and-forget on this handler (res.end() returns before the .then chain)
-    await wait(undefined, 250)
-    await async_test(
+    await new Promise(resolve => setTimeout(resolve, 250))
+    await expect_result(
       `remove_api_key_integration clears hasConnectedWelle`,
-      () => sdk.api.organizations.getOne(sdk.userInfo.businessId),
-      { onResult: (o: any) => !o?.hasConnectedWelle },
+      () => sdk.api.organizations.getOne(businessId),
+      (o: any) => !o?.hasConnectedWelle,
     )
-    await async_test(
+    await expect_rejected(
       `no token is issued after remove_api_key_integration`,
       () => linkedSDK.api.integrations.proxy_read({ integration: WELLE_TITLE, type: 'partner-redirect-token' }),
-      { shouldError: true, onError: (e: any) => (e?.message || '').includes('Welle integration not found') },
+      (e: any) => (e?.message || '').includes('Welle integration not found'),
     )
   } finally {
-    await delete_all_welle_integrations(sdk).catch(console.error)
-    await sdk.api.organizations.updateOne(sdk.userInfo.businessId, { hasConnectedWelle: false }).catch(console.error)
-    for (const id of [linkedId, unlinkedId]) {
-      if (!id) continue
-      await sdk.api.endusers.deleteOne(id).catch(console.error)
+    if (tenant) {
+      const { sdk, businessId } = tenant
+      await delete_all_welle_integrations(sdk).catch(console.error)
+      await sdk.api.organizations.updateOne(businessId, { hasConnectedWelle: false }).catch(console.error)
+      for (const id of [linkedId, unlinkedId]) {
+        if (!id) continue
+        await sdk.api.endusers.deleteOne(id).catch(console.error)
+      }
+      // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+      try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) }
     }
   }
+
+  return checks
 }
 
-// Allow running this test file independently
-if (require.main === module) {
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
+/** Asserting wrapper, for standalone runs. */
+export const welle_partner_token_tests = async () => {
+  assert_checks('Welle partner token', await welle_partner_token_checks())
+}
 
-  const runTests = async () => {
-    await setup_tests(sdk, sdkNonAdmin)
-    await welle_partner_token_tests({ sdk, sdkNonAdmin })
-  }
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Welle partner token',
+  run: welle_partner_token_checks,
+}
 
-  runTests()
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  welle_partner_token_tests()
     .then(() => {
       console.log("✅ Welle partner token test suite completed successfully")
       process.exit(0)

package/src/tests/setup_isolated.ts

@@ -1,4 +1,6 @@
 import axios from "axios"
+import fs from "fs"
+import path from "path"
 
 import { assert, log_header } from "@tellescope/testing"
 
@@ -36,6 +38,10 @@ export type IsolatedTenant = {
   subdomain: string,
   users: IsolatedUser[],
   apiKeys: string[],
+  /** Plaintext (`{ key }`) keys, provisioned only when the spec asked for `legacyApiKeys`. Never
+   *  merged into `apiKeys` — the two storage shapes are not interchangeable (a hashed key cannot
+   *  authenticate the form-ingestion webhook). */
+  legacyApiKeys: string[],
   roles: string[],
   /** Admin session (users[0]) */
   sdk: Session,
@@ -48,6 +54,9 @@ export type IsolatedTenantSpec = {
   name?: string,
   users?: { roles?: string[], isAdmin?: boolean }[],
   apiKeys?: number,
+  /** Keys stored UNHASHED, the legacy shape. Defaults to 0; `apiKeys` still defaults to 1. Ask for
+   *  one only when the suite must authenticate the form-ingestion webhook as a legacy caller. */
+  legacyApiKeys?: number,
   roles?: { role: string, permissions?: any }[],
 }
 
@@ -178,3 +187,141 @@ export const run_isolated_in_parallel = async (
     assert_checks(suites[i].name, r.value)
   }
 }
+
+/* ===================== auto-discovered parallel dispatcher ===================== */
+
+/**
+ * A suite enrolled in the parallel pool. A test file enrolls itself by exporting one of these as
+ * `ISOLATED_SUITE`; nothing shared has to be edited:
+ *
+ *   export const ISOLATED_SUITE: IsolatedSuite = { name: 'Programs', run: programs_checks }
+ *
+ * `run` must obey the same contract as run_isolated_in_parallel's entries: collect Check[], tear
+ * down its OWN tenants in a finally, and never assert (assert calls process.exit, which skips every
+ * other in-flight suite's teardown and strands its tenants permanently).
+ */
+export type IsolatedSuite = {
+  /** Unique across all enrolled suites; printed as the batch header and the check-table title. */
+  name: string,
+  run: () => Promise<Check[]>,
+}
+
+/** The export name a test file uses to enroll. Exported so the discovery unit test can scan for it. */
+export const ISOLATED_SUITE_EXPORT = 'ISOLATED_SUITE'
+
+/** Suites in flight at once when TEST_PARALLELISM is unset. Past this, a local API starts returning
+ *  429s from the per-record update throttles rather than real failures. */
+export const DEFAULT_TEST_PARALLELISM = 8
+
+/** Positive integers only; anything else falls back to the default rather than failing a run (a bad
+ *  value must never mean "no limit"). */
+export const parse_test_parallelism = (raw: string | undefined): number => {
+  if (raw === undefined || raw.trim() === '') return DEFAULT_TEST_PARALLELISM
+
+  const parsed = Number(raw.trim())
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    console.warn(
+      `  TEST_PARALLELISM=${JSON.stringify(raw)} is not a positive integer — using the default of ${DEFAULT_TEST_PARALLELISM}`
+    )
+    return DEFAULT_TEST_PARALLELISM
+  }
+  return parsed
+}
+
+export type DiscoveredIsolatedSuite = IsolatedSuite & {
+  /** Path relative to the api_tests root, e.g. `security/form-logic-js-execution.test.js`. */
+  file: string,
+}
+
+/** The compiled api_tests tree. Discovery walks `lib/cjs`, never `src` — a stale build silently drops
+ *  a suite from the run, which is what `npm run check:build` (run before every suite) exists to catch. */
+export const isolated_suites_root = () => path.join(__dirname, 'api_tests')
+
+/**
+ * Relative paths of every compiled test file under `root`, recursively (so `security/` is included),
+ * sorted by a plain code-unit comparison — NOT localeCompare, so batch membership is identical on
+ * every machine.
+ */
+const compiled_test_files = (root: string): string[] => {
+  const found: string[] = []
+
+  const walk = (dir: string, prefix: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name
+
+      if (entry.isDirectory()) { walk(path.join(dir, entry.name), relative); continue }
+      // `.test.js` alone: skips `.js.map`, `.d.ts`, `.d.ts.map` and any non-test helper module
+      if (!entry.name.endsWith('.test.js')) continue
+
+      found.push(relative)
+    }
+  }
+  walk(root, '')
+
+  return found.sort()
+}
+
+/**
+ * Loads every compiled test file and returns the ones that enrolled, in path order.
+ *
+ * `require` runs each file's module scope. That is safe only because every test file keeps its
+ * standalone entrypoint behind `if (require.main === module)` — that guard is load-bearing here.
+ */
+export const discover_isolated_suites = (root = isolated_suites_root()): DiscoveredIsolatedSuite[] => {
+  const suites: DiscoveredIsolatedSuite[] = []
+  const byName: Record<string, string> = {}
+  const label = (file: string) => `${path.basename(root)}/${file}`
+
+  if (!fs.existsSync(root)) {
+    // Loud, rather than "0 suites discovered" followed by a green run.
+    throw new Error(`No compiled test directory at ${root} — build first (npx tsc -b packages/tsconfig.cjs.json --force)`)
+  }
+
+  for (const file of compiled_test_files(root)) {
+    const loaded = require(path.join(root, file))
+    const descriptor = loaded?.[ISOLATED_SUITE_EXPORT]
+    if (descriptor === undefined || descriptor === null) continue
+
+    if (typeof descriptor.name !== 'string' || descriptor.name.trim() === '' || typeof descriptor.run !== 'function') {
+      throw new Error(
+        `${label(file)} exports ${ISOLATED_SUITE_EXPORT}, but it is not { name: string, run: () => Promise<Check[]> }`
+      )
+    }
+    if (byName[descriptor.name]) {
+      throw new Error(
+        `Two isolated suites are named ${JSON.stringify(descriptor.name)}: ${label(byName[descriptor.name])} and ${label(file)}`
+      )
+    }
+
+    byName[descriptor.name] = file
+    suites.push({ name: descriptor.name, run: descriptor.run, file })
+  }
+
+  return suites
+}
+
+/**
+ * Discovers the enrolled suites and runs them through a pool of TEST_PARALLELISM (default 8).
+ *
+ * One batch at a time, asserting after each batch settles rather than once at the end: a red batch
+ * stops the run instead of burning the rest of them. Within a batch the contract is unchanged —
+ * run_isolated_in_parallel lets every suite settle and tear down before anything asserts.
+ */
+export const run_discovered_isolated_suites = async (
+  options?: { root?: string, parallelism?: number },
+): Promise<DiscoveredIsolatedSuite[]> => {
+  const root = options?.root ?? isolated_suites_root()
+  const suites = discover_isolated_suites(root)
+  const parallelism = options?.parallelism ?? parse_test_parallelism(process.env.TEST_PARALLELISM)
+
+  console.log(`\nDiscovered ${suites.length} isolated suite(s), running up to ${parallelism} at a time:`)
+  for (const s of suites) {
+    console.log(`    ${s.name}  (${path.basename(root)}/${s.file})`)
+  }
+
+  for (let i = 0; i < suites.length; i += parallelism) {
+    await run_isolated_in_parallel(suites.slice(i, i + parallelism))
+  }
+
+  return suites
+}