declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -0,0 +1,224 @@
+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 persist-with-rds `old-dev-config-location` relocate +
+ *         tier-migrate, run through the REAL declapract apply pipeline against a genTempDir
+ *         clone of a consumer repo (the row-4 clamp, rds declarer).
+ * .why  = the config declarer has its own pipeline test; per
+ *         `rule.require.declapract-integration-tests` EACH declarer that relocates a file AND
+ *         transforms blocks owes its own end-to-end test — a unit test of the exported `fix`
+ *         never exercises the glob→file match or the `relativeFilePath` rewrite. the rds
+ *         declarer adds one transform the config twin lacks (`__CHANG3_ME__` → aws-param), so
+ *         it needs its own clamp rather than a claim that the config test covers it.
+ * .teeth = the input holds `"access": "dev"` (unambiguous → migrated to `prep`) plus four `.dev`
+ *          hosts the util runs on in a CONSUMER's real config — a `://` URL `https://auth.myapp.dev`,
+ *          a mid-dotted `bastion.dev.example.com`, a terminal `aws.ssmproxy.mydb.dev`, and a FOREIGN
+ *          public host `api.dev.paypal.com` (paypal's own label). a `.dev` label is axis-ambiguous
+ *          WHEREVER it sits, so per guard #3 EVERY host is preserved byte-for-byte — the after-state
+ *          proves all four survive, that none flips to `.prep`, and that NO `@declapract:review`
+ *          bytes ever enter the config. it also proves the rds-only `__CHANG3_ME__` → aws-param
+ *          transform (the one the config twin lacks) plus the relocation.
+ */
+describe('persist-with-rds — old-dev-config-location relocate + tier-migrate (row-4 clamp)', () => {
+  given('[case1] an rds repo with a config/dev.json to migrate', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-persist-with-rds-old-dev-config-location',
+      clone: './src/practices/persist-with-rds/.test/assets/demo-repo-with-dev-config',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const devPath = 'config/dev.json';
+    const prepPath = 'config/prep.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const exists = async (relativePath: string): Promise<boolean> =>
+      fs
+        .access(path.join(tempDir, relativePath))
+        .then(() => true)
+        .catch(() => false);
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'persist-with-rds',
+        file: devPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('config/dev.json holds the dev tier + the placeholder + matches snapshot', async () => {
+        const before = await read(devPath);
+        expect(before).toContain('"access": "dev"');
+        expect(before).toContain('"__CHANG3_ME__"');
+        expect(before).toMatchSnapshot('config/dev.json — before');
+      });
+    });
+
+    when('[t1] the relocate + migrate fix is applied', () => {
+      useThen('migrate the dev config', async () => applyMigrate());
+
+      then(
+        'config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot',
+        async () => {
+          // the relocation landed: the new path exists, the old path is unlinked
+          expect(await exists(prepPath)).toBe(true);
+          expect(await exists(devPath)).toBe(false);
+
+          const after = await read(prepPath);
+          // the access itself is the one unambiguous token → migrated
+          expect(after).toContain('"access": "prep"');
+          expect(after).not.toContain('"access": "dev"');
+          // EVERY host survives byte-for-byte — a `.dev` label is axis-ambiguous WHEREVER it sits,
+          // so per guard #3 the util rewrites NO host at all.
+          expect(after).toContain('bastion.dev.example.com');
+          expect(after).toContain('aws.ssmproxy.mydb.dev');
+          expect(after).toContain('https://auth.myapp.dev');
+          // the FOREIGN public host is the decisive corruption case: teeth — the prior mid-dotted
+          // rewrite turned this into `api.prep.paypal.com`, a silent public-endpoint corruption.
+          expect(after).toContain('api.dev.paypal.com');
+          expect(after).not.toContain('api.prep.paypal.com');
+          // no host was flipped to `.prep`, so no wrong-tier value ever enters the config
+          expect(after).not.toContain('bastion.prep.example.com');
+          expect(after).not.toContain('aws.ssmproxy.mydb.prep');
+          // the migration never emits a value it cannot verify — no marker bytes in config
+          expect(after).not.toContain('@declapract:review');
+          // the rds-only placeholder → the aws-param reference (the transform the twin lacks)
+          expect(after).toContain('"$.at(aws::param)"');
+          expect(after).not.toContain('__CHANG3_ME__');
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('config/prep.json — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // config/dev.json is gone after the first relocate, so the EXISTS check no longer
+      // fires and no fix runs — config/prep.json must be untouched (per
+      // rule.require.idempotent-fixes).
+      const passes = useThen(
+        'a second apply over the already-migrated repo',
+        async () => {
+          const before = await read(prepPath);
+          await applyMigrate();
+          const after = await read(prepPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});
+
+/**
+ * .what = D55 clamp: `src/utils/config/getConfig.ts` has exactly ONE declarer — the `config`
+ *         practice (the real sdk-config impl). `persist-with-rds` ships NO second copy of that
+ *         path (the old `'placeholder' as any` typed lie).
+ * .why  = `lambda-service-with-rds` extends `lambda-service`, which always supplies `config`, so the
+ *         placeholder was dead weight whose correctness rested on alphabetical apply order
+ *         (`config` < `persist-with-rds`). two declarers of one path, one a typed lie, is a silent
+ *         hazard: a consumer converged to the real file only by accident of that order. one
+ *         declarer removes both the order dependency and the lie — the consumer receives config's
+ *         real getConfig at this exact path, so persist-with-rds's own import resolves.
+ * .teeth = re-add a getConfig.ts under persist-with-rds/best-practice → the sole-declarer assertion
+ *          reddens.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the filesystem (the
+ *         practice trees). no credential, no network.
+ */
+describe('persist-with-rds — getConfig has a single declarer (D55 clamp)', () => {
+  const configGetConfig =
+    'src/practices/config/best-practice/src/utils/config/getConfig.ts';
+  const rdsGetConfig =
+    'src/practices/persist-with-rds/best-practice/src/utils/config/getConfig.ts';
+  const rdsDbConnection =
+    'src/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.ts';
+  const exists = async (relativePath: string): Promise<boolean> =>
+    fs
+      .access(relativePath)
+      .then(() => true)
+      .catch(() => false);
+
+  given('[case1] the two practices that touch src/utils/config/getConfig.ts', () => {
+    when('[t0] the declarers of that path are read', () => {
+      then('the config practice is the sole declarer (real sdk-config impl)', async () => {
+        expect(await exists(configGetConfig)).toBe(true);
+        const real = await fs.readFile(configGetConfig, 'utf-8');
+        expect(real).toContain("from 'sdk-config'");
+        expect(real).not.toContain("'placeholder' as any");
+      });
+
+      then('persist-with-rds ships NO second copy (no typed-lie placeholder)', async () => {
+        // teeth: re-add a getConfig.ts under persist-with-rds/best-practice and this reddens
+        expect(await exists(rdsGetConfig)).toBe(false);
+      });
+
+      then('persist-with-rds imports getConfig from the config-supplied path', async () => {
+        // the consumer receives config's real getConfig at this exact path, so the import resolves
+        const dbConn = await fs.readFile(rdsDbConnection, 'utf-8');
+        expect(dbConn).toContain("from '../config/getConfig'");
+      });
+    });
+  });
+});
+
+/**
+ * .what = config.schema.ts clamp: this path has TWO declarers BY DESIGN — `config` (the base
+ *         shape, for a non-rds `lambda-service`) and `persist-with-rds` (the full shape with the
+ *         database block, for `lambda-service-with-rds`). persist-with-rds declares its full schema
+ *         as a PLAIN overwrite template (EQUALS), NOT a CONTAINS + regex-splice fix.
+ * .why  = a CONTAINS+splice `fix` for this path was dead code: its regex anchored on `});` before
+ *         `export type Config`, but config's base emits `} as const;` there, so on a fresh
+ *         `lambda-service-with-rds` consumer the fix no-oped and the check stayed permanently red —
+ *         no path to green via `declapract fix`. worse, its inline splice string was stale (flat
+ *         `role.cicd.{username,password}` vs the real `for-plan`/`for-apply` split). the later
+ *         declarer (persist-with-rds) shadows config's base for rds consumers, so removal of the
+ *         `.declapract.ts` makes its full `config.schema.ts` a plain EQUALS overwrite (declapract's
+ *         default with no companion) that always converges — rule.prefer.overwrite-over-mutate: do
+ *         not pair an overwrite template with a separate splice fix for the same path.
+ * .teeth = re-add a config.schema.ts.declapract.ts under persist-with-rds/best-practice → the
+ *          "no splice-fix declarer" assertion reddens; strip the `for-plan` split from
+ *          persist-with-rds's full schema → the "full schema declared" assertion reddens.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: reads the filesystem (practice trees).
+ */
+describe('persist-with-rds — config.schema.ts is a plain overwrite, not a splice-fix (config.schema clamp)', () => {
+  const configSchema =
+    'src/practices/config/best-practice/src/utils/config/config.schema.ts';
+  const rdsSchema =
+    'src/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts';
+  const rdsSchemaFix =
+    'src/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts.declapract.ts';
+  const exists = async (relativePath: string): Promise<boolean> =>
+    fs
+      .access(relativePath)
+      .then(() => true)
+      .catch(() => false);
+
+  given('[case1] the two by-design declarers of src/utils/config/config.schema.ts', () => {
+    when('[t0] the declared files are read', () => {
+      then('config declares the BASE shape (no database block) for a non-rds service', async () => {
+        const base = await fs.readFile(configSchema, 'utf-8');
+        expect(base).toContain('const base = z.object(');
+        expect(base).not.toContain('database: z.object(');
+      });
+
+      then('persist-with-rds declares the FULL schema (database + for-plan/for-apply split)', async () => {
+        // teeth: strip the for-plan split from the full schema and this reddens
+        const full = await fs.readFile(rdsSchema, 'utf-8');
+        expect(full).toContain('database: z.object(');
+        expect(full).toContain("'for-plan': z.object(");
+        expect(full).toContain("'for-apply': z.object(");
+      });
+
+      then('persist-with-rds ships NO CONTAINS+splice fix for that path (dead regex gone)', async () => {
+        // teeth: re-add config.schema.ts.declapract.ts and this reddens. the paired full template
+        // is a plain EQUALS overwrite, so a fresh rds consumer converges via overwrite, never a
+        // splice that no-ops on config's `} as const;` base.
+        expect(await exists(rdsSchemaFix)).toBe(false);
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/.extensions.sql.declapract.integration.test.ts

@@ -0,0 +1,38 @@
+import { readFile } from '../../utils/readFile';
+import { fix } from './best-practice/provision/schema/sql/init/.extensions.sql.declapract';
+
+describe('.extensions.sql fix', () => {
+  it('should be able to fix a file with custom extensions correctly', async () => {
+    const declaredFileContents = await readFile({
+      filePath: `${__dirname}/best-practice/provision/schema/sql/init/.extensions.sql`,
+    }); // grab the declared contents
+    const exampleFoundContents = `
+/**
+ NOTE: because db owner is not allowed to create extensions, these changes are applied manually
+
+  NOTE: for the integration test db, these are applied automatically upon spinning up the docker instance
+*/
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+CREATE EXTENSION IF NOT EXISTS "cube";
+CREATE EXTENSION IF NOT EXISTS "earthdistance";
+    `;
+    const { contents: fixedContents } = await fix(exampleFoundContents, {
+      declaredFileContents,
+    } as any);
+    expect(fixedContents).toContain('CREATE EXTENSION IF NOT EXISTS "cube";');
+    expect(fixedContents).toContain(
+      'CREATE EXTENSION IF NOT EXISTS "earthdistance";',
+    );
+    expect(fixedContents).toMatchSnapshot();
+  });
+  it('should be able to create a new file to fix case where file does not exist yet', async () => {
+    const declaredFileContents = await readFile({
+      filePath: `${__dirname}/best-practice/provision/schema/sql/init/.extensions.sql`,
+    }); // grab the declared contents
+    const { contents: fixedContents } = await fix(null, {
+      declaredFileContents,
+    } as any);
+    expect(fixedContents).toMatchSnapshot();
+  });
+});

package/dist/practices/persist-with-rds/.test/assets/demo-repo-with-dev-config/config/dev.json

@@ -0,0 +1,18 @@
+{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev",
+    "password": "__CHANG3_ME__"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}

package/dist/practices/persist-with-rds/.test/assets/demo-repo-with-dev-config/declapract.declare.yml

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

package/dist/practices/persist-with-rds/.test/assets/demo-repo-with-dev-config/declapract.use.yml

@@ -0,0 +1,18 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: 'testdb'
+  databaseUserName:
+    cicdUser: 'cicd_user'
+    serviceUser: 'service_user'
+  databaseTunnelHost:
+    prep: 'tunnel.prep.example.com'
+    prod: 'tunnel.prod.example.com'
+  databaseClusterHost:
+    prep: 'cluster.prep.example.com'
+    prod: 'cluster.prod.example.com'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/practices/persist-with-rds/.test/assets/demo-repo-with-dev-config/package.json

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

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

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] an rds repo with a config/dev.json to migrate when: [t0] the migration input (before any fix) then: config/dev.json holds the dev tier + the placeholder + matches snapshot: config/dev.json — before 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev",
+    "password": "__CHANG3_ME__"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;
+
+exports[`persist-with-rds — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] an rds repo with a config/dev.json to migrate when: [t1] the relocate + migrate fix is applied then: config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot: config/prep.json — after 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "prep"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev",
+    "password": "$.at(aws::param)"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;

package/dist/practices/persist-with-rds/__snapshots__/.extensions.sql.declapract.integration.test.ts.snap

@@ -0,0 +1,42 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`.extensions.sql fix should be able to create a new file to fix case where file does not exist yet 1`] = `
+"/**
+ * postgres databases use extensions to increase functionality
+ * - we have a minimum set of extensions that are required for sql-schema-generator
+ * - services may also include their own extensions if they want additional functionality
+ * - this is not managed by sql-schema-control
+ *   - requires superuser privileges, cicd user only has db_owner privileges
+ * - this is applied
+ *   - automatically for integration-test db (through \`provision/docker/.../init/\` directory, with files cp'd by npm provision scripts)
+ *   - by the deployment script for live deployments
+ */
+
+-- extensions required for all sql-schema-generator resources:
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- extensions required for custom use cases in this service:
+-- CREATE EXTENSION IF NOT EXISTS ..."
+`;
+
+exports[`.extensions.sql fix should be able to fix a file with custom extensions correctly 1`] = `
+"/**
+ * postgres databases use extensions to increase functionality
+ * - we have a minimum set of extensions that are required for sql-schema-generator
+ * - services may also include their own extensions if they want additional functionality
+ * - this is not managed by sql-schema-control
+ *   - requires superuser privileges, cicd user only has db_owner privileges
+ * - this is applied
+ *   - automatically for integration-test db (through \`provision/docker/.../init/\` directory, with files cp'd by npm provision scripts)
+ *   - by the deployment script for live deployments
+ */
+
+-- extensions required for all sql-schema-generator resources:
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- extensions required for custom use cases in this service:
+CREATE EXTENSION IF NOT EXISTS "cube";
+CREATE EXTENSION IF NOT EXISTS "earthdistance";"
+`;

package/dist/practices/persist-with-rds/__snapshots__/deploy-database-gerunds.declapract.integration.test.ts.snap

@@ -0,0 +1,102 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds deploy.database.sh gerund-free given: the shipped deploy.database.sh when: the template body is read then: the emitted deploy.database.sh matches snapshot: deploy.database.sh 1`] = `
+"#####################################################
+## initialize the database in a live cluster
+## - in other words, it does all of the things that docker does for us when we spin up a cluster without the db already
+## - i.e.,
+##    - create the database
+##    - install the extensions
+##    - creates the schema
+##    - creates the cicd user
+##    - grants the cicd user ownership of the db
+## - note:
+##   - requires pg admin access
+##   - requires _you_ to change the passwords in prod manually
+##
+## usage example:
+## \`\`\`sh
+## ./provision/schema/deploy.database.sh prep $(op item get ahbodedb.prep.postgres --fields label=password --format json | jq -r .value)
+## \`\`\`
+#####################################################
+
+set -eu
+
+# check that the human has defined the environment that they want this key created for correctly
+ENVIRONMENT="\${1:-}";
+if [ "$ENVIRONMENT" != "prod" ] && [ "$ENVIRONMENT" != "prep" ]; then
+  echo "\\nerror: environment, the first argument, must be specified as either 'prod' or 'prep'. you specified '$ENVIRONMENT'";
+  exit 2;
+fi
+
+# check that the human is authed into correct account
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account');
+EXPECTED_AWS_ACCOUNT_ID=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.awsAccountId.prod}" || echo "@declapract{variable.awsAccountId.prep}");
+if [ "$AWS_ACCOUNT_ID" != "$EXPECTED_AWS_ACCOUNT_ID" ]; then
+  echo "\\nerror: the AWS_ACCOUNT that you are signed into is not correct for the environment you specified. you are authed into account '$AWS_ACCOUNT_ID' but the correct account id for '$ENVIRONMENT' is '$EXPECTED_AWS_ACCOUNT_ID'";
+  exit 2;
+fi
+
+# check that pg admin password was specified
+POSTGRES_ADMIN_PASSWORD="\${2:-}"
+if [ -z "\${POSTGRES_ADMIN_PASSWORD:-}" ]; then
+  echo "\\nerror: POSTGRES_ADMIN_PASSWORD must be defined as second arg";
+  exit 2;
+fi;
+
+# check that the cicd password was provisioned, if in prod, since this is used to create the cicd user
+# note: this reads the legacy DOTTED param name (\`....database.role.cicd.password\`), a live consumer
+#       distinct from the slash-path plan/apply secrets. it is the prod cicd-user bootstrap credential
+#       and stays alive on purpose — do not prune it as an unreferenced legacy param.
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_PASSWORD=$(aws ssm get-parameter --name "@declapract{variable.organizationName}.@declapract{variable.projectName}.$ENVIRONMENT.database.role.cicd.password" --with-decryption --output text --query Parameter.Value)
+  if [ -z "\${CICD_USER_PASSWORD:-}" ]; then
+    echo "\\nerror: CICD_USER_PASSWORD must be provisioned with terraform before you run this"
+    exit 2;
+  fi;
+  if [ "$CICD_USER_PASSWORD" = "__IGNORED__" ] || [ "$CICD_USER_PASSWORD" = "__CHANG3_ME__" ]; then
+    echo "\\nerror: CICD_USER_PASSWORD must be set to a value other than the default placeholder"
+    exit 2;
+  fi;
+fi;
+
+
+# define the postgres connection string
+CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseTunnelHost.prod}" || echo "@declapract{variable.databaseTunnelHost.prep}");
+CLUSTER_CONNECTION_STRING=postgresql://postgres:$POSTGRES_ADMIN_PASSWORD@$CLUSTER_HOST:5432
+ROOT_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/postgres
+SVC_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/@declapract{variable.databaseName}
+
+# define path to the init sqls
+SRC_PATH=$(readlink --canonicalize "$0");
+SRC_DIR=$(dirname $SRC_PATH);
+INIT_SQLS_DIR=$SRC_DIR/sql/init;
+
+# run the create database command on root db
+echo "\\n 🔨 create the database..."
+psql $ROOT_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.database.sql
+
+echo "\\n 🔨 install the extensions..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.extensions.sql
+
+echo "\\n 🔨 create the schema..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.schema.sql
+
+if [ "$ENVIRONMENT" = "prod" ]; then
+  echo "\\n 🔨 grant reads to the datalakedb user..." # only in prod env; we dont want prep's test data in our datalake
+  psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.user.datalakedb.sql
+fi;
+
+echo "\\n 🔨 create the cicd user..."
+CICD_USER_CREATE_SQL_PATH=$INIT_SQLS_DIR/.user.cicd.sql
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_CREATE_SQL_PATH_TEMP=$CICD_USER_CREATE_SQL_PATH.tmp # in prod, we must create a temp file which will have the actual password we'll use to create the cicd user
+  cat $CICD_USER_CREATE_SQL_PATH | sed "s/__CHANG3_ME__/\${CICD_USER_PASSWORD}/" > $CICD_USER_CREATE_SQL_PATH_TEMP # create the temp file w/ the actual password
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH_TEMP # run the temp create sql w/ the actual password
+  rm $CICD_USER_CREATE_SQL_PATH_TEMP # remove the temp file, so the password doesn't get checked in
+else
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH # otherwise, we can run the file directly. no password replacement required
+fi
+echo "\\n 🎉 done"
+"
+`;

package/dist/practices/persist-with-rds/__snapshots__/provision-testdb-access.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds provision:testdb access given: the shipped best-practice package.json when: the provision:testdb chain is read then: the emitted provision:testdb chain matches snapshot: provision:testdb chain 1`] = `"npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && ACCESS=test npm run provision:schema:plan && ACCESS=test npm run provision:schema:apply && ACCESS=test npm run provision:schema:plan"`;

package/dist/practices/persist-with-rds/__snapshots__/ssm-cicd-param-names.declapract.integration.test.ts.snap

@@ -0,0 +1,10 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds ssm cicd param names are slash-path, tierless given: [case1] the two cicd credentials when: [t0] resources.parameters.ts is read then: the emitted cicd + crud param-name lines match snapshot: ssm cicd + crud param names 1`] = `
+[
+  "*         with NO tier segment — \`parameter/<star>/svc-<star>/database/role/cicd/for-plan/<star>\`",
+  "secret({ name: \`\${namespace}.database.role.crud.password\` }),",
+  "name: \`/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-plan/password\`,",
+  "name: \`/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-apply/password\`,",
+]
+`;

package/dist/practices/persist-with-rds/__snapshots__/testdb-preflight-failloud.declapract.integration.test.ts.snap

@@ -0,0 +1,30 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`testdb preflight fails loud (#589) given: the shipped wait-for-postgres preflight probe when: [t4] the shipped probe is vibechecked as a whole then: the emitted wait-for-postgres.sh matches snapshot: wait-for-postgres.sh preflight probe 1`] = `
+"#!/bin/sh
+set -eu
+# wait until postgres is really available
+maxcounter=45
+
+echo "waiting for postgres server to begin accepting connections..."
+counter=1
+# pass the secret via PGPASSWORD, not inline in the connection string (which leaks it to \`ps\`)
+export PGPASSWORD="\${POSTGRES_PASSWORD:-}"
+# capture the probe's stderr so the real cause (bad password, port conflict, image build failure)
+# surfaces on timeout, rather than one hardcoded diagnosis that reads the same for every cause
+lasterr=""
+while true; do
+    # fold the capture into the if-condition so \`set -e\` does not exit on the expected
+    # connect failures while postgres warms up; lasterr still holds the last stderr
+    if lasterr=$(psql "dbname=\${POSTGRES_DB:-} host=localhost user=postgres port=5432" -c '\\l' 2>&1); then break; fi
+    sleep 1
+    counter=\`expr $counter + 1\`
+    if [ $counter -gt $maxcounter ]; then
+        >&2 echo "postgres did not accept connections after \${maxcounter}s; the last psql error was:"
+        >&2 echo "$lasterr"
+        exit 1
+    fi;
+done
+echo "connected to postgres instance successfully"
+"
+`;

package/dist/practices/persist-with-rds/bad-practices/old-dev-config-location/config/dev.json.declapract.ts

@@ -1,19 +1,33 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
 
+import { asPrepConfigPath } from '../../../../../utils/asPrepConfigPath';
+import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToPrep';
+
 export const check = FileCheckType.EXISTS;
 
+/**
+ * .what = rewrite the rds password placeholder `"__CHANG3_ME__"` to the aws-param reference.
+ * .why  = the rds config twin adds this one transform the config twin lacks; a named op keeps the
+ *         declarer's `fix` a what-not-how read (rule.require.named-transformers).
+ */
+const withAwsParamPlaceholder = (input: { contents: string }): string =>
+  input.contents.replace(/"__CHANG3_ME__"/g, '"$.at(aws::param)"');
+
 export const fix: FileFixFunction = (contents, context) => {
-  // move config/dev.json → config/prep.json and update .dev → .prep references
+  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
+  // both halves are shared utils (one source for both declarers): migrateDevConfigToPrep
+  // owns the content migration, asPrepConfigPath owns the relocate. this declarer adds the
+  // rds-only aws-param placeholder rewrite on top.
   const updatedContents = contents
-    ?.replace(/\.dev\b/g, '.prep')
-    .replace(/"access":\s*"dev"/, '"access": "prep"')
-    .replace(/"__CHANG3_ME__"/g, '"$.at(aws::param)"');
+    ? withAwsParamPlaceholder({
+        contents: migrateDevConfigToPrep({ contents }),
+      })
+    : contents;
 
   return {
     contents: updatedContents ?? null,
-    relativeFilePath: context.relativeFilePath.replace(
-      /^config\/dev\.json$/,
-      'config/prep.json',
-    ),
+    relativeFilePath: asPrepConfigPath({
+      relativeFilePath: context.relativeFilePath,
+    }),
   };
 };

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

@@ -24,3 +24,35 @@ terraform provisions these ssm parameters for database credentials:
 legacy parameters (kept for backwards compatibility):
 - `{namespace}.database.admin.password`
 - `{namespace}.database.service.password`
+
+## a stateful store gets an alias, never a copy, across the dual-publish transition
+
+the `serverless` + `environments` practices dual-publish each lambda fleet under both slugs
+(`-dev-` ancient, `-prep-` contemp) through the `-dev-`→`-prep-` slug transition. a stateless lambda
+is safe under two names. a stateful store is not.
+
+this RDS cluster (and its SSM credential params, its S3 buckets, its SQS queues) stays one store
+reached by two pointers — a Route53 CNAME, an SSM pointer, or an ARN — never two clusters.
+
+a second `-prep-` RDS cluster is never stood up to satisfy dual-publish. two independent clusters
+form a write-`-dev-`/read-`-prep-` split: the ancient fleet writes one, the contemp fleet reads the
+other, and the divergence stays silent until data is absent. the alias points at the one cluster.
+
+no data migration is needed: the runtime DB path resolves `config.database.tunnel.lambda.host` (see
+`src/utils/database/getOneDatabaseConnection.ts`), an access-keyed config value
+(`databaseClusterHost.{prep,prod}`) with no deploy-slug token, so a CNAME re-points the one live
+cluster with zero data moved. which alias mechanism to use is unsettled; the invariant "one store, two
+pointers" holds regardless.
+
+## the provision workflow's rds jobs are gated behind this practice (D28)
+
+`cicd-service`'s `provision.yml` carries 4 rds-coupled jobs — `sql-schema-{prep,prod}` (the
+`.sql-schema-control.yml` callee, driven by this practice's schema + daos) and
+`aws-{prep,prod}-declastruct` (the `provision/aws/resources.ts` wish this practice ships). the gate
+lives in `cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts`: a usecase-aware
+`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
+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

@@ -5,7 +5,7 @@ generates:
     to: src/access/daos
     using:
       log: src/utils/logger#log
-      DatabaseConnection: src/utils/database/getDatabaseConnection#DatabaseConnection
+      DatabaseConnection: src/utils/database/getOneDatabaseConnection#DatabaseConnection
   schema:
     config: codegen.sql.schema.yml
   control: