declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/tests-node/best-practice/jest.acceptance.config.ts

@@ -29,7 +29,17 @@ const config: Config = {
     // here's an example of how to ignore esm module transformation, when needed
     // 'node_modules/(?!(@octokit|universal-user-agent|before-after-hook)/)',
   ],
-  testMatch: ['**/*.acceptance.test.ts', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  testMatch: [
+    '**/*.acceptance.test.ts',
+    '**/*._.acpt.test.ts', // the `._.` kind seam; both suffix forms match
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;

package/dist/practices/tests-node/best-practice/jest.acceptance.env.ts

@@ -5,7 +5,7 @@ import util from 'node:util';
 import { jest } from '@jest/globals';
 import { ConstraintError } from 'helpful-errors';
 
-import { useKeyrack } from './src/.test/useKeyrack';
+import { useTestdbPortOverride } from './src/.test/assets/database/useTestdbPortOverride';
 
 jest.setTimeout(90000); // we're calling downstream apis
 
@@ -23,14 +23,24 @@ if (!existsSync(join(process.cwd(), 'package.json')))
   );
 
 /**
- * .what = source credentials from keyrack for the target tier and export them for the aws-sdk-v2
- *         lambda caller, in one call.
+ * .what = align CONFIG with ACCESS, before any test imports the environment.
  * .why =
- *   - a cloud acceptance run targets a deployed tier (e.g. prep), derived from ACCESS; default to the
- *     lowest-privilege `test` when unset, so a PR / local in-process run stays on test creds.
- *   - useKeyrack is the org convention: it sources keyrack (sets AWS_PROFILE), sets ACCESS, and — for
- *     an aws consumer — exports the sso profile's static creds so aws-sdk-v2 auths against the target
- *     (keyrack.source alone sets only AWS_PROFILE, which v2 cannot use). #586.
- *   - `strict` fails fast with a helpful error if keyrack is locked or a key is absent.
+ *   - jest forces NODE_ENV=test, and sdk-environment derives config from NODE_ENV before access.
+ *     so a cloud run with ACCESS=prep still read config/test.json, and a request built from config
+ *     (e.g. a twilio signature) failed with prep access.
+ *   - `envStatic` caches at first import, so the alignment must land here, per worker, before the
+ *     first test imports `src/utils/environment`.
+ *   - an in-process run (LOCALLY=true) holds no ACCESS, so it stays on `test`. a cloud run with no
+ *     ACCESS never reaches here: jest.acceptance.prepare.ts stops it first.
+ * .note = keyrack is sourced once per run in jest.acceptance.prepare.ts, not here.
  */
-useKeyrack({ env: (process.env.ACCESS ?? 'test') as 'test' | 'prep' | 'prod', mode: 'strict' });
+const access = process.env.ACCESS ?? 'test';
+process.env.ACCESS = access;
+process.env.CONFIG = access;
+
+/**
+ * .what = declare this checkout's testdb port as TESTDB_PORT, for an in-process run with test access.
+ * .why = an in-process run opens the local testdb from this worker; a worktree's testdb binds a port
+ *        of its own, which the app dials only under test access. prep and prod access never read it.
+ */
+if (access === 'test') useTestdbPortOverride();

package/dist/practices/tests-node/best-practice/jest.acceptance.prepare.ts

@@ -1,36 +1,51 @@
 import autopruneSetup from 'test-fns/autoprune.setup.jest';
 
+import { getOneKeyrackEnvForAcceptance, useKeyrack } from './src/.test/useKeyrack';
 import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
 
 /**
  * .what = jest globalSetup for the acceptance suite — runs once, in the main process, before
  *         jest forks its workers.
  * .why =
- *   - COMPOSES two setups that both need this one hook: the livedb wake (resume the shared
- *     aurora-serverless cluster so the first query does not cold-start past the timeout) and
- *     test-fns autoprune (mint this run's id BEFORE the first fork, so genTempDir dirs are
- *     reclaimed). jest allows ONE globalSetup, so a service that needs both must compose them
- *     here rather than pick one — a bare `globalSetup: 'test-fns/autoprune.setup.jest'` (the
- *     shipped default) leaves the db un-woken, and a bare wake setup drops autoprune (every dir
- *     stamped, none reclaimed — the #590 half-wired state).
+ *   - COMPOSES three setups that each need this one hook: the livedb wake (resume the shared
+ *     aurora-serverless cluster so the first query does not cold-start past the timeout), the
+ *     keyrack source (credentials for the run's access), and test-fns autoprune (mint this run's id
+ *     BEFORE the first fork, so genTempDir dirs are reclaimed). jest allows ONE globalSetup, so a
+ *     service that needs all three must compose them here rather than pick one — a bare
+ *     `globalSetup: 'test-fns/autoprune.setup.jest'` (the shipped default) leaves the db un-woken,
+ *     and a bare wake setup drops autoprune (every dir stamped, none reclaimed — the
+ *     half-wired state).
  *   - the acceptance suites invoke deployed lambdas that proxy to peers which query the shared
  *     cluster; a paused cluster cold-starts past the timeout and flakes the quote suites. wake
  *     it once here (not per-file — env setup runs per worker), so the first real query lands warm.
- *   - the wake runs FIRST (best-effort, self-gated on a declared db tunnel — a no-op for a
- *     service that reaches no cluster), THEN autoprune mints the run id.
+ *   - the target access is named FIRST: a cloud run with no ACCESS and no LOCALLY=true stops at
+ *     once with the fix, rather than source the test keyrack over a prep target and hang.
+ *   - then the wake (best-effort, self-gated on a declared db tunnel), THEN keyrack, THEN autoprune
+ *     mints the run id. keyrack after the wake, so the run's access creds never leak into the
+ *     `rhx use.rds.capacity --env prep` call the wake makes.
+ *   - keyrack is sourced ONCE per run here, not once per suite file in the env file. jest
+ *     forks its workers after globalSetup, so each worker inherits the env it sets.
  *   - `globalConfig` is FORWARDED to autoprune unchanged: test-fns reads its `globalTeardown`
  *     slot to detect the half-wired state, and a dropped/defaulted arg would falsely accuse a
  *     correctly-wired consumer (see test-fns autoprune.setup.jest .note).
- * .note = `useWakeOfLivedb` is imported by RELATIVE path, never the `@src` alias — a globalSetup is
+ * .note = each util is imported by RELATIVE path, never the `@src` alias — a globalSetup is
  *         loaded by node's plain require BEFORE jest's moduleNameMapper exists, so `@src` here
  *         fails with `Cannot find module` and kills the run at startup (the same trap test-fns'
  *         own autoprune.setup.jest documents).
  */
 // biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
 export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
+  // name the target access, or stop with the fix
+  const access = getOneKeyrackEnvForAcceptance({ env: process.env });
+
   // the wake TARGET is always the prep cluster: a test-access AND a prep-access suite both fan out
-  // to the shared prep peer fleet (define.invariant.test-and-prep-reach-prep-peers), so 'prep' is
+  // to the shared prep peer fleet, so 'prep' is
   // the one cluster either access reaches; only prod is self-contained and never woken.
-  await useWakeOfLivedb({ env: 'prep' });
+  await useWakeOfLivedb({ env: 'prep', reaches: 'via-tunnel' });
+
+  // source the credentials for the run's access once for the run; `strict` fails fast if keyrack
+  // is locked or a key is absent
+  useKeyrack({ env: access, mode: 'strict' });
+
   await autopruneSetup(globalConfig);
 };

