declapract-typescript-ehmpathy 0.49.13 → 0.49.15

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.declapract.integration.test.ts

@@ -0,0 +1,86 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the pg-client-without-ssl fix (#652), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer repo
+ * .why = a unit test of `fix` never proves the `src/**\/*.ts` glob reaches a client the repo built
+ *        on its own, nor that one apply leaves it converged. a client that reads the app config is
+ *        given verified tls; a client that does not is flagged for a human, and never guessed at
+ * .note = each touched file is snapshotted in full, before AND after, per
+ *         rule.require.declapract-integration-tests
+ */
+// each apply evaluates the whole practice, which runs long under a full suite
+jest.setTimeout(10 * 60 * 1000);
+
+describe('pg-client-without-ssl (#652)', () => {
+  given('[case1] a repo with two plaintext pg clients of its own', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-persist-with-rds-pg-client-without-ssl',
+      clone:
+        './src/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const files = [
+      'src/utils/database/getSurfReportConnection.ts',
+      'src/access/sdks/sdkWaveArchive.ts',
+    ];
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyAll = async () => {
+      for (const file of files)
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file,
+        });
+    };
+
+    when('[t0] the input, before any fix', () => {
+      then('each client file matches snapshot', async () => {
+        for (const file of files)
+          expect(await read(file)).toMatchSnapshot(`${file} — before`);
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      useThen('apply the fix', async () => applyAll());
+
+      then('the config-backed client declares verified tls, and matches snapshot', async () => {
+        const after = await read(files[0]!);
+        expect(after).toContain(
+          'ssl: asDatabaseClientSsl({ clusterEndpoint: config.database.tunnel.lambda?.host ?? null }),',
+        );
+        expect(after).toContain(
+          "import { asDatabaseClientSsl } from '@src/utils/database/asDatabaseClientSsl';",
+        );
+        expect(after).toMatchSnapshot(`${files[0]} — after`);
+      });
+
+      then('the client outside the config is flagged, not guessed at, and matches snapshot', async () => {
+        const after = await read(files[1]!);
+        expect(after.split('\n')[0]).toContain('@declapract:review: a pg Client here');
+        expect(after).toContain(
+          'new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });',
+        );
+        expect(after).toMatchSnapshot(`${files[1]} — after`);
+      });
+    });
+
+    when('[t2] apply runs again (idempotency)', () => {
+      const passes = useThen('a second apply', async () => {
+        const before = await Promise.all(files.map((file) => read(file)));
+        await applyAll();
+        const after = await Promise.all(files.map((file) => read(file)));
+        return { before, after };
+      });
+
+      then('the second apply changes zero bytes', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.declapract.readme.md

@@ -0,0 +1,9 @@
+a pg `Client` built with no `ssl` option connects in plaintext. a postgres 17 cluster forces ssl
+by default, so that client fails to connect at all once the cluster is upgraded.
+
+this fix gives each such client `ssl: asDatabaseClientSsl({ clusterEndpoint })`, which verifies the
+cluster certificate against the rds us-east-1 roots and connects plain to the local testdb.
+
+the fix names the endpoint as `config.database.tunnel.lambda?.host`, so it applies only where the
+file already reads `config.database.tunnel`. any other file gets a review pointer at its top, since
+a human must pick the endpoint there.

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: declarations/examples
+  practices: declarations/practices
+  use-cases: declarations/useCases.yml

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/declapract.use.yml

@@ -0,0 +1,19 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: 'testdb'
+  databaseClusterName: 'testdb'
+  databaseUserName:
+    cicdUser: 'testdb_cicd'
+    serviceUser: 'testdb_service'
+  databaseTunnelHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  databaseClusterHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/src/access/sdks/sdkWaveArchive.ts

@@ -0,0 +1,7 @@
+import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/.test/assets/demo-repo-with-plaintext-pg-client/src/utils/database/getSurfReportConnection.ts

@@ -0,0 +1,19 @@
+import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+  });
+  await client.connect();
+  return client;
+};

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,72 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t0] the input, before any fix then: each client file matches snapshot: src/access/sdks/sdkWaveArchive.ts — before 1`] = `
+"import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t0] the input, before any fix then: each client file matches snapshot: src/utils/database/getSurfReportConnection.ts — before 1`] = `
+"import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+  });
+  await client.connect();
+  return client;
+};
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t1] apply runs then: the client outside the config is flagged, not guessed at, and matches snapshot: src/access/sdks/sdkWaveArchive.ts — after 1`] = `
+"// @declapract:review: a pg Client here connects with no tls. pass \`ssl: asDatabaseClientSsl({ clusterEndpoint })\` from @src/utils/database/asDatabaseClientSsl
+import pg from 'pg';
+
+/**
+ * .what = a client for a wave archive outside the app config
+ */
+export const getWaveArchiveClient = () =>
+  new pg.Client({ host: process.env.WAVE_ARCHIVE_HOST });
+"
+`;
+
+exports[`pg-client-without-ssl (#652) given: [case1] a repo with two plaintext pg clients of its own when: [t1] apply runs then: the config-backed client declares verified tls, and matches snapshot: src/utils/database/getSurfReportConnection.ts — after 1`] = `
+"import { Client } from 'pg';
+
+import { getConfig } from '@src/utils/config/getConfig';
+import { asDatabaseClientSsl } from '@src/utils/database/asDatabaseClientSsl';
+
+/**
+ * .what = a second connection the repo built on its own, for the surf report replica
+ */
+export const getSurfReportConnection = async () => {
+  const config = await getConfig();
+  const client = new Client({
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    user: config.database.role.crud.username,
+    password: config.database.role.crud.password,
+    database: config.database.target.database,
+    ssl: asDatabaseClientSsl({ clusterEndpoint: config.database.tunnel.lambda?.host ?? null }),
+  });
+  await client.connect();
+  return client;
+};
+"
+`;

package/dist/practices/persist-with-rds/bad-practices/pg-client-without-ssl/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,32 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import {
+  isPgClientWithoutSsl,
+  withPgClientSslDeclared,
+} from '../../../../../../utils/withPgClientSslDeclared';
+
+/**
+ * .what = the retired factory files that `old-get-database-connection` declares by their own path
+ * .why = that bad-practice deletes them on a template match; were this wildcard to flag them too,
+ *        two fixes would race on one file (a rewrite turns a template match into a kept edit, or
+ *        a second unlink hits a file already gone), so the retired files are left to their owner
+ */
+const RETIRED_FILE_PATHS = [
+  'src/utils/database/getDatabaseConnection.ts',
+  'src/utils/database/getDatabaseConnection.integration.test.ts',
+];
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (
+    contents !== null &&
+    !RETIRED_FILE_PATHS.includes(context.relativeFilePath) &&
+    isPgClientWithoutSsl({ source: contents })
+  )
+    return; // bad practice detected
+  throw new Error('does not match bad practice: every pg Client declares ssl');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+  return { contents: withPgClientSslDeclared({ source: contents }) };
+};

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.declapract.integration.test.ts

@@ -15,6 +15,9 @@ import { genTempDir, given, then, useThen, when } from 'test-fns';
  * .note = the terraform file is snapshotted in full (before AND after) so a reviewer
  *   can eyeball the exact end-state, per rule.require.declapract-integration-tests.
  */
+// the practice-scoped apply evaluates the whole persist-with-rds practice; under suite load it can outlast the default
+jest.setTimeout(600_000);
+
 describe('terraform-parameters forget', () => {
   given(
     '[case1] a repo with terraform-managed ssm params',
@@ -22,7 +25,7 @@ describe('terraform-parameters forget', () => {
       const tempDir = genTempDir({
         slug: 'declapract-terraform-parameters',
         clone: './src/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm',
-        symlink: [{ at: 'src', to: 'src' }],
+        symlink: [{ at: 'declarations', to: 'src' }],
       });
 
       const tfPath = 'provision/aws/product/parameter-store.tf';
@@ -59,6 +62,10 @@ describe('terraform-parameters forget', () => {
               'from = aws_ssm_parameter.secret_twilio_authToken',
             );
             expect(tf).toContain('destroy = false');
+            // the admin forget names its two copy targets under the derived names (#686)
+            expect(tf).toContain(
+              '# copy this value before the first plan → /test-org/test-project/{config}/database.role.cicd.for-plan.password, /test-org/test-project/{config}/database.role.cicd.for-apply.password (see provision/aws/readme.md)\nremoved {\n  from = aws_ssm_parameter.secret_database_admin_password',
+            );
             // full content, for the reviewer's eye
             expect(tf).toMatchSnapshot('parameter-store.tf — after');
           },

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.declare.yml

@@ -1,4 +1,4 @@
 declare:
-  examples: src/examples
-  practices: src/practices
-  use-cases: src/useCases.yml
+  examples: declarations/examples
+  practices: declarations/practices
+  use-cases: declarations/useCases.yml

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/provision/aws/product/parameter-store.tf

@@ -3,6 +3,15 @@ data "aws_ssm_parameter" "legacy_admin_password" {
   count           = var.environment == "prod" ? 1 : 0
   with_decryption = true
 }
+resource "aws_ssm_parameter" "secret_database_admin_password" {
+  name  = "${local.parameter_store_namespace}.database.admin.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
 resource "aws_ssm_parameter" "secret_database_role_crud_password" {
   name  = "${local.parameter_store_namespace}.database.role.crud.password"
   type  = "SecureString"

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/__snapshots__/.declapract.integration.test.ts.snap

@@ -6,6 +6,15 @@ exports[`terraform-parameters forget given: [case1] a repo with terraform-manage
   count           = var.environment == "prod" ? 1 : 0
   with_decryption = true
 }
+resource "aws_ssm_parameter" "secret_database_admin_password" {
+  name  = "\${local.parameter_store_namespace}.database.admin.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
 resource "aws_ssm_parameter" "secret_database_role_crud_password" {
   name  = "\${local.parameter_store_namespace}.database.role.crud.password"
   type  = "SecureString"
@@ -28,7 +37,14 @@ resource "aws_ssm_parameter" "secret_twilio_authToken" {
 `;
 
 exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t1] the bad-practice forget fix is applied then: the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot: parameter-store.tf — after 1`] = `
-"removed {
+"# copy this value before the first plan → /test-org/test-project/{config}/database.role.cicd.for-plan.password, /test-org/test-project/{config}/database.role.cicd.for-apply.password (see provision/aws/readme.md)
+removed {
+  from = aws_ssm_parameter.secret_database_admin_password
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+removed {
   from = aws_ssm_parameter.secret_database_role_crud_password
   lifecycle {
     destroy = false # forget from state; keep the live param

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/provision/aws/product/parameter-store.tf.declapract.ts

@@ -1,7 +1,7 @@
 import { type FileCheckFunction, type FileFixFunction } from 'declapract';
 
 /**
- * .what = terraform must not manage SSM parameters — they belong to declastruct-aws
+ * .what = terraform must not manage ssm parameters — they belong to declastruct-aws
  *   now (provision/aws/resources.parameters.ts).
  * .why = terraform managed these via the `__IGNORED__` + `ignore_changes = [value]`
  *   workaround, which hid drift and forced the secret through terraform state. the
@@ -25,9 +25,45 @@ export const check: FileCheckFunction = (contents) => {
   );
 };
 
-export const fix: FileFixFunction = (contents) => {
+/**
+ * .what = the derived ssm names a legacy role param's value seeds, or [] for any other param
+ * .why = the role rename (admin → cicd for-plan + for-apply, service → crud) moved the values to
+ *        new names; the forget erases the last terraform trace of the old one, so its comment
+ *        names where the value must be copied (#686). a fix holds no aws access, so the copy
+ *        itself is a human step (provision/aws/readme.md).
+ */
+const getAllCopyTargetsForLabel = (input: {
+  label: string;
+  namespace: string;
+}): string[] => {
+  if (/(^|_)admin(_|$)/.test(input.label))
+    return [
+      `${input.namespace}/database.role.cicd.for-plan.password`,
+      `${input.namespace}/database.role.cicd.for-apply.password`,
+    ];
+  if (/(^|_)service(_|$)/.test(input.label))
+    return [`${input.namespace}/database.role.crud.password`];
+  return [];
+};
+
+/**
+ * .what = cast copy targets into the comment line above a forget block ([] when none)
+ */
+const asCopyNoteLines = (input: { targets: string[] }): string[] =>
+  input.targets.length
+    ? [
+        `# copy this value before the first plan → ${input.targets.join(', ')} (see provision/aws/readme.md)`,
+      ]
+    : [];
+
+export const fix: FileFixFunction = (contents, context) => {
   if (!contents) return {};
 
+  // the derived namespace each copy target sits under; the config segment differs per env, so it stays `{config}`
+  const org = context?.projectVariables?.organizationName ?? '{org}';
+  const project = context?.projectVariables?.projectName ?? '{project}';
+  const namespace = `/${org}/${project}/{config}`;
+
   // drop the `data "aws_ssm_parameter"` reads — they existed only to seed values
   // that declastruct-aws now owns.
   const withoutDataReads = contents.replace(
@@ -40,8 +76,11 @@ export const fix: FileFixFunction = (contents) => {
   // indented `  }` of a nested lifecycle block never matches, so the nest is safe.
   const withForgetBlocks = withoutDataReads.replace(
     /resource\s+"aws_ssm_parameter"\s+"(\w+)"\s*\{[\s\S]*?\n\}/g,
-    (_match, label) =>
+    (_match, label: string) =>
       [
+        ...asCopyNoteLines({
+          targets: getAllCopyTargetsForLabel({ label, namespace }),
+        }),
         `removed {`,
         `  from = aws_ssm_parameter.${label}`,
         `  lifecycle {`,

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/.declapract.readme.md

@@ -1 +1,10 @@
 withDatabaseConnection -> withDatabaseContext, per procedure-fns pattern
+
+`withDatabaseConnection` took `dbConnection` in the input. `withDatabaseContext`
+(`src/utils/database/withDatabaseContext.ts`, shipped by the best-practice) takes it in the context:
+each op becomes `(input, context) => …`, and each caller passes the context as the 2nd arg.
+
+the move changes each op and each caller, so the fix does not rewrite code. it stamps a
+`// @declapract:review:` line above each import or definition of `withDatabaseConnection` that names
+the move, and leaves the extant wrapper in place so the tree still builds. delete the marker, and
+then the wrapper, once its last caller moves.

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/domain.operations/findSurferById.ts

@@ -0,0 +1,9 @@
+import { DatabaseConnection } from '../utils/database/getDatabaseConnection';
+import {
+  withDatabaseConnection,
+} from '../utils/database/withDatabaseConnection';
+
+export const findSurferById = withDatabaseConnection(
+  async ({ id, dbConnection }: { id: string; dbConnection: DatabaseConnection }) =>
+    dbConnection.query({ sql: 'select * from surfer where id = :id', values: { id } }),
+);

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input/src/utils/database/withDatabaseConnection.ts

@@ -0,0 +1,10 @@
+import { DatabaseConnection, getDatabaseConnection } from './getDatabaseConnection';
+
+export const withDatabaseConnection =
+  <I extends { dbConnection: DatabaseConnection }, O>(
+    logic: (input: I) => Promise<O>,
+  ) =>
+  async (input: Omit<I, 'dbConnection'>): Promise<O> => {
+    const dbConnection = await getDatabaseConnection();
+    return logic({ ...input, dbConnection } as I);
+  };

package/dist/practices/persist-with-rds/bad-practices/with-connection-in-input/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,55 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asInputToContextReviewMarker } from '../../../../../../utils/asInputToContextReviewMarker';
+import { withReviewMarkerAbove } from '../../../../../../utils/withReviewMarkerAbove';
+
+/**
+ * .what = a line that imports, re-exports, or defines the retired `withDatabaseConnection`.
+ * .why  = a multi-line import names the module only on its `from` line, so the module path is
+ *         matched too; one marker per import statement either way.
+ */
+const WITH_DATABASE_CONNECTION_LINE_PATTERN =
+  /(?:^\s*import\b[^\n]*\bwithDatabaseConnection\b|^\s*export\s+(?:const|function)\s+withDatabaseConnection\b|\bfrom\s+['"][^'"]*\/withDatabaseConnection['"])/;
+
+const REVIEW_MARKER = asInputToContextReviewMarker({
+  from: 'withDatabaseConnection (dbConnection in the input)',
+  into: 'withDatabaseContext (src/utils/database/withDatabaseContext.ts)',
+});
+
+/**
+ * .what = flags a src file that imports or defines `withDatabaseConnection`.
+ * .why  = the practice replaced it with `withDatabaseContext`; the prior declaration was an EXISTS
+ *         check with no fix, so an apply failed with no pointer to the replacement and each call
+ *         site broke the build (#626). this check names each file by path in `plan`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents
+      ?.split('\n')
+      .some((line) => WITH_DATABASE_CONNECTION_LINE_PATTERN.test(line))
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: no import or definition of withDatabaseConnection',
+  );
+};
+
+/**
+ * .what = stamps the shared input→context review line above each such import or definition.
+ * .why  = each op moves `dbConnection` from its input into a context arg, and each caller passes
+ *         it as the 2nd arg — a shape change a regex cannot make safely — so the fix names the
+ *         move beside the line, and never deletes the extant wrapper (its callers still need it).
+ * .note = idempotent; the check stays red until a human moves the ops, so `plan` keeps it in view.
+ * .note = an absent file is left absent: every fix must settle on absent input, a contract the
+ *         repo-wide fix-coverage sweep holds (`practiceFixCoverage`, #607)
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: withReviewMarkerAbove({
+      contents,
+      lineMatcher: WITH_DATABASE_CONNECTION_LINE_PATTERN,
+      marker: REVIEW_MARKER,
+    }),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/.declapract.readme.md

@@ -12,18 +12,67 @@ we use:
 | `databaseTunnelHost.{prep,prod}` | ssm proxy host for database tunnel | `aws.ssmproxy.ahbodedb.prep` |
 | `databaseClusterHost.{prep,prod}` | rds cluster endpoint | `ahbodedb.cluster-xxx.us-east-1.rds.amazonaws.com` |
 
+## optional variables
+
+| variable | description | default |
+|----------|-------------|---------|
+| `databaseClusterName` (or `databaseClusterName.{prep,prod}`) | the rds cluster the vpc tunnel targets (`database.tunnel.cluster.name`) | the first label of `databaseClusterHost.{env}` |
+
+set it only when the cluster endpoint is a custom dns alias whose first label is not the
+cluster identifier. a hand-set `database.tunnel.cluster.name` in a repo's own config is kept.
+
+## the pg-pool patch
+
+pg-pool's pool falls back to `require('pg').Client` when no `Client` is passed. dpdm reads that
+require statically, so every repo with pg + pg-pool fails `test:lint:cycles` on `pg <-> pg-pool`
+(the check reads node_modules too, by policy). this practice ships
+`patches/pg-pool.patch`, which drops the fallback, under the bare-name key
+`pnpm.patchedDependencies["pg-pool"]`:
+
+- the bare name never goes stale, so the stale-patch check never retires it; the hunk fits every
+  stable pg-pool release in `^3.2.1`, which `pg@8.3.0` asks for
+- a repo's own exact-version key (`pg-pool@<version>`) outranks it at install, and both survive the apply.
+  a hand patch of the same line may be deleted, key and file
+- after an apply, run `pnpm install` and commit the lockfile: it records the patch hash, so a ci
+  `--frozen-lockfile` install fails until it does
+- pg passes its own `Client` into every pool it builds, so code that goes through `pg` sees no change.
+  code that calls `new Pool()` from pg-pool directly must pass `{ Client: require('pg').Client }`
+- if pnpm warns that the patch failed to apply, pg-pool moved the line: upgrade
+  declapract-typescript-ehmpathy and re-apply. if no fix has shipped yet, pin your own
+  `pg-pool@<version>` patch; its exact key outranks the bare one
+- to recut the hunk, keep one context line on each side of the changed line. wider context misfits
+  older releases in `^3.2.1` (3.2.1–3.4.1), and pnpm then installs pg-pool unpatched
+
 ## ssm parameters
 
-terraform provisions these ssm parameters for database credentials:
+the provision wish (`provision/aws/resources.parameters.ts`) declares the db credentials at the
+names sdk-config derives for a bare `$.at(aws::param)`:
 
 | parameter name | description | environments |
 |----------------|-------------|--------------|
-| `{namespace}.database.role.cicd.password` | password for cicd database user | prep, prod |
-| `{namespace}.database.role.crud.password` | password for crud database user | prep, prod |
+| `/{org}/{project}/{config}/database.role.cicd.for-plan.password` | password for the cicd plan user | prep, prod |
+| `/{org}/{project}/{config}/database.role.cicd.for-apply.password` | password for the cicd apply user | prep, prod |
+| `/{org}/{project}/{config}/database.role.crud.password` | password for the crud user | prep, prod |
+
+a repo whose values sit at a prior name (or under `role.admin` / `role.service`) copies them to
+these names before its first provision apply — the map is in `provision/aws/readme.md`.
+
+prep users are created with the `__CHANG3_ME__` password by `provision/schema/deploy.database.sh`,
+so `config/prep.json` accepts either `__CHANG3_ME__` or `$.at(aws::param)` at each password.
+
+## config grants
+
+`src/utils/config/config.schema.ts` exports one schema per oidc grant:
+
+- `apply` (the default: the apply job, the cloud runtime, local dev, tests) requires every secret,
+  so `Config` carries no `| undefined` and consumers need no guards
+- `plan` marks `role.cicd.for-apply.password` and `role.crud.password` optional. the prod plan
+  job's oidc role may read only the for-plan credential, and sdk-config substitutes `undefined`
+  for each param a role is denied
+- `for-plan` and `for-apply` each carry a username, since a plan job may map to a readonly db user
 
-legacy parameters (kept for backwards compatibility):
-- `{namespace}.database.admin.password`
-- `{namespace}.database.service.password`
+the grant is an argument, never read inside the schema; `getConfig` picks the schema at call time
+(see the `config` practice readme).
 
 ## a stateful store gets an alias, never a copy, across the dual-publish transition
 
@@ -53,6 +102,6 @@ lives in `cicd-service/best-practice/.github/workflows/provision.yml.declapract.
 `contents` fn emits those 4 jobs **only** when `persist-with-rds` is in the resolved practice set, so
 a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) does not inherit a
 `provision` workflow that references files it lacks. it uses `CONTAINS`, not `EQUALS`, so a narrow
-`declapract fix --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
+`declapract apply --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
 EQUALS hazard). if you add a new rds-coupled provision job, add it to that gate the same way — a
 caller that names a callee this practice supplies must be reconciled against this practice's presence.

package/dist/practices/persist-with-rds/best-practice/codegen.sql.dao.yml

@@ -1,5 +1,5 @@
 language: postgres
-dialect: 10.7
+dialect: 17
 generates:
   daos:
     to: src/access/daos

package/dist/practices/persist-with-rds/best-practice/codegen.sql.dao.yml.declapract.ts

@@ -1,3 +1,35 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, type FileFixFunction } from 'declapract';
 
 export const check = FileCheckType.CONTAINS; // contains since the user may have exclusions in that "for" object
+
+const DIALECT_LINE = /^dialect: .*$/m;
+const LANGUAGE_LINE = /^language: .*$/m;
+
+/**
+ * .what = moves the found config onto the declared `dialect` line, and keeps every other line
+ * .why = a CONTAINS check has no default fix for a file that exists, so a repo on a stale dialect
+ *        (10.7, eight majors behind) could never converge on its own (#664)
+ * .note = a second pass finds the declared line already in place, so it changes naught
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // write the declared config where none exists
+  const declared = context.declaredFileContents!;
+  if (!contents) return { contents: declared };
+
+  // swap the found dialect line for the declared one
+  const dialectDeclared = declared.match(DIALECT_LINE)?.[0];
+  if (!dialectDeclared) return { contents };
+  if (DIALECT_LINE.test(contents))
+    return { contents: contents.replace(DIALECT_LINE, dialectDeclared) };
+
+  // or add it under the language line, where the template declares it
+  const languageFound = contents.match(LANGUAGE_LINE)?.[0];
+  if (languageFound)
+    return {
+      contents: contents.replace(
+        LANGUAGE_LINE,
+        `${languageFound}\n${dialectDeclared}`,
+      ),
+    };
+  return { contents: `${dialectDeclared}\n${contents}` };
+};