declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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/*/svc-*/database/role/cicd/for-plan/*\` and",
+  "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:

package/dist/practices/persist-with-rds/best-practice/package.json

@@ -4,10 +4,10 @@
     "yesql": "@declapract{check.minVersion('3.2.2')}"
   },
   "devDependencies": {
-    "sql-code-generator": "@declapract{check.minVersion('0.10.1')}",
-    "sql-dao-generator": "@declapract{check.minVersion('0.12.0')}",
-    "sql-schema-control": "@declapract{check.minVersion('1.7.0')}",
-    "sql-schema-generator": "@declapract{check.minVersion('0.25.2')}",
+    "sql-code-generator": "@declapract{check.minVersion('0.10.2')}",
+    "sql-dao-generator": "@declapract{check.minVersion('0.13.1')}",
+    "sql-schema-control": "@declapract{check.minVersion('1.8.1')}",
+    "sql-schema-generator": "@declapract{check.minVersion('0.26.1')}",
     "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
     "@types/pg": "@declapract{check.minVersion('8.6.1')}"
   },
@@ -23,7 +23,7 @@
     "provision:testdb:docker:up": "docker compose -f ./provision/docker/testdb/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
     "provision:testdb:docker:await": "docker compose -f ./provision/docker/testdb/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
     "provision:testdb:docker:down": "docker compose -f ./provision/docker/testdb/docker-compose.yml down",
-    "provision:testdb": "npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && npm run provision:schema:plan && npm run provision:schema:apply && npm run provision:schema:plan",
+    "provision:testdb": "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",
     "start:testdb": "npm run provision:testdb",
     "start:livedb:prep": "rhx use.rds.capacity --env prep"
   }

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

@@ -40,8 +40,9 @@ path) maps onto the write-only contract exactly:
 
 - **plan role** (`CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN`): `ssm:DescribeParameters` +
   `ssm:ListTagsForResource` only. NO `ssm:GetParameter`, NO `kms:Decrypt` — it
-  reconciles metadata. its ONE decrypt exception is the `database.role.cicd.for-plan`
-  credential at the config layer.
+  reconciles metadata. its ONE decrypt exception is the
+  `/{org}/{project}/database/role/cicd/for-plan/password` credential — a SLASH path with
+  no tier segment, byte-identical to the arn the policy pins.
 - **apply role** (`CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN`): `ssm:PutParameter` +
   `kms:Encrypt` (default `aws/ssm` key) + the tag write perms. never needs decrypt.
 
@@ -52,10 +53,12 @@ declared `name` must be byte-identical. do NOT reshape the path.
 
 terraform seeded these params under `var.environment`, where the prep account carries
 the legacy `dev` label (see `define.infrastructure-dev-vs-application-prep`). the live
-param NAMES contain that literal `dev`, so `resources.parameters.ts` casts the
-namespace prep→dev. tags do NOT cast — they conform to the access vocab (`prep`), so
-the first apply reconciles the live `environment` tag dev→prep (a metadata-only change,
-no value write).
+CRUD param name contains that literal `dev`, so `resources.parameters.ts` casts the
+dotted crud namespace prep→dev. the two cicd names do NOT cast — they are slash paths
+with no tier segment at all (the aws ACCOUNT separates prep from prod, and the plan
+role's iam pin omits a tier), so they stay byte-identical across every tier. tags do
+NOT cast either — they conform to the access vocab (`prep`), so the first apply
+reconciles the live `environment` tag dev→prep (a metadata-only change, no value write).
 
 ## order of operations (once per env — prep, then prod)
 

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts

@@ -30,13 +30,16 @@ import { getEnvironment } from 'sdk-environment';
 const { access } = getEnvironment.static();
 
 /**
- * .what = the legacy terraform stage label used inside the live param NAMES.
+ * .what = the access as it is SPELLED in the live SSM param NAMES — a legacy slug.
  * .why = terraform seeded these params under var.environment, where the prep account carried the
- *        legacy `dev` label (see define.infrastructure-dev-vs-application-prep). the live param
+ *        legacy `dev` slug (see define.infrastructure-dev-vs-application-prep). the live param
  *        names contain that literal string, so the dotted namespace casts prep→dev. test/prod are
  *        unchanged. (tags do NOT cast — they conform to the access vocab; see `secret` below.)
+ * .note = this is NOT the lambda-fleet slug bridge `sdkAwsLambdaEnvAccessAncient`, which collapses
+ *        BOTH test and prep to `dev`. here test keeps its own name, because this casts a literal
+ *        legacy SSM param string, not a fleet slug — a deliberately narrower cast, not a drifted copy.
  */
-const stage = access === 'prep' ? 'dev' : access;
+const accessSlug = access === 'prep' ? 'dev' : access;
 
 /**
  * .what = declare a secret ssm parameter for adoption (write-only, default key).
@@ -46,9 +49,9 @@ const stage = access === 'prep' ? 'dev' : access;
  *        org access vocab (`prep`, not the legacy `dev`), so the first apply reconciles the live
  *        `environment` tag from dev→prep (a metadata-only change, no value write).
  */