package/dist/practices/tests-node/best-practice/jest.integration.config.ts

@@ -29,7 +29,17 @@ const config: Config = {
     // here's an example of how to ignore esm module transformation, when needed
     // 'node_modules/(?!(@octokit|universal-user-agent|before-after-hook)/)',
   ],
-  testMatch: ['**/*.integration.test.ts', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  testMatch: [
+    '**/*.integration.test.ts',
+    '**/*._.intg.test.ts', // the `._.` kind seam; both suffix forms match
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.integration.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;

package/dist/practices/tests-node/best-practice/jest.integration.env.db.ts

@@ -58,6 +58,8 @@ export const probeTestDb = (
     );
   } catch (error) {
     // surface what psql actually said; a bare catch collapses every cause into one guess
+    // .note = a documented cast: node types a caught value as unknown, and execFileSync's error
+    //         carries `stderr` as a Buffer (piped above); the `'stderr' in error` guard proves the key
     const said =
       error && typeof error === 'object' && 'stderr' in error
         ? String((error as { stderr?: Buffer }).stderr ?? '').trim()
@@ -84,7 +86,9 @@ export const probeTestDb = (
         '',
         fix,
       ].join('\n'),
-      { cause: error },
+      // a catch binds `unknown` under strictest, and `cause` is typed `Error`; narrow, never cast,
+      // so a non-Error throw is re-homed into an Error rather than dropped
+      { cause: error instanceof Error ? error : new Error(String(error)) },
     );
   }
 };

