declapract-typescript-ehmpathy 0.49.13 → 0.49.14

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

@@ -1,47 +1,75 @@
+import { spawnSync } from 'node:child_process';
 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.
+ * .what = clamps #598: the 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. extends the clamp to #623 (keyrack sourced once per
+ *         run, in the globalSetup, after the wake and before autoprune), #651 (the acceptance
+ *         prepare names its access or stops), #675 (the acceptance env aligns CONFIG with ACCESS),
+ *         and #621 (the expo configs wake via-gateway).
  * .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.
+ *         cold-starts past the 90s timeout and flakes the suite. jest allows ONE globalSetup, so the
+ *         wake must COMPOSE with test-fns autoprune -- never REPLACE it. keyrack moves into the same
+ *         hook so it is sourced once per run, not once per suite file (~25s each).
+ * .teeth = drop the useWakeOfLivedb call, the keyrack call, the autoprune forward, or the order from
+ *          a composite and the matched case reddens; put useKeyrack back in an env file and the
+ *          env case reddens; drop the CONFIG alignment and the acceptance env 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.
+ *         root (not under `best-practice/`), so declapract's loader never reads it as a declaration
+ *         (`define.declapract-test-files`). it spans several practices' 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 NODE = join(__dirname, 'best-practice');
+const EXPO = join(__dirname, '..', 'tests-expo', 'best-practice');
+const ANY = join(__dirname, '..', 'tests-any', 'best-practice');
 