-const secret = (name: string): DeclaredAwsSsmParameterSecure =>
+const secret = (input: { name: string }): DeclaredAwsSsmParameterSecure =>
   DeclaredAwsSsmParameterSecure.as({
-    name,
+    name: input.name,
     keyId: null, // default aws/ssm key (matches the terraform resources)
     description: null,
     tags: {
@@ -61,22 +64,38 @@ const secret = (name: string): DeclaredAwsSsmParameterSecure =>
 
 /**
  * .what = the full set of secret ssm parameters this wish declares.
- * .why = the db-role credentials the service + migrations use. declared for every access tier —
+ * .why = the db-role credentials the service + migrations use. declared for every access —
  *        no per-tier conditional. only prep + prod ever APPLY this wish (there is no
  *        aws-test-declastruct provision job — see .github/workflows/provision.yml), so the
  *        value-less-absent throw on apply cannot trigger in test. test sources its non-sensitive
  *        db creds straight from config/test.json and never reconciles these params.
- * .note = the for-plan credential is the plan role's one decrypt exception; its name is pinned in
- *         the prod plan role's iam policy, so it MUST stay byte-identical.
+ * .note = the two cicd credentials are pinned in the prod plan role's iam policy as SLASH paths
+ *         with NO tier segment — `parameter/*/svc-*/database/role/cicd/for-plan/*` and
+ *         `.../for-apply/*`. that pin's arn needs literal `/` separators after `parameter/`, so a
+ *         dotted name cannot match it and the plan role gets ciphertext or a denial, forever. it
+ *         omits a tier segment on purpose: the aws ACCOUNT separates prep from prod, never the
+ *         name. so the for-plan name MUST stay byte-identical to the pin. the crud credential is
+ *         pinned by NO policy, so it keeps the dotted `${org}.${project}.${accessSlug}` name that
+ *         config/${env}.json matches — hence the three names differ in shape by design, not by
+ *         accident.
  */
-export const getParameters = (): DeclaredAwsSsmParameterSecure[] => {
-  // dotted namespace that prefixes the env-scoped param names
+export const getAllParameters = (input: {
+  accessSlug: string | null;
+}): DeclaredAwsSsmParameterSecure[] => {
+  // dotted namespace that prefixes the env-scoped crud param name
   // keep in sync with terraform local.parameter_store_namespace + config/${env}.json
-  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${stage}`;
+  const slug = input.accessSlug ?? accessSlug;
+  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${slug}`;
 
   return [
-    secret(`${namespace}.database.role.crud.password`),
-    secret(`${namespace}.database.role.cicd.for-plan.password`),
-    secret(`${namespace}.database.role.cicd.for-apply.password`),
+    // crud: dotted + tier-scoped, matched by config/${env}.json; no policy pins it
+    secret({ name: `${namespace}.database.role.crud.password` }),
+    // cicd: SLASH path, NO tier segment — byte-identical to the prod plan role's iam pin
+    secret({
+      name: `/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-plan/password`,
+    }),
+    secret({
+      name: `/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-apply/password`,
+    }),
   ];
 };

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.ts

@@ -3,14 +3,17 @@ import { getDeclastructAwsProvider } from 'declastruct-aws';
 import type { DomainEntity } from 'domain-objects';
 import { genLogMethods } from 'sdk-logs';
 
-import { getParameters } from './resources.parameters';
+import { getAllParameters } from './resources.parameters';
 
 /**
  * .what = the declastruct wish for this service's aws resources.
  * .why = declastruct-aws owns the ssm parameters that terraform now forgets (see
  *        provision/aws/product/parameter-store.tf). the plan role reconciles secrets
- *        WITHOUT any ssm:GetParameter or kms:Decrypt; apply writes via PutParameter +
+ *        without any ssm:GetParameter or kms:Decrypt; apply writes via PutParameter +
  *        kms:Encrypt.
+ * .name = `getProviders` + `getResources` are declastruct's REQUIRED wish entrypoint names, so
+ *         both are exempt from the get-set-gen One/All cardinality rule (a `getAll*` rename makes
+ *         declastruct find no entrypoint — the wish dies). external-framework contract names.
  */
 
 export const getProviders = async (): Promise<DeclastructProvider[]> => [
@@ -24,4 +27,4 @@ export const getProviders = async (): Promise<DeclastructProvider[]> => [
 ];
 
 export const getResources = async (): Promise<DomainEntity<any>[]> =>
-  getParameters();
+  getAllParameters({ accessSlug: null });

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/wait-for-postgres.sh

@@ -1,15 +1,25 @@
 #!/bin/sh
+set -eu
 # wait until postgres is really available
 maxcounter=45
 
 echo "waiting for postgres server to begin accepting connections..."
 counter=1
-while ! psql "dbname=$POSTGRES_DB host=localhost user=postgres password=$POSTGRES_PASSWORD port=5432" -c '\l' > /dev/null 2>&1; do
+# 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 "we have been waiting for postgres too long already; failing"
+        >&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 successfuly"
+echo "connected to postgres instance successfully"

package/dist/practices/persist-with-rds/best-practice/provision/schema/deploy.database.sh

@@ -1,5 +1,5 @@
 #####################################################
-## initilize the database in a live cluster
+## 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
@@ -17,43 +17,48 @@
 ## ```
 #####################################################
 
-# check that user has defined the environment that they want this key created for correctly
-ENVIRONMENT=$1;
+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 1;
+  echo "\nerror: environment, the first argument, must be specified as either 'prod' or 'prep'. you specified '$ENVIRONMENT'";
+  exit 2;
 fi
 
-# check that user is authed into correct account
+# 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 1;
+  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
+POSTGRES_ADMIN_PASSWORD="${2:-}"
+if [ -z "${POSTGRES_ADMIN_PASSWORD:-}" ]; then
   echo "\nerror: POSTGRES_ADMIN_PASSWORD must be defined as second arg";
-  exit 1;
+  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 running this"
-    exit 1;
+  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 1;
+    exit 2;
   fi;
 fi;
 
 
-# define the postgres connecition string
+# 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
@@ -65,24 +70,24 @@ SRC_DIR=$(dirname $SRC_PATH);
 INIT_SQLS_DIR=$SRC_DIR/sql/init;
 
 # run the create database command on root db
-echo "\n 🔨 creating the database..."
+echo "\n 🔨 create the database..."
 psql $ROOT_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.database.sql
 
-echo "\n 🔨 installing the extensions..."
+echo "\n 🔨 install the extensions..."
 psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.extensions.sql
 
-echo "\n 🔨 creating the schema..."
+echo "\n 🔨 create the schema..."
 psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.schema.sql
 
 if [ "$ENVIRONMENT" = "prod" ]; then
-  echo "\n 🔨 granting reads to the datalakedb user..." # only in prod env; we dont want prep's test data in our datalake
+  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 🔨 creating the cicd user..."
+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 when creating the cicd user
+  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

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -15,16 +15,23 @@ export type Grant = 'plan' | 'apply';
  * .note = grant is a per-schema arg, NOT read from env here; getConfig picks which
  *         schema to parse with at call time (see getConfig.ts).
  */
-const getSchema = <TGrant extends Grant>(grant: TGrant) => {
+const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
   // required by default; optional only under grant=plan. generic on the LITERAL
   // TGrant so each schema infers monomorphically (all-required for apply,
   // reader-denied-optional for plan) instead of the widened union.
-  // .note on `as`: a conditional return type cannot be proven from the runtime
-  //   ternary, so TS needs this one assertion. it is sound — the branch matches
-  //   TGrant exactly (plan => .optional(), apply => schema).
   const secret = <T extends z.ZodTypeAny>(
     schema: T,
   ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
+    // as-cast — why types miss: TS cannot relate a conditional return type
+    //   (`TGrant extends 'plan' ? … : …`) to a runtime `grant === 'plan'`
+    //   ternary; the two are unrelated to the checker, so the ternary widens to
+    //   `ZodOptional<T> | T` and does not fit the declared conditional return.
+    // correct type: the value IS `ZodOptional<T>` when TGrant='plan' and `T`
+    //   otherwise — exactly the declared return; the runtime branch matches the
+    //   type branch one-to-one, so the assertion is sound.
+    // removal path: TS learns to relate a conditional return type to a runtime
+    //   discriminant check (microsoft/TypeScript#33912), or the caller splits
+    //   into two monomorphic overloads that never share this body.
     (grant === 'plan' ? schema.optional() : schema) as TGrant extends 'plan'
       ? z.ZodOptional<T>
       : T;
@@ -88,8 +95,8 @@ const getSchema = <TGrant extends Grant>(grant: TGrant) => {
  * .why = getConfig picks which to parse with by grant (see getConfig.ts).
  */
 export const schema = {
-  apply: getSchema('apply'),
-  plan: getSchema('plan'),
+  apply: getOneSchema('apply'),
+  plan: getOneSchema('plan'),
 } as const;
 
 /**

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.integration.test.ts

@@ -0,0 +1,10 @@
+import { getOneDatabaseConnection } from './getOneDatabaseConnection';
+
+describe('getOneDatabaseConnection', () => {
+  it('should be able to connect and execute a query', async () => {
+    const dbConnection = await getOneDatabaseConnection();
+    const result = await dbConnection.query({ sql: 'select 1' });
+    expect(result.rows.length).toEqual(1);
+    await dbConnection.end();
+  });
+});