package/dist/practices/tests-node/best-practice/jest.integration.env.ts

@@ -5,7 +5,7 @@ import util from 'node:util';
 import { jest } from '@jest/globals';
 import { ConstraintError } from 'helpful-errors';
 
-import { useKeyrack } from './src/.test/useKeyrack';
+import { useTestdbPortOverride } from './src/.test/assets/database/useTestdbPortOverride';
 import { useWakeOfTestdb } from './src/.test/useWakeOfTestdb';
 
 jest.setTimeout(90000); // since we're calling downstream apis
@@ -41,20 +41,17 @@ if (
   );
 
 /**
- * .what = source credentials from keyrack for the test tier and export them for the aws-sdk-v2
- *         lambda caller, in one call.
- * .why = useKeyrack is the org convention: it sources keyrack (sets AWS_PROFILE) and — for an aws
- *        consumer — exports the sso profile's static creds so aws-sdk-v2 auths against the target
- *        (aws-sdk v2 cannot use an sso profile, and prefers AWS_PROFILE over static creds when both
- *        are set, so the shared guard removes AWS_PROFILE after the splice). #586.
+ * .what = declare this checkout's testdb port as TESTDB_PORT, before any test opens a connection.
+ * .why = a worktree's testdb binds a port of its own; the app dials TESTDB_PORT under test access,
+ *        so a worktree's suite reaches its own db, never another checkout's.
  */
-useKeyrack({ env: 'test' });
+useTestdbPortOverride();
 
 /**
  * .what = preflight the LOCAL testdb when this service declares its own db (databaseUserName).
  * .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; useWakeOfTestdb fails loud and names
  *        the fix. it is the LOCAL own-db half; the shared prep cluster its peers query is woken by
- *        useWakeOfLivedb in globalSetup (define.invariant.test-and-prep-reach-prep-peers).
+ *        useWakeOfLivedb in globalSetup, since both test and prep access reach the prep peers.
  */
 useWakeOfTestdb();

package/dist/practices/tests-node/best-practice/jest.integration.env.ts.declapract.ts

@@ -0,0 +1,82 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import {
+  defineExpectedContentsWithUsecaseInserts,
+  type UsecaseInsert,
+} from '../../../utils/defineExpectedContentsWithUsecaseInserts';
+
+/**
+ * .what = the `jest.integration.env.ts` tests-node declares, usecase-aware for persist-with-dynamodb
+ * .why  = tests-node is the one owner of this file (#630). a dynamodb service also needs its
+ *         integration suite pointed at the local dynamodb container, so the dynamodb delta rides
+ *         here as two inserts — a relative `access` import and the endpoint assignment — rather
+ *         than as a second declaration of the same file (rule.avoid.runtime-forks).
+ * .why  = a FINDSERT, never EQUALS: the base must still equal the template, but the dynamodb
+ *         inserts, once present, are kept under every scope — so a narrow
+ *         `declapract apply --practice tests-node`, where persist-with-dynamodb goes dark from
+ *         `context.projectPractices`, never strips them.
+ * .note = the import is RELATIVE: a jest env loads before moduleNameMapper settles the `@src` alias.
+ */
+export const DYNAMODB_INSERTS: UsecaseInsert[] = [
+  {
+    after: "import { useWakeOfTestdb } from './src/.test/useWakeOfTestdb';",
+    text: "\nimport { access } from './src/utils/environment';",
+  },
+  {
+    after: 'useWakeOfTestdb();',
+    text: [
+      '',
+      '',
+      '/**',
+      ' * .what = point dynamodb at the local dynamodb container, under the test access',
+      ' * .why = a dynamodb suite must never reach a live table',
+      ' */',
+      "if (access === 'test')",
+      "  process.env.USE_CUSTOM_DYNAMODB_ENDPOINT = 'http://localhost:7337';",
+    ].join('\n'),
+  },
+];
+
+/**
+ * .what = the contents this declaration expects, for the repo's extant file and usecase
+ */
+const defineExpectedContents = (input: {
+  contents: string | null;
+  declared: string;
+  projectPractices: string[];
+}): string =>
+  defineExpectedContentsWithUsecaseInserts({
+    contents: input.contents,
+    declared: input.declared,
+    inserts: DYNAMODB_INSERTS,
+    usecaseInScope: input.projectPractices.includes('persist-with-dynamodb'),
+  });
+
+/**
+ * .what = throws when the repo's env file differs from the declared base + its owed inserts
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  const expected = defineExpectedContents({
+    contents,
+    declared: context.declaredFileContents ?? '',
+    projectPractices: context.projectPractices,
+  });
+  if (contents !== expected)
+    throw new ConstraintError(
+      'jest.integration.env.ts differs from the declared template (plus its usecase inserts)',
+      { relativeFilePath: context.relativeFilePath },
+    );
+};
+
+/**
+ * .what = writes the declared base, plus the dynamodb inserts when owed or already present
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its output.
+ */
+export const fix: FileFixFunction = (contents, context) => ({
+  contents: defineExpectedContents({
+    contents,
+    declared: context.declaredFileContents ?? '',
+    projectPractices: context.projectPractices,
+  }),
+});

package/dist/practices/tests-node/best-practice/jest.integration.prepare.ts

@@ -1,24 +1,30 @@
 import autopruneSetup from 'test-fns/autoprune.setup.jest';
 
+import { useKeyrack } from './src/.test/useKeyrack';
 import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
 
 /**
  * .what = jest globalSetup for the integration suite — runs once, in the main process, before
  *         jest forks its workers.
  * .why =
- *   - COMPOSES two setups that both need this one hook: the livedb wake (resume the shared
- *     aurora-serverless cluster so the first query does not cold-start past the timeout) and
- *     test-fns autoprune (mint this run's id BEFORE the first fork, so genTempDir dirs are
- *     reclaimed). jest allows ONE globalSetup, so a service that needs both must compose them
- *     here rather than pick one — a bare `globalSetup: 'test-fns/autoprune.setup.jest'` (the
- *     shipped default) leaves the db un-woken, and a bare wake setup drops autoprune (every dir
- *     stamped, none reclaimed — the #590 half-wired state).
+ *   - COMPOSES three setups that each need this one hook: the livedb wake (resume the shared
+ *     aurora-serverless cluster so the first query does not cold-start past the timeout), the
+ *     keyrack source (credentials for test access), and test-fns autoprune (mint this run's id
+ *     BEFORE the first fork, so genTempDir dirs are reclaimed). jest allows ONE globalSetup, so a
+ *     service that needs all three must compose them here rather than pick one — a bare
+ *     `globalSetup: 'test-fns/autoprune.setup.jest'` (the shipped default) leaves the db un-woken,
+ *     and a bare wake setup drops autoprune (every dir stamped, none reclaimed — the
+ *     half-wired state).
  *   - the wake runs FIRST (best-effort, self-gated on a declared db tunnel — a no-op for a
- *     service that reaches no cluster), THEN autoprune mints the run id.
+ *     service that reaches no cluster), THEN keyrack, THEN autoprune mints the run id. keyrack
+ *     after the wake, so the test-access creds never leak into the `rhx use.rds.capacity --env
+ *     prep` call the wake makes.
+ *   - keyrack is sourced ONCE per run here, not once per suite file in the env file (~25s each).
+ *     jest forks its workers after globalSetup, so each worker inherits the env it sets.
  *   - `globalConfig` is FORWARDED to autoprune unchanged: test-fns reads its `globalTeardown`
  *     slot to detect the half-wired state, and a dropped/defaulted arg would falsely accuse a
  *     correctly-wired consumer (see test-fns autoprune.setup.jest .note).
- * .note = `useWakeOfLivedb` is imported by RELATIVE path, never the `@src` alias — a globalSetup is
+ * .note = each util is imported by RELATIVE path, never the `@src` alias — a globalSetup is
  *         loaded by node's plain require BEFORE jest's moduleNameMapper exists, so `@src` here
  *         fails with `Cannot find module` and kills the run at startup (the same trap test-fns'
  *         own autoprune.setup.jest documents).
@@ -26,8 +32,13 @@ import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
 // biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
 export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
   // the wake TARGET is always the prep cluster: a test-access AND a prep-access suite both fan out
-  // to the shared prep peer fleet (define.invariant.test-and-prep-reach-prep-peers), so 'prep' is
+  // to the shared prep peer fleet, so 'prep' is
   // the one cluster either access reaches; only prod is self-contained and never woken.
-  await useWakeOfLivedb({ env: 'prep' });
+  await useWakeOfLivedb({ env: 'prep', reaches: 'via-tunnel' });
+
+  // source the test-access credentials once for the run; useKeyrack bars the ec2 metadata
+  // service under declared aws auth, so the instance role cannot stand in
+  useKeyrack({ env: 'test' });
+
   await autopruneSetup(globalConfig);
 };

package/dist/practices/tests-node/best-practice/jest.unit.config.ts

@@ -30,12 +30,21 @@ const config: Config = {
   ],
   testMatch: [
     // note: order matters
-    '**/*.test.ts',
+    '**/*.test.ts', // also matches the `._.unit.test` kind seam
     '!**/*.acceptance.test.ts',
     '!**/*.integration.test.ts',