-const read = (rel: string): string => readFileSync(join(P, rel), 'utf8');
+const read = (dir: string, rel: string): string => readFileSync(join(dir, rel), 'utf8');
 
 const composites = [
-  { config: 'jest.integration.config.ts', setup: 'jest.integration.prepare.ts' },
-  { config: 'jest.acceptance.config.ts', setup: 'jest.acceptance.prepare.ts' },
+  {
+    dir: NODE,
+    config: 'jest.integration.config.ts',
+    setup: 'jest.integration.prepare.ts',
+    reaches: 'via-tunnel',
+    keyrack: true,
+  },
+  {
+    dir: NODE,
+    config: 'jest.acceptance.config.ts',
+    setup: 'jest.acceptance.prepare.ts',
+    reaches: 'via-tunnel',
+    keyrack: true,
+  },
+  {
+    dir: EXPO,
+    config: 'jest.integration.config.ts',
+    setup: 'jest.integration.prepare.ts',
+    reaches: 'via-gateway',
+    keyrack: false,
+  },
+  {
+    dir: EXPO,
+    config: 'jest.acceptance.config.ts',
+    setup: 'jest.acceptance.prepare.ts',
+    reaches: 'via-gateway',
+    keyrack: false,
+  },
 ];
 
 describe('#598 livedb-wake composite globalSetup', () => {
-  for (const { config, setup } of composites) {
-    given(`[case] ${setup}`, () => {
-      const setupContents = read(setup);
-      const configContents = read(config);
+  for (const { dir, config, setup, reaches, keyrack } of composites) {
+    const label = dir === NODE ? 'tests-node' : 'tests-expo';
+    given(`[case] ${label} ${setup}`, () => {
+      const setupContents = read(dir, setup);
+      const configContents = read(dir, config);
 
       when('[t0] the config is read', () => {
         then(`it points globalSetup at ./${setup}`, () => {
@@ -55,8 +83,9 @@ describe('#598 livedb-wake composite globalSetup', () => {
           expect(setupContents).toContain("from './src/.test/useWakeOfLivedb'");
         });
 
-        then('it awaits useWakeOfLivedb (resume the cluster)', () => {
+        then(`it awaits useWakeOfLivedb ${reaches}`, () => {
           expect(setupContents).toContain('await useWakeOfLivedb(');
+          expect(setupContents).toContain(`reaches: '${reaches}'`);
         });
 
         then('it forwards globalConfig to the autoprune setup', () => {
@@ -69,12 +98,91 @@ describe('#598 livedb-wake composite globalSetup', () => {
           expect(wakeAt).toBeGreaterThanOrEqual(0);
           expect(pruneAt).toBeGreaterThan(wakeAt);
         });
+
+        if (keyrack)
+          then('it sources keyrack once, after the wake and before autoprune (#623)', () => {
+            expect(setupContents).toContain("from './src/.test/useKeyrack'");
+            const wakeAt = setupContents.indexOf('await useWakeOfLivedb(');
+            const keyrackAt = setupContents.indexOf('useKeyrack(');
+            const pruneAt = setupContents.indexOf('await autopruneSetup(');
+            expect(keyrackAt).toBeGreaterThan(wakeAt);
+            expect(pruneAt).toBeGreaterThan(keyrackAt);
+          });
       });
     });
   }
 
+  given('[case] the tests-node acceptance prepare names its access (#651)', () => {
+    const setupContents = read(NODE, 'jest.acceptance.prepare.ts');
+
+    then('it derives the keyrack env via getOneKeyrackEnvForAcceptance, never a silent default', () => {
+      expect(setupContents).toContain('getOneKeyrackEnvForAcceptance({ env: process.env })');
+      expect(setupContents).not.toContain("?? 'test'");
+    });
+
+    then('it sources keyrack strict', () => {
+      expect(setupContents).toContain("mode: 'strict'");
+    });
+  });
+
+  given('[case] the tests-node env files no longer source keyrack per suite file (#623)', () => {
+    for (const envFile of ['jest.integration.env.ts', 'jest.acceptance.env.ts'])
+      then(`${envFile} holds no useKeyrack call`, () => {
+        expect(read(NODE, envFile)).not.toContain('useKeyrack(');
+      });
+  });
+
+  given('[case] the tests-node acceptance env aligns CONFIG with ACCESS (#675)', () => {
+    const envContents = read(NODE, 'jest.acceptance.env.ts');
+
+    then('it sets ACCESS and CONFIG to one value', () => {
+      expect(envContents).toContain("const access = process.env.ACCESS ?? 'test';");
+      expect(envContents).toContain('process.env.ACCESS = access;');
+      expect(envContents).toContain('process.env.CONFIG = access;');
+    });
+
+    /**
+     * .what = run the template's alignment lines, then derive config through the real sdk-environment
+     * .why  = the string checks above prove the lines ship; this proves they WORK under jest's forced
+     *         NODE_ENV=test — sdk-environment reads CONFIG before NODE_ENV, and a change of that
+     *         order upstream would turn this red rather than ship a prep run on test config
+     */
+    const getOneConfigDerived = (input: { access: string; aligned: boolean }) => {
+      const alignment = input.aligned
+        ? "const access = process.env.ACCESS ?? 'test'; process.env.ACCESS = access; process.env.CONFIG = access;"
+        : '';
+      const { CONFIG: _config, ...envBase } = process.env;
+      // look up the path here, so the child loads this repo's pinned copy (and depcheck sees the dep)
+      const sdkEnvironmentPath = require.resolve('sdk-environment');
+      const result = spawnSync(
+        'node',
+        [
+          '-e',
+          `${alignment} const { getEnvironment } = require(${JSON.stringify(sdkEnvironmentPath)}); process.stdout.write(String(getEnvironment.static().config));`,
+        ],
+        {
+          encoding: 'utf-8',
+          env: { ...envBase, NODE_ENV: 'test', ACCESS: input.access },
+        },
+      );
+      return { status: result.status, config: result.stdout, stderr: result.stderr };
+    };
+
+    when('[t0] a cloud run with ACCESS=prep derives its config under NODE_ENV=test', () => {
+      then('the aligned env derives config prep', () => {
+        const result = getOneConfigDerived({ access: 'prep', aligned: true });
+        expect(result.stderr).toEqual('');
+        expect(result.config).toEqual('prep');
+      });
+
+      then('the unaligned env derives config test — the #675 defect the alignment closes', () => {
+        expect(getOneConfigDerived({ access: 'prep', aligned: false }).config).toEqual('test');
+      });
+    });
+  });
+
   given('[case] useWakeOfLivedb.ts self-gates', () => {
-    const wakeContents = read('src/.test/useWakeOfLivedb.ts');
+    const wakeContents = read(ANY, 'src/.test/useWakeOfLivedb.ts');
 
     when('[t0] the wake util is read', () => {
       then('it skips in ci (ci wakes via the dedicated workflow step)', () => {
@@ -85,7 +193,7 @@ describe('#598 livedb-wake composite globalSetup', () => {
         expect(wakeContents).toContain("=== 'prod'");
       });
 
-      then('it gates on a declared db tunnel (the reaches-cluster signal)', () => {
+      then('it gates a via-tunnel caller on a declared db tunnel (the reaches-cluster signal)', () => {
         expect(wakeContents).toContain('.database?.tunnel');
       });
 
@@ -94,19 +202,17 @@ describe('#598 livedb-wake composite globalSetup', () => {
       });
 
       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');
       });
+
+      then('the wake decision is a named, exported transformer (#621)', () => {
+        expect(wakeContents).toContain('export const getWakeDecision');
+      });
     });
   });
 });

package/dist/practices/tests-node/testdb-port-override.declapract.integration.test.ts

@@ -0,0 +1,184 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
+
+/**
+ * .what = executes the REAL shipped `useTestdbPortOverride` template through its branches, with
+ *         every boundary (fs, path, helpful-errors, the persist-with-rds port source) stubbed, and
+ *         pins that both jest envs call it where the app opens the local testdb in-process
+ * .why  = the app dials a worktree's testdb port only via the TESTDB_PORT this step declares. if
+ *         the step stops to declare it, a worktree's suite silently dials the declared port and
+ *         reads another checkout's db; if it declares a wrong port, every query fails far from cause
+ * .teeth = drop the absent-source early return and [case1] reddens (TESTDB_PORT set where no
+ *          per-worktree port exists); ask the source with a non-test access, or skip the assignment,
+ *          and [case2] reddens; drop either loud check and [case3]/[case4] redden; drop the call
+ *          from either jest env, or the acceptance env's test-access gate, and [case5] reddens
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped templates off
+ *         the filesystem. no real subprocess, no git — the port source is stubbed. it sits at the
+ *         PRACTICE ROOT so declapract never emits it (`rule.require.declapract-integration-tests`)
+ */
+
+const P = join(__dirname, 'best-practice');
+const SOURCE_PATH = join(
+  P,
+  'src/.test/assets/database/useTestdbPortOverride.ts',
+);
+const read = (rel: string): string => readFileSync(join(P, rel), 'utf8');
+
+type PortAsk = { access: string; portDeclared: number };
+
+/**
+ * .what = run the template once with its boundaries stubbed; report TESTDB_PORT after, the asks
+ *         the port source received, and any error thrown
+ */
+const runUseTestdbPortOverride = (input: {
+  portSource: 'absent' | 'present' | 'drifted';
+  testConfig: string | null; // null = the config/test.json file is absent
+}): { portDeclaredAfter: string | null; portAsks: PortAsk[]; error: Error | null } => {
+  const portAsks: PortAsk[] = [];
+
+  class FakeConstraintError extends Error {
+    constructor(message: string) {
+      super(message);
+      this.name = 'ConstraintError';
+    }
+  }
+
+  // decide which file a path refers to by its tail — the template joins cwd with a fixed name
+  const isPortSourcePath = (p: string): boolean =>
+    p.endsWith('src/.test/assets/database/getTestdbPort.ts');
+  const isConfigPath = (p: string): boolean => p.endsWith('config/test.json');
+
+  const requireStub = (id: string): unknown => {
+    if (isPortSourcePath(id) && input.portSource === 'present')
+      return {
+        getTestdbPort: (ask: PortAsk): number => {
+          portAsks.push(ask);
+          return ask.portDeclared + 77;
+        },
+      };
+    if (isPortSourcePath(id)) return {};
+    if (id === 'node:fs')
+      return {
+        existsSync: (p: string): boolean => {
+          if (isPortSourcePath(p)) return input.portSource !== 'absent';
+          return isConfigPath(p) && input.testConfig !== null;
+        },
+        readFileSync: (): string => input.testConfig ?? '',
+      };
+    if (id === 'node:path')
+      return { join: (...parts: string[]): string => parts.join('/') };
+    if (id === 'helpful-errors') return { ConstraintError: FakeConstraintError };
+    throw new Error(`unexpected require: ${id}`);
+  };
+
+  const { useTestdbPortOverride } = getModuleExportsFromTsSource<{
+    useTestdbPortOverride: () => void;
+  }>({ source: readFileSync(SOURCE_PATH, 'utf8'), requireStub });
+
+  // run against a clean TESTDB_PORT; restore the prior value after
+  const portOverridePrior = process.env.TESTDB_PORT;
+  delete process.env.TESTDB_PORT;
+  try {
+    useTestdbPortOverride!();
+    return {
+      portDeclaredAfter: process.env.TESTDB_PORT ?? null,
+      portAsks,
+      error: null,
+    };
+  } catch (caught) {
+    if (!(caught instanceof Error)) throw caught;
+    return { portDeclaredAfter: process.env.TESTDB_PORT ?? null, portAsks, error: caught };
+  } finally {
+    if (portOverridePrior === undefined) delete process.env.TESTDB_PORT;
+    if (portOverridePrior !== undefined)
+      process.env.TESTDB_PORT = portOverridePrior;
+  }
+};
+
+const COMPLETE_CONFIG = JSON.stringify({
+  database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+});
+
+describe('useTestdbPortOverride declares the testdb port the app dials', () => {
+  given('[case1] a repo without persist-with-rds (no port source)', () => {
+    when('[t0] the step runs', () => {
+      const result = useBeforeAll(async () =>
+        runUseTestdbPortOverride({ portSource: 'absent', testConfig: null }),
+      );
+      then('it declares naught, and never throws', () => {
+        expect(result.error).toEqual(null);
+        expect(result.portDeclaredAfter).toEqual(null);
+      });
+    });
+  });
+
+  given('[case2] a persist-with-rds repo with a complete config/test.json', () => {
+    when('[t0] the step runs', () => {
+      const result = useBeforeAll(async () =>
+        runUseTestdbPortOverride({
+          portSource: 'present',
+          testConfig: COMPLETE_CONFIG,
+        }),
+      );
+      then('it asks the port source with test access and the declared port', () => {
+        expect(result.portAsks).toEqual([{ access: 'test', portDeclared: 7821 }]);
+      });
+      then('it declares the per-worktree port as TESTDB_PORT', () => {
+        expect(result.error).toEqual(null);
+        expect(result.portDeclaredAfter).toEqual(String(7821 + 77));
+      });
+    });
+  });
+
+  given('[case3] a port source whose export drifted', () => {
+    when('[t0] the step runs', () => {
+      const result = useBeforeAll(async () =>
+        runUseTestdbPortOverride({
+          portSource: 'drifted',
+          testConfig: COMPLETE_CONFIG,
+        }),
+      );
+      then('it fails loud with a ConstraintError that names the export', () => {
+        expect(result.error?.name).toEqual('ConstraintError');
+        expect(result.error?.message).toContain('exports no getTestdbPort');
+        expect(result.portDeclaredAfter).toEqual(null);
+      });
+    });
+  });
+
+  given('[case4] a port source, but config/test.json declares no port', () => {
+    [null, JSON.stringify({ database: { tunnel: {} } })].forEach((testConfig) => {
+      when(`[t0] config/test.json is ${testConfig === null ? 'absent' : 'portless'}`, () => {
+        const result = useBeforeAll(async () =>
+          runUseTestdbPortOverride({ portSource: 'present', testConfig }),
+        );
+        then('it fails loud with a ConstraintError that names the absent key', () => {
+          expect(result.error?.name).toEqual('ConstraintError');
+          expect(result.error?.message).toContain('database.tunnel.local.port');
+          expect(result.portDeclaredAfter).toEqual(null);
+        });
+      });
+    });
+  });
+
+  given('[case5] the jest envs that open the local testdb in-process', () => {
+    then('jest.integration.env.ts declares the port before the wake probes it', () => {
+      const env = read('jest.integration.env.ts');
+      expect(env).toContain(
+        "import { useTestdbPortOverride } from './src/.test/assets/database/useTestdbPortOverride';",
+      );
+      expect(env.indexOf('useTestdbPortOverride();')).toBeGreaterThan(-1);
+      expect(env.indexOf('useTestdbPortOverride();')).toBeLessThan(
+        env.indexOf('useWakeOfTestdb();'),
+      );
+    });
+
+    then('jest.acceptance.env.ts declares the port only with test access', () => {
+      const env = read('jest.acceptance.env.ts');
+      expect(env).toContain("if (access === 'test') useTestdbPortOverride();");
+    });
+  });
+});

package/dist/practices/tests-node/testdb-preflight-branches.declapract.integration.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 
 import { given, then, useBeforeAll, when } from 'test-fns';
-import ts from 'typescript';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
 
 /**
  * .what = executes the REAL shipped `useWakeOfTestdb` template through its deterministic
@@ -19,7 +19,9 @@ import ts from 'typescript';
  * .teeth = invert the own-db gate and the no-db case reddens (a probe fires where it must not).
  *          drop the absent-config throw and that case reddens. drop a key from the completeness
  *          check and the incomplete-config case reddens. mis-map a probe arg and the complete case
- *          reddens (the probe receives the wrong host/port/role).
+ *          reddens (the probe receives the wrong host/port/role). probe the declared port where
+ *          the harness declared TESTDB_PORT and the worktree case reddens (the wake would probe
+ *          the default port while a worktree's db binds its own — #674).
  * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped template off
  *         the filesystem. no network, no real subprocess — the probeTestDb boundary is stubbed. it
  *         sits at the PRACTICE ROOT (not under `best-practice/`), because declapract's compile
@@ -59,15 +61,8 @@ type ProbeArgs = {
 const runUseWakeOfTestdb = (input: {
   declapractUse: string | null; // null = the declapract.use.yml file is absent
   testConfig: string | null; // null = the config/test.json file is absent
+  testdbPortOverride: string | null; // null = the harness declared no TESTDB_PORT
 }): { probeCalls: ProbeArgs[] } => {
-  const source = readFileSync(SOURCE_PATH, 'utf8');
-  const transpiled = ts.transpileModule(source, {
-    compilerOptions: {
-      module: ts.ModuleKind.CommonJS,
-      target: ts.ScriptTarget.ES2020,
-    },
-  }).outputText;
-
   const probeCalls: ProbeArgs[] = [];
 
   class FakeConstraintError extends Error {
@@ -97,7 +92,7 @@ const runUseWakeOfTestdb = (input: {
         },
         readFileSync: (p: string): string => {
           const key = asFileKey(p);
-          return (key !== 'other' && contentFor(key)) || '';
+          return (key === 'use' || key === 'config' ? contentFor(key) : '') ?? '';
         },
       };
     if (id === 'node:path')
@@ -112,11 +107,22 @@ const runUseWakeOfTestdb = (input: {
     return {};
   };
 
-  const moduleExports: Record<string, () => void> = {};
+  const { useWakeOfTestdb } = getModuleExportsFromTsSource<{
+    useWakeOfTestdb: () => void;
+  }>({ source: readFileSync(SOURCE_PATH, 'utf8'), requireStub });
 
-  // eslint-disable-next-line no-new-func
-  new Function('exports', 'require', transpiled)(moduleExports, requireStub);
-  moduleExports.useWakeOfTestdb!();
+  // declare TESTDB_PORT as the harness would, for this call only; restore the prior value after
+  const portOverridePrior = process.env.TESTDB_PORT;
+  if (input.testdbPortOverride === null) delete process.env.TESTDB_PORT;
+  if (input.testdbPortOverride !== null)
+    process.env.TESTDB_PORT = input.testdbPortOverride;
+  try {
+    useWakeOfTestdb!();
+  } finally {
+    if (portOverridePrior === undefined) delete process.env.TESTDB_PORT;
+    if (portOverridePrior !== undefined)
+      process.env.TESTDB_PORT = portOverridePrior;
+  }
 
   return { probeCalls };
 };
@@ -128,6 +134,7 @@ describe('the useWakeOfTestdb decide-gate runs its real branches (executed, no l
         runUseWakeOfTestdb({
           declapractUse: 'useCase: lambda-service\n',
           testConfig: COMPLETE_CONFIG,
+          testdbPortOverride: null,
         }),
       );
       then('it is a no-op (the testdb is never preflighted)', () => {
@@ -139,14 +146,15 @@ describe('the useWakeOfTestdb decide-gate runs its real branches (executed, no l
   given('a service that owns a db (declapract.use.yml declares a databaseUserName)', () => {
     const OWN_DB_USE = 'databaseUserName: svc-x-crud\n';
 
-    when('its config/test.json is complete', () => {
+    when('its config/test.json is complete, and the harness declared no TESTDB_PORT', () => {
       const state = useBeforeAll(() =>
         runUseWakeOfTestdb({
           declapractUse: OWN_DB_USE,
           testConfig: COMPLETE_CONFIG,
+          testdbPortOverride: null,
         }),
       );
-      then('it preflights the testdb with the config tunnel + role', () => {
+      then('it preflights the testdb with the config tunnel + role, at the declared port', () => {
         expect(state.probeCalls).toEqual([
           {
             host: 'localhost',
@@ -159,11 +167,60 @@ describe('the useWakeOfTestdb decide-gate runs its real branches (executed, no l
       });
     });
 
+    when('its config/test.json is complete, and the harness declared TESTDB_PORT (a worktree)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfTestdb({
+          declapractUse: OWN_DB_USE,
+          testConfig: COMPLETE_CONFIG,
+          testdbPortOverride: String(5432 + 77),
+        }),
+      );
+      then('it probes the per-worktree port the db binds, not the declared one', () => {
+        expect(state.probeCalls).toEqual([
+          {
+            host: 'localhost',
+            port: 5432 + 77,
+            username: 'svc_x_crud',
+            password: 'pw',
+            database: 'svc_x_testdb',
+          },
+        ]);
+      });
+    });
+
+    when('the harness declared a malformed TESTDB_PORT', () => {
+      then('it throws a ConstraintError that names TESTDB_PORT, and never probes', () => {
+        const probeCallsSeen: ProbeArgs[][] = [];
+        const error = (() => {
+          try {
+            probeCallsSeen.push(
+              runUseWakeOfTestdb({
+                declapractUse: OWN_DB_USE,
+                testConfig: COMPLETE_CONFIG,
+                testdbPortOverride: 'not-a-port',
+              }).probeCalls,
+            );
+            return null;
+          } catch (caught) {
+            return caught;
+          }
+        })();
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('TESTDB_PORT');
+        expect(probeCallsSeen).toEqual([]);
+      });
+    });
+
     when('its config/test.json is absent', () => {
       then('it throws a ConstraintError that names config/test.json (never a silent skip)', () => {
         const error = (() => {
           try {
-            runUseWakeOfTestdb({ declapractUse: OWN_DB_USE, testConfig: null });
+            runUseWakeOfTestdb({
+              declapractUse: OWN_DB_USE,
+              testConfig: null,
+              testdbPortOverride: null,
+            });
             return null;
           } catch (caught) {
             return caught;
@@ -188,6 +245,7 @@ describe('the useWakeOfTestdb decide-gate runs its real branches (executed, no l
             runUseWakeOfTestdb({
               declapractUse: OWN_DB_USE,
               testConfig: incomplete,
+              testdbPortOverride: null,
             });
             return null;
           } catch (caught) {

package/dist/practices/tests-service/__snapshots__/package.json.declapract.integration.test.ts.snap

@@ -4,9 +4,6 @@ exports[`tests-service package.json — the #598 wake-command gate, end to end g
 "{
   "name": "test-project",
   "version": "1.0.0",
-  "devDependencies": {
-    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
-  },
   "scripts": {
     "start:livedb:prep": "rhx use.rds.capacity --env prep"
   }
@@ -17,10 +14,7 @@ exports[`tests-service package.json — the #598 wake-command gate, end to end g
 exports[`tests-service package.json — the #598 wake-command gate, end to end given: [case2] a consumer that reaches NO cluster (no tunnel declared) when: [t0] the tests-service package.json declaration is applied then: the emitted package.json matches snapshot (the stripped shape): package.json — no-tunnel consumer (wake command stripped) 1`] = `
 "{
   "name": "test-project",
-  "version": "1.0.0",
-  "devDependencies": {
-    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
-  }
+  "version": "1.0.0"
 }
 "
 `;