declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/tests-node/best-practice/src/.test/useWakeOfLivedb.ts

@@ -0,0 +1,181 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = wake the shared aurora-serverless cluster before a suite runs, when this
+ *         service reaches it — whether it OWNS the db or only invokes peers that do.
+ * .why =
+ *   - the non-prod cluster is aurora-serverless-v2 at min-capacity 0, so it auto-pauses
+ *     when idle; the first downstream query after a pause cold-starts past the 90s test
+ *     timeout and flakes the suite (svc-gateway hit this on mAddCrewMember + the quote suites)
+ *   - a gateway/fan-out service owns NO db of its own, so a db-ownership signal misses it.
+ *     the signal that it REACHES the shared cluster is a tunnel declared in its config —
+ *     `config/prep.json`'s `database.tunnel`. that is the self-gate: a tunnel means a query
+ *     lands on the cluster (direct or via a peer), so wake it; no tunnel means no-op.
+ *   - `rhx use.rds.capacity` opens an ssm tunnel to the cluster and waits for it to accept
+ *     connections, which resumes it for every consumer (incl. deployed lambdas), not just
+ *     the local caller
+ *   - best-effort: a warm db, absent tunnel alias, or absent skill must NEVER break the
+ *     suite, so a wake failure is surfaced loud to stderr (not swallowed) and the suite
+ *     proceeds — a wake is a latency nicety, not a correctness gate; the suite's own
+ *     assertions are the gate
+ *   - ci is skipped: creds arrive via oidc and the local ssm-tunnel path is unavailable there,
+ *     so ci wakes via the dedicated `start:livedb:prep` workflow step instead
+ * .note = this is the LIVEDB half of a suite's db needs — the shared prep cluster its peers query.
+ *         it RESUMES a paused cluster. its pair, `useWakeOfTestdb`, is the LOCAL own-db half: it
+ *         only PREFLIGHTS the local testdb (it cannot start it, so it fails loud with a `start:testdb`
+ *         fix). the two form a symmetric pair; the name reads "wake" for symmetry, the act differs.
+ *         the wake fires for prep OR test access, per define.invariant.test-and-prep-reach-prep-peers.
+ */
+export const useWakeOfLivedb = async (
+  input: { env: 'test' | 'prep' | 'prod' | null },
+): Promise<void> => {
+  // in ci, the wake runs as a dedicated workflow step (local ssm-tunnel path is unavailable)
+  if (process.env.CI) return;
+
+  // prod never scales to 0, so it never needs a wake; default the target to prep
+  const env = input.env ?? 'prep';
+  if (env === 'prod') return;
+
+  // gate on a declared db tunnel: it is the signal this service reaches the shared cluster,
+  // whether it owns the db (persist-with-rds) or only invokes peers that query it (a gateway).
+  // absent config = no cluster to wake; a malformed config fails loud (names the file), never silent.
+  if (!asReachesSharedClusterFromConfig({ env })) return;
+
+  // the wake blocks suite start on a local run, so its budget is consumer-bounded: a generous
+  // default (a cold aurora-serverless-v2 resume can exceed 60s), overridable DOWN via
+  // LIVEDB_WAKE_TIMEOUT_MS so a consumer can fail fast on a hung tunnel rather than wait the full cap
+  const timeoutMs = Number(process.env.LIVEDB_WAKE_TIMEOUT_MS) || 180000;
+
+  // best-effort wake: a wake-command failure (a non-zero exit, a timeout kill, an absent binary) is
+  // non-fatal — a warm db or absent skill must not break the suite. but an error that bears no
+  // child-process shape is a malfunction in this module's own logic, so rethrow it (rule.forbid.failhide):
+  // the catch tolerates only the allowlisted wake failures and surfaces the rest.
+  try {
+    wakeSharedCluster({ env, timeoutMs });
+  } catch (error) {
+    if (!isWakeCommandFailure({ error })) throw error;
+    // a non-Error failure shape (e.g. a child-process `{ status, signal }` object) must read
+    // legibly on stderr: `String({...})` yields the useless `[object Object]`, so serialize it.
+    const message =
+      error instanceof Error ? error.message : JSON.stringify(error);
+    warnWakeFailed({ env, message });
+  }
+};
+
+/**
+ * .what = read the raw text of this service's `config/<env>.json`, or null when absent.
+ * .why  = a communicator leaf: the sole filesystem i/o of the wake gate, named so the
+ *         orchestrator composes it rather than embeds an inline `existsSync`/`readFileSync`.
+ * .note = an absent config is benign (a service that declares none reaches no known cluster),
+ *         so absence returns null and the pure decide-step below folds it to false. this leaf
+ *         performs i/o only; it never parses or decides.
+ */
+const readConfigText = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): string | null => {
+  const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+  if (!existsSync(configPath)) return null;
+  return readFileSync(configPath, 'utf8');
+};
+
+/**
+ * .what = decide, from raw config text, whether this service reaches the shared cluster.
+ * .why  = a pure transformer leaf: no i/o, deterministic. a `database.tunnel` in the config =
+ *         a query lands on the cluster (direct or via a peer), so the service reaches it.
+ *         the one fact — does this service reach the cluster — has one shape here, read off
+ *         the same `database.tunnel` signal everywhere, so two readers cannot drift.
+ */
+const asReachesSharedClusterFromConfigText = (input: {
+  text: string;
+}): boolean => {
+  return !!JSON.parse(input.text)?.database?.tunnel;
+};
+
+/**
+ * .what = compose the config read + tunnel decision into a single what-not-how signal.
+ * .why  = the composer of the two leaves above, so `useWakeOfLivedb` reads one intent rather than
+ *         an inline read-parse-decode a reader must simulate.
+ * .note = an absent config folds to false (no known cluster → no wake). but a present-yet-
+ *         unparseable config is NOT benign: it means the consumer authored a config the setup
+ *         cannot read, so a silent `false` would conflate a broken config with an absent tunnel.
+ *         so a parse failure throws a ConstraintError (caller-must-fix, exit 2) that names the
+ *         file + the fix, rather than a raw engine SyntaxError with no file and no remediation.
+ */
+const asReachesSharedClusterFromConfig = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): boolean => {
+  const text = readConfigText({ env: input.env });
+  if (text === null) return false; // no config = no known cluster (benign)
+  try {
+    return asReachesSharedClusterFromConfigText({ text });
+  } catch (cause) {
+    // allowlist the ONLY error the parse-decide leaf can throw — a SyntaxError on malformed json.
+    // an error of any other shape is a malfunction in this module's own logic, not a config the
+    // consumer mis-authored, so surface it unwrapped rather than relabel it a parse failure
+    // (rule.forbid.failhide: a catch allowlists its expected errors and rethrows the rest).
+    if (!(cause instanceof SyntaxError)) throw cause;
+    // a config the consumer authored but the setup cannot parse is a real defect, not "no cluster" —
+    // throw with the path so a malformed config names the file to repair (never a silent false)
+    const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+    throw new ConstraintError(
+      `useWakeOfLivedb: could not parse ${configPath} as JSON — fix the malformed config so the wake gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = wake the shared cluster by an ssm tunnel that resumes it for every consumer.
+ * .why  = a communicator leaf: the sole subprocess i/o of the wake, named so the orchestrator
+ *         composes it rather than embeds an inline `execSync`. `rhx use.rds.capacity` opens the
+ *         tunnel and waits for the cluster to accept connections, which resumes it (incl. for
+ *         deployed lambdas), not just the local caller.
+ */
+const wakeSharedCluster = (input: {
+  env: 'test' | 'prep' | 'prod';
+  timeoutMs: number;
+}): void => {
+  execSync(`rhx use.rds.capacity --env ${input.env}`, {
+    stdio: 'inherit',
+    timeout: input.timeoutMs,
+  });
+};
+
+/**
+ * .what = surface a wake failure loud to stderr, non-fatal.
+ * .why  = a communicator leaf: the failure sink of the wake, named so the orchestrator composes
+ *         it rather than embeds an inline `process.stderr.write`. a real wake failure — a
+ *         miswired command, an absent skill, a broken rhx binary — must be visible, never hidden;
+ *         the suite proceeds and a downstream cold-start timeout flake is the likely symptom.
+ */
+const warnWakeFailed = (input: {
+  env: 'test' | 'prep' | 'prod';
+  message: string;
+}): void => {
+  process.stderr.write(
+    `useWakeOfLivedb: 'rhx use.rds.capacity --env ${input.env}' failed (non-fatal): ${input.message}\n`,
+  );
+};
+
+/**
+ * .what = decide whether an error is a wake-command failure (safe to tolerate) vs a code malfunction.
+ * .why  = a pure transformer leaf: the allowlist `rule.forbid.failhide` demands. an execSync failure
+ *         bears a child-process shape — a numeric `status` (a non-zero exit), a string `signal` (a
+ *         timeout kill), or a string `code` (`ENOENT` for an absent binary, `ETIMEDOUT` for the cap).
+ *         those are the wake failures the suite intends to tolerate. an error with none of that shape
+ *         is a genuine malfunction in this module's own logic, so the catch rethrows it, never warns
+ *         it away — a best-effort op still distinguishes the failures it ignores from the ones it must not.
+ */
+const isWakeCommandFailure = (input: { error: unknown }): boolean => {
+  const error = input.error;
+  if (!error || typeof error !== 'object') return false;
+  const shape = error as { status?: unknown; signal?: unknown; code?: unknown };
+  if (typeof shape.status === 'number') return true; // child exited non-zero
+  if (typeof shape.signal === 'string') return true; // child killed by a signal (a timeout)
+  if (typeof shape.code === 'string') return true; // ENOENT (absent binary), ETIMEDOUT (cap hit)
+  return false;
+};

package/dist/practices/tests-node/best-practice/src/.test/useWakeOfTestdb.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+import { probeTestDb } from '../../jest.integration.env.db';
+
+/**
+ * .what = preflight the LOCAL testdb before a suite runs, when this service declares its own db.
+ * .why =
+ *   - prevent time wasted on a suite that fails deep in a query because the local testdb was never
+ *     provisioned, or was provisioned for a DIFFERENT repo (an opaque "password authentication
+ *     failed" surfaced far from its cause).
+ *   - the gate is a declared db: a `databaseUserName` in `declapract.use.yml` is the signal this
+ *     service OWNS a db (persist-with-rds), so it needs a local testdb. a service that declares none
+ *     is a no-op here.
+ *   - the check fails LOUD and CALLER-must-fix (a local testdb the human starts) via a ConstraintError
+ *     that names the fix — `probeTestDb` surfaces psql's own stderr so the consumer can tell "not
+ *     started" from "bad password" from "psql absent" (never a swallowed error).
+ * .note = this is the LOCAL own-db counterpart to `useWakeOfLivedb` (the shared prep cluster wake).
+ *         the two form a symmetric pair, but differ in one honest way: `useWakeOfLivedb` RESUMES a
+ *         paused cluster; this one only PREFLIGHTS the local testdb — it cannot start it, so it fails
+ *         loud with the `start:testdb` fix rather than resume it. the name reads "wake" for symmetry
+ *         with its pair; the act is a readiness preflight.
+ * .note = the LIVEDB half of a suite's db needs — the shared prep cluster its peers query — is woken
+ *         separately by `useWakeOfLivedb` in globalSetup, per
+ *         `define.invariant.test-and-prep-reach-prep-peers` (both test and prep access reach prep).
+ */
+export const useWakeOfTestdb = (): void => {
+  // gate: does this service own a db? a declared databaseUserName in declapract.use.yml is the signal.
+  const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
+  const declapractUseContent = existsSync(declapractUsePath)
+    ? readFileSync(declapractUsePath, 'utf8')
+    : '';
+  const requiresTestDb = declapractUseContent.includes('databaseUserName');
+  if (!requiresTestDb) return;
+
+  // an own-db service without config/test.json cannot preflight — name the fix (author the config)
+  const testConfigPath = join(process.cwd(), 'config', 'test.json');
+  if (!existsSync(testConfigPath))
+    throw new ConstraintError(
+      'config/test.json not found but a databaseUserName is declared in declapract.use.yml — author config/test.json with the testdb tunnel + role',
+      { testConfigPath },
+    );
+
+  // a present-but-incomplete config fails loud, and names the exact keys the preflight needs
+  const testConfig = JSON.parse(readFileSync(testConfigPath, 'utf8'));
+  if (
+    !testConfig.database?.tunnel?.local ||
+    !testConfig.database?.role?.crud ||
+    !testConfig.database?.target?.database
+  )
+    throw new ConstraintError(
+      'config/test.json lacks an expected key — declare database.tunnel.local, database.role.crud, and database.target.database',
+      {
+        hasTunnelLocal: !!testConfig.database?.tunnel?.local,
+        hasRoleCrud: !!testConfig.database?.role?.crud,
+        hasTargetDatabase: !!testConfig.database?.target?.database,
+      },
+    );
+
+  // preflight the testdb; probeTestDb surfaces psql's own stderr on failure (never a swallowed
+  // error) and passes PGPASSWORD via env, never the command args
+  probeTestDb({
+    host: testConfig.database.tunnel.local.host,
+    port: testConfig.database.tunnel.local.port,
+    username: testConfig.database.role.crud.username,
+    password: testConfig.database.role.crud.password,
+    database: testConfig.database.target.database,
+  });
+};

package/dist/practices/tests-node/livedb-wake-branches.declapract.integration.test.ts

@@ -0,0 +1,227 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = executes the REAL shipped `useWakeOfLivedb` template through its deterministic
+ *         decide-gate branches, with every boundary (fs, child_process, env) injected — so
+ *         the wake's actual logic runs, not a source-text pin of it.
+ * .why  = `livedb-wake-globalsetup.declapract.integration.test.ts` pins the wake by SOURCE TEXT
+ *         (it `.toContain`s `process.env.CI`, `=== 'prod'`, `.database?.tunnel`, …). a logic
+ *         bug that keeps those tokens — an inverted gate, a swallowed timeout, a classifier that
+ *         rethrows every failure — sails through every pin green. the decide-steps are pure
+ *         state decisions (ci-skip, prod-skip, tunnel present/absent, parse-failure throw) and
+ *         the failure classifier is a pure allowlist, so they run for real here with no live
+ *         infra — the repo's own `runTargetSlug`/`probeTestDb` pattern.
+ * .the-invariant = each gate lets the wake through ONLY when it should: not-ci ∧ not-prod ∧
+ *         reaches-cluster. a config the consumer authored but the setup cannot parse throws
+ *         (never a silent false). a wake-command failure is tolerated loud; a non-child-process
+ *         error is rethrown.
+ * .teeth = invert any gate in the template (drop the ci return, the prod return, the tunnel
+ *          gate) and the matched case reddens — a caller reaches the cluster it must not, or
+ *          skips one it must. drop the parse-failure throw and the malformed-config case
+ *          reddens. widen the classifier to rethrow-none and the non-child-process case reddens.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped template off
+ *         the filesystem. no network, no real subprocess — the child_process boundary is stubbed,
+ *         so the deployed cluster is never touched. it sits at the PRACTICE ROOT (not under
+ *         `best-practice/`), because declapract's compile strips `.declapract.test.ts` (+ `.snap`)
+ *         but NOT `.declapract.integration.test.ts` — so an integration clamp collocated inside
+ *         `best-practice/` would SHIP to a consumer and apply as an EQUALS template until
+ *         ehmpathy/declapract#109 lands. the practice-root home keeps it out of the emission set
+ *         while it still clamps the shipped template by path (`rule.require.declapract-integration-tests`).
+ */
+
+const SOURCE_PATH = `${__dirname}/best-practice/src/.test/useWakeOfLivedb.ts`;
+
+/**
+ * .what = transpile the template to CommonJS + execute its sole export with every boundary
+ *         stubbed, then report what crossed each boundary (the exec calls, the stderr warns).
+ * .why  = the template imports `node:fs`, `node:child_process`, `node:path`, `helpful-errors`;
+ *         a require-stub feeds each a controlled fake so the real decide-logic runs against
+ *         inputs this test dictates, and the boundary effects are observed rather than performed.
+ */
+const runUseWakeOfLivedb = async (input: {
+  env: 'test' | 'prep' | 'prod' | null;
+  ci: boolean;
+  configText: string | null; // null = the config file is absent
+  wakeThrows?: unknown; // when set, the stubbed execSync throws this
+}): Promise<{ execCalls: string[]; stderr: string[] }> => {
+  const source = readFileSync(SOURCE_PATH, 'utf8');
+  const transpiled = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+    },
+  }).outputText;
+
+  const execCalls: string[] = [];
+  const stderr: string[] = [];
+
+  class FakeConstraintError extends Error {
+    public readonly cause: unknown;
+    constructor(message: string, meta?: { cause?: unknown }) {
+      super(message);
+      this.name = 'ConstraintError';
+      this.cause = meta?.cause;
+    }
+  }
+
+  const requireStub = (id: string): unknown => {
+    if (id === 'node:child_process')
+      return {
+        execSync: (cmd: string): void => {
+          execCalls.push(cmd);
+          if (input.wakeThrows !== undefined) throw input.wakeThrows;
+        },
+      };
+    if (id === 'node:fs')
+      return {
+        existsSync: (): boolean => input.configText !== null,
+        readFileSync: (): string => input.configText ?? '',
+      };
+    if (id === 'node:path')
+      return { join: (...parts: string[]): string => parts.join('/') };
+    if (id === 'helpful-errors') return { ConstraintError: FakeConstraintError };
+    return {};
+  };
+
+  const moduleExports: Record<
+    string,
+    (i: { env: 'test' | 'prep' | 'prod' | null }) => Promise<void>
+  > = {};
+
+  // control the two process globals the template reads, and capture its stderr warns
+  const priorCi = process.env.CI;
+  if (input.ci) process.env.CI = '1';
+  else delete process.env.CI;
+  const priorWrite = process.stderr.write.bind(process.stderr);
+  (process.stderr as unknown as { write: (s: string) => boolean }).write = (
+    s: string,
+  ): boolean => {
+    stderr.push(s);
+    return true;
+  };
+
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function('exports', 'require', transpiled)(moduleExports, requireStub);
+    await moduleExports.useWakeOfLivedb!({ env: input.env });
+  } finally {
+    (process.stderr as unknown as { write: (s: string) => boolean }).write =
+      priorWrite as never;
+    if (priorCi === undefined) delete process.env.CI;
+    else process.env.CI = priorCi;
+  }
+
+  return { execCalls, stderr };
+};
+
+const TUNNEL_CONFIG = '{"database":{"tunnel":{"lambda":{"host":"x"}}}}';
+
+describe('the useWakeOfLivedb decide-gate runs its real branches (executed, no live infra)', () => {
+  given('a service that reaches the shared cluster (config declares a db tunnel)', () => {
+    when('the caller is not in ci and targets prep', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the cluster via the rhx skill for that access', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the target access is null (defaults to prep)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: null, ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the prep cluster by default', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the run is in ci', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: true, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (ci wakes via the dedicated workflow step)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('the target access is prod', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prod', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (prod never scales to 0)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a service that reaches no shared cluster', () => {
+    when('its config is absent', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: null }),
+      );
+      then('it does NOT wake (no known cluster)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('its config declares no db tunnel', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: '{"database":{}}' }),
+      );
+      then('it does NOT wake (no reaches-cluster signal)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a config the consumer authored but the setup cannot parse', () => {
+    when('the wake gate reads it', () => {
+      then('it throws a ConstraintError that names the parse failure (never a silent false)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: '{ not: valid json',
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('could not parse');
+      });
+    });
+  });
+
+  given('the wake command fails', () => {
+    when('it fails with a child-process shape (a non-zero exit)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: { status: 1 },
+        }),
+      );
+      then('it tolerates the failure (non-fatal) and warns loud to stderr', () => {
+        expect(state.stderr.length).toBe(1);
+      });
+      then('the wake-failure warn matches snapshot', () => {
+        expect(state.stderr[0]).toMatchSnapshot('useWakeOfLivedb wake-failure warn');
+      });
+    });
+
+    when('it fails with a NON-child-process shape (a code malfunction)', () => {
+      then('it rethrows, never warns it away (rule.forbid.failhide)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: new Error('a real bug in this module'),
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe('a real bug in this module');
+      });
+    });
+  });
+});

package/dist/practices/tests-node/livedb-wake-prepare.declapract.integration.test.ts

@@ -0,0 +1,112 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #598: the two node suite configs COMPOSE the livedb wake with autoprune in ONE
+ *         globalSetup, in the right order, forward globalConfig -- and useWakeOfLivedb self-gates
+ *         so a service that reaches no cluster is a no-op.
+ * .why  = a gateway/fan-out service owns no db but invokes peers that query the shared prep
+ *         aurora-serverless cluster; at min-capacity 0 the cluster auto-pauses, so the first query
+ *         cold-starts past the 90s timeout and flakes the suite. the fix wakes the cluster before
+ *         the suite runs. jest allows ONE globalSetup, so the wake must COMPOSE with test-fns
+ *         autoprune (which also needs that hook) -- never REPLACE it. the trap the downstream
+ *         hand-fix fell into: `globalSetup: './jest.acceptance.prepare.ts'` that called only
+ *         the wake, a silent drop of autoprune (the #590 half-wired state). this clamp forbids
+ *         that: the composite must reach BOTH, wake FIRST, and forward globalConfig to autoprune
+ *         (test-fns reads its globalTeardown slot; a dropped arg falsely accuses a wired consumer).
+ * .teeth = drop the useWakeOfLivedb call, the autoprune forward, or the order from a composite and
+ *          the matched case reddens; weaken a useWakeOfLivedb self-gate (CI / prod / tunnel) and its
+ *          case reddens.
+ * .note = subject is the shipped TEMPLATE text, read as a string. this file sits at the PRACTICE
+ *         root (not under `best-practice/`), so declapract's loader — which walks only
+ *         `best-practice/` for templates — never reads it as a declaration and never copies it to a
+ *         consumer (`define.declapract-test-files`). that is why a source-text clamp lives here
+ *         rather than collocated: it spans SEVERAL files, so it is not a single-file clamp.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different
+// cwd, and a repo-root-relative path under process.cwd() would then miss the tree (vacuous green).
+const P = join(__dirname, 'best-practice');
+
+const read = (rel: string): string => readFileSync(join(P, rel), 'utf8');
+
+const composites = [
+  { config: 'jest.integration.config.ts', setup: 'jest.integration.prepare.ts' },
+  { config: 'jest.acceptance.config.ts', setup: 'jest.acceptance.prepare.ts' },
+];
+
+describe('#598 livedb-wake composite globalSetup', () => {
+  for (const { config, setup } of composites) {
+    given(`[case] ${setup}`, () => {
+      const setupContents = read(setup);
+      const configContents = read(config);
+
+      when('[t0] the config is read', () => {
+        then(`it points globalSetup at ./${setup}`, () => {
+          expect(configContents).toContain(`globalSetup: './${setup}'`);
+        });
+      });
+
+      when('[t1] the composite globalSetup is read', () => {
+        then('it imports useWakeOfLivedb by RELATIVE path (not the @src alias)', () => {
+          // a globalSetup loads before jest moduleNameMapper, so @src fails at startup
+          expect(setupContents).toContain("from './src/.test/useWakeOfLivedb'");
+        });
+
+        then('it awaits useWakeOfLivedb (resume the cluster)', () => {
+          expect(setupContents).toContain('await useWakeOfLivedb(');
+        });
+
+        then('it forwards globalConfig to the autoprune setup', () => {
+          expect(setupContents).toContain('await autopruneSetup(globalConfig)');
+        });
+
+        then('it wakes BEFORE autoprune mints the run id (order)', () => {
+          const wakeAt = setupContents.indexOf('await useWakeOfLivedb(');
+          const pruneAt = setupContents.indexOf('await autopruneSetup(');
+          expect(wakeAt).toBeGreaterThanOrEqual(0);
+          expect(pruneAt).toBeGreaterThan(wakeAt);
+        });
+      });
+    });
+  }
+
+  given('[case] useWakeOfLivedb.ts self-gates', () => {
+    const wakeContents = read('src/.test/useWakeOfLivedb.ts');
+
+    when('[t0] the wake util is read', () => {
+      then('it skips in ci (ci wakes via the dedicated workflow step)', () => {
+        expect(wakeContents).toContain('process.env.CI');
+      });
+
+      then('it skips prod (prod never scales to 0)', () => {
+        expect(wakeContents).toContain("=== 'prod'");
+      });
+
+      then('it gates on a declared db tunnel (the reaches-cluster signal)', () => {
+        expect(wakeContents).toContain('.database?.tunnel');
+      });
+
+      then('it wakes via the rhx use.rds.capacity skill', () => {
+        expect(wakeContents).toContain('rhx use.rds.capacity --env');
+      });
+
+      then('a present-but-unparseable config fails loud, never a silent false (rule.forbid.failhide)', () => {
+        // a config the consumer authored but the setup cannot parse is a real defect, not "no
+        // cluster" — it throws a ConstraintError that names the file, rather than a silent false
+        // that conflates a broken config with an absent tunnel.
+        // teeth: silent-false the catch (drop the throw) and both substrings vanish → reddens.
+        expect(wakeContents).toContain('ConstraintError');
+        expect(wakeContents).toContain('could not parse');
+      });
+
+      then('the read-parse-decide is a named transformer, not inline in the wake (rule.require.named-transformers)', () => {
+        // the neighbor-config read + tunnel decision is one named intent, so the wake orchestrator
+        // reads what-not-how. teeth: inline the parse back into useWakeOfLivedb and this reddens.
+        expect(wakeContents).toContain('asReachesSharedClusterFromConfig');
+      });
+    });
+  });
+});