+    '!**/*.evaluation.test.ts',
+    '!**/*._.acpt.test.ts',
+    '!**/*._.intg.test.ts',
+    '!**/*._.eval.test.ts',
+    '!**/.agent/.actors/**', // rhachet host-local state; holds a scratch clone of this repo, whose suites are not ours
     '!**/.agent/.cache/**',
     '!**/.yalc/**',
   ],
+  // skip all of `.agent/`: rhachet roles, host-local clones, and the rmsafe trash live there. a test
+  // there would run as ours, and a snapshot there would read as obsolete (the haste map scans it)
+  testPathIgnorePatterns: ['/node_modules/', '/.agent/'],
+  modulePathIgnorePatterns: ['<rootDir>/.agent/'],
   setupFilesAfterEnv: ['./jest.unit.env.ts'],
 
   // reclaim every temp dir genTempDir made this run (test-fns autoprune; needs test-fns >=1.16,

package/dist/practices/tests-node/best-practice/jest.unit.env.ts

@@ -34,6 +34,6 @@ if (!existsSync(join(process.cwd(), 'package.json')))
  */
 if (access !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
   throw new ConstraintError(
-    `unit tests must target the 'test' tier — set I_KNOW_THE_RISKS=true to override`,
+    `unit tests must run with 'test' access — set I_KNOW_THE_RISKS=true to override`,
     { access },
   );

package/dist/practices/tests-node/best-practice/jest.unit.env.ts.declapract.ts

@@ -6,11 +6,29 @@ import { FileCheckType } from 'declapract';
 import { readFile } from '../../../utils/readFile';
 
 /**
- * .what = declare the jest unit-env file, with the config mock block included only when the
- *         `config` practice is in play for the project.
+ * .what = the `access` import the template carries, emitted only with the `environments` practice
+ */
+const ACCESS_IMPORT = `import { access } from './src/utils/environment';`;
+
+/**
+ * .what = the `access` derivation emitted in place of the import, when `environments` is absent
+ * .why  = sdk-environment reads `ACCESS`; jest sets `NODE_ENV=test` when unset — so the guard
+ *         still passes by default and still blocks a suite run with `ACCESS=prod`.
+ */
+const ACCESS_FROM_ENVARS = `// the access this suite runs with — the ACCESS envar, else jest's own NODE_ENV
+const access = process.env.ACCESS ?? process.env.NODE_ENV;`;
+
+/**
+ * .what = declare the jest unit-env file, narrowed to the practices in play for the project:
+ *         - the config mock block only when the `config` practice is in play
+ *         - the `access` import only when the `environments` practice is in play
  * .why  = the mock stubs `getConfig` to return plaintext test config; a project WITHOUT the
  *         `config` practice has no such module to mock, so the stub would reference a file that is
- *         absent. a branch on `context.projectPractices` lets one practice serve both.
+ *         absent. likewise `src/utils/environment` is emitted only by `environments`, so without it
+ *         the import is TS2307 — `access` is derived from the envars instead. a branch on
+ *         `context.projectPractices` lets one practice serve every usecase (rule.avoid.runtime-forks).
+ * .note = check is CONTAINS: an extant file is never rewritten (declapract only creates an absent
+ *         one), so a narrow `--practice tests-node` apply that darkens `environments` strips naught.
  */
 export const contents: FileContentsFunction = async (context) => {
   // grab the superset of best practices content
@@ -19,7 +37,7 @@ export const contents: FileContentsFunction = async (context) => {
   });
 
   // remove the config mock block when the config practice is absent — immutable const, no reassign
-  const contents = context.projectPractices.includes('config')
+  const contentsForConfig = context.projectPractices.includes('config')
     ? contentsSuperset
     : contentsSuperset.replace(
         `// mock that getConfig just returns plaintext test env config in unit tests
@@ -31,8 +49,15 @@ jest.mock('./src/utils/config/getConfig', () => ({
         '',
       );
 
+  // derive access from the envars when the environments practice is absent
+  const contentsForEnvironments = context.projectPractices.includes(
+    'environments',
+  )
+    ? contentsForConfig
+    : contentsForConfig.replace(ACCESS_IMPORT, ACCESS_FROM_ENVARS);
+
   // return the narrowed contents
-  return contents;
+  return contentsForEnvironments;
 };
 
 /**

package/dist/practices/tests-node/best-practice/src/.test/assets/database/useTestdbPortOverride.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = declare this checkout's testdb port as TESTDB_PORT, for the app under test to dial
+ * .why = persist-with-rds gives each worktree a testdb on a port of its own. the app reads that
+ *        port from TESTDB_PORT, and only with test access, so the harness must declare it before
+ *        a test opens a connection — else a worktree's suite dials the declared port and reads
+ *        another checkout's db
+ * .note = the port comes from persist-with-rds's `src/.test/assets/database/getTestdbPort`, the
+ *         same helper the compose file and the schema provisioner ask. tests-node also serves repos
+ *         without persist-with-rds, so the helper is read at runtime where present, never imported;
+ *         absent, this declares naught and the app dials its declared port
+ */
+export const useTestdbPortOverride = (): void => {
+  // without the persist-with-rds helper, there is no per-worktree port to declare
+  const helperPath = join(
+    process.cwd(),
+    'src',
+    '.test',
+    'assets',
+    'database',
+    'getTestdbPort.ts',
+  );
+  if (!existsSync(helperPath)) return;
+
+  // a helper whose export drifted is a fault to name, never a bare TypeError
+  const helper: {
+    getTestdbPort?: (input: { access: string; portDeclared: number }) => number;
+  } = require(helperPath);
+  if (typeof helper.getTestdbPort !== 'function')
+    throw new ConstraintError(
+      'src/.test/assets/database/getTestdbPort.ts exports no getTestdbPort function',
+      {
+        helperPath,
+        hint: 'export `getTestdbPort({ access, portDeclared })` from that file, or run `npx declapract apply` to restore it',
+      },
+    );
+
+  // the declared port lives in config/test.json; persist-with-rds owes it, so its absence is loud
+  const testConfigPath = join(process.cwd(), 'config', 'test.json');
+  const portDeclared: unknown = existsSync(testConfigPath)
+    ? JSON.parse(readFileSync(testConfigPath, 'utf8')).database?.tunnel?.local
+        ?.port
+    : undefined;
+  if (typeof portDeclared !== 'number')
+    throw new ConstraintError(
+      'config/test.json declares no database.tunnel.local.port — the testdb port cannot be derived',
+      {
+        testConfigPath,
+        hint: 'declare database.tunnel.local.port in config/test.json, or run `npx declapract apply` to restore it',
+      },
+    );
+
+  // declare the port; the harness runs only with test access, which the app's override requires
+  process.env.TESTDB_PORT = String(
+    helper.getTestdbPort({ access: 'test', portDeclared }),
+  );
+};