declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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,43 @@ 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/<star>/svc-<star>/database/role/cicd/for-plan/<star>`
+ *         and `.../for-apply/<star>`. 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.
+ * .note = `<star>` stands in for the literal `*` wildcard of that arn, and must stay a stand-in.
+ *         a literal `*` written immediately before a `/` closes this comment mid-prose, so every
+ *         character after it is read as code and the file no longer parses — which breaks
+ *         `pnpm fix` in every repo that adopts this template, with no repair available to them
+ *         (declapract apply restores these bytes). see #613.
  */
-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();
+  });
+});

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

@@ -0,0 +1,90 @@
+import { HelpfulError, UnexpectedCodePathError } from 'helpful-errors';
+import pg, { Client, type QueryResult, type QueryResultRow } from 'pg';
+
+import { getConfig } from '../config/getConfig';
+import { getEnvironment } from '../environment';
+
+// https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
+pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
+pg.types.setTypeParser(1700, (value) => parseFloat(value)); // cast numerics to numbers; by default, pg returns numerics as strings
+
+export interface DatabaseConnection {
+  query: <Row extends QueryResultRow>(args: {
+    sql: string;
+    values?: unknown[];
+  }) => Promise<QueryResult<Row>>;
+  end: () => Promise<void>;
+}
+
+export class DatabaseQueryError extends HelpfulError {
+  constructor({
+    sql,
+    values,
+    caught,
+  }: {
+    sql: string;
+    values?: unknown[];
+    caught: Error;
+  }) {
+    const message = `
+caught error querying database: ${caught.message}
+
+sql:
+  ${sql.trim()}
+
+values:
+  ${JSON.stringify(values)}
+    `.trim();
+    super(message, { sql, values, cause: caught });
+  }
+}
+
+export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> => {
+  const environment = await getEnvironment();
+  const config = await getConfig();
+  const target = config.database.target;
+  const role = config.database.role.crud;
+
+  // determine which tunnel to use based on environment.server
+  const tunnel =
+    environment.server === 'cloud@aws.lambda'
+      ? config.database.tunnel.lambda
+      : config.database.tunnel.local;
+
+  // ensure tunnel is defined for the requested server
+  if (!tunnel) {
+    throw new UnexpectedCodePathError(
+      `Database tunnel not configured for environment.server + env.access`,
+      { environment },
+    );
+  }
+
+  // instantiate the client
+  const client = new Client({
+    host: tunnel.host,
+    port: tunnel.port,
+    user: role.username,
+    password: role.password,
+    database: target.database,
+  });
+  await client.connect();
+  await client.query(`SET search_path TO ${target.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
+  const dbConnection = {
+    query: ({ sql, values }: { sql: string; values?: unknown[] }) =>
+      client.query(sql, values),
+    end: () => client.end(),
+  };
+
+  // declare our interface
+  return {
+    query: (args: { sql: string; values?: unknown[] }) =>
+      dbConnection.query(args).catch((error) => {
+        throw new DatabaseQueryError({
+          sql: args.sql,
+          values: args.values,
+          caught: error,
+        });
+      }),
+    end: () => dbConnection.end(),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseContext.ts

@@ -1,7 +1,7 @@
 import {
   DatabaseConnection,
-  getDatabaseConnection,
-} from './getDatabaseConnection';
+  getOneDatabaseConnection,
+} from './getOneDatabaseConnection';
 
 export interface DatabaseContext {
   dbConnection: DatabaseConnection;
@@ -32,11 +32,19 @@ export const withDatabaseContext = <P1, P2 extends DatabaseContext, R>(
   ) => {
     // open the db connection, if one was not given
     const dbConnection =
-      context.dbConnection ?? (await getDatabaseConnection());
+      context.dbConnection ?? (await getOneDatabaseConnection());
 
     // try and run the logic with db connection
     try {
-      return await logic(input, { ...context, dbConnection } as P2); // as P2 because: https://github.com/microsoft/TypeScript/issues/35858
+      // as-cast — why types miss: the input context is `Omit<P2,'dbConnection'> &
+      //   { dbConnection? }`; the spread `{ ...context, dbConnection }` re-adds a
+      //   NON-optional dbConnection, but ts cannot prove a spread of a generic
+      //   `Omit<P2,…> & {…}` reconstitutes the exact `P2` (microsoft/TypeScript#35858).
+      // correct type: the value IS `P2` — every P2 key is present (the omit dropped
+      //   only dbConnection, which the spread restores with a concrete connection).
+      // removal path: ts resolves spread-of-generic to the original type
+      //   (microsoft/TypeScript#35858), or the caller passes a fully-typed P2 in.
+      return await logic(input, { ...context, dbConnection } as P2);
     } finally {
       // make sure to close the db connection, both when `logic` throws an error or succeeds
       if (!context.dbConnection) await dbConnection.end();

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -1,13 +1,25 @@
-import type { DatabaseConnection } from './getDatabaseConnection';
+import type { DatabaseConnection } from './getOneDatabaseConnection';
 
+/**
+ * .what = wraps a logic fn so it runs inside one db transaction: START TRANSACTION,
+ *         run the logic, COMMIT on success, ROLLBACK + rethrow on failure. the
+ *         transaction rides the injected `context.dbConnection`.
+ * .why = gives any logic atomic semantics — every write commits together, or none
+ *        does — without each op repeating the begin/commit/rollback dance. a partial
+ *        write cannot survive a throw.
+ * .note = the wrapper is ALWAYS async — it awaits the transaction — so its honest
+ *         return type is `Promise<Awaited<R>>`, NOT `logic`'s `R | Promise<R>`. the
+ *         return type is declared explicitly so no `as` cast is needed and no type
+ *         lie is told: a caller of a sync `logic` correctly sees a Promise back.
+ */
 export const withDatabaseTransaction = <
   P,
   C extends { dbConnection: DatabaseConnection },
   R,
 >(
   logic: (input: P, context: C) => R | Promise<R>,
-): typeof logic => {
-  return (async (input: P, context: C) => {
+): ((input: P, context: C) => Promise<Awaited<R>>) => {
+  return async (input: P, context: C) => {
     await context.dbConnection.query({ sql: 'START TRANSACTION' }); // begin transaction
     try {
       const result = await logic(input, context); // run the request
@@ -17,5 +29,5 @@ export const withDatabaseTransaction = <
       await context.dbConnection.query({ sql: 'ROLLBACK' }); // rollback if not successful
       throw error;
     }
-  }) as typeof logic;
+  };
 };

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

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #549: the shipped provision/schema/deploy.database.sh carries no gerund
+ *         (-ing) progress-string, comment, or error — imperative/plain verbs only, per
+ *         rule.forbid.gerunds.
+ * .why  = this template is emitted verbatim to every persist-with-rds consumer, and each
+ *         consumer runs the mechanic gerund hook on the emitted file. a gerund in the
+ *         template trips that hook downstream, so each repo re-fixes it and re-diverges from
+ *         the template — the fix must live upstream, here, once.
+ * .teeth = revert any progress-string to its gerund form (e.g. "create the database" ->
+ *          "creating the database") in best-practice/provision/schema/deploy.database.sh and
+ *          the paired "no gerund" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the
+ *         practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('persist-with-rds deploy.database.sh gerund-free', () => {
+  given('the shipped deploy.database.sh', () => {
+    const source = readFileSync(
+      join(__dirname, 'best-practice/provision/schema/deploy.database.sh'),
+      'utf8',
+    );
+
+    // the exact gerund forms #549 removed; none may reappear in the template
+    const forbidden = [
+      'creating',
+      'installing',
+      'granting',
+      'before running this',
+    ];
+
+    when('the template body is read', () => {
+      forbidden.forEach((word) =>
+        then(`it carries no gerund form: "${word}"`, () => {
+          expect(source.includes(word)).toEqual(false);
+        }),
+      );
+
+      then('it keeps the imperative progress strings', () => {
+        expect(source).toContain('🔨 create the database...');
+        expect(source).toContain('🔨 install the extensions...');
+        expect(source).toContain('🔨 create the schema...');
+        expect(source).toContain('🔨 create the cicd user...');
+      });
+
+      then('the emitted deploy.database.sh matches snapshot', () => {
+        // snapshot the whole shipped file so a reworded progress string that stays
+        // gerund-free still reddens a vibecheck in review — the token asserts prove the
+        // gerund class is absent, this proves the exact text (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('deploy.database.sh');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/empty-template-declares-zero-clusters.declapract.integration.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the empty-template invariant the case=7 (stateful-store-alias-not-copy) safety
+ *         rests on: the persist-with-rds declastruct wish declares ZERO rds clusters — `getResources`
+ *         returns only SSM params, and the provision tree imports no cluster/rds/aurora/database
+ *         resource-declaration type.
+ * .why  = case=7's fail-safe is "a lambda under two names is two copies of code; a database under two
+ *         names must be one store with two pointers" — and its load-bearer is that the template holds
+ *         NO cluster for a `fix` to duplicate. a second cluster is the operator's to hand-author,
+ *         against the runbook, never a state the template produces. this is the demoed critipath's
+ *         real test (per `rule.require.experience-catalog-evolution`, a demoed critipath owes a test
+ *         by verification): if a future edit ever declares a cluster in the go-forward wish, the
+ *         "zero clusters to duplicate" premise silently breaks, and this reddens.
+ * .teeth = a cluster resource cannot enter `getResources` without an import of a `DeclaredAws*Cluster`
+ *          / `*Rds` / `*Aurora` / `*Database` type plus its addition to the returned array — so the
+ *          "declares only SSM params" + "imports no cluster type" cases redden the moment one lands.
+ * .note = `.integration.test.ts` because it reads the filesystem (a remote boundary); at the practice
+ *         ROOT (not under best-practice/), so it is neither loaded as a declaration nor copied to a
+ *         consumer. mirrors the source-text clamp in `ssm-cicd-param-names.declapract.integration.test.ts`.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+const resourcesPath = join(__dirname, 'best-practice/provision/aws/resources.ts');
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+// any declastruct-aws resource-declaration type that would name an rds/aurora cluster or database.
+// a cluster resource cannot be declared without one of these, so the negation is the teeth.
+const CLUSTER_TYPE_PATTERN = /Declared\w*(Rds|Cluster|Aurora|Database)/;
+
+describe('persist-with-rds wish declares zero rds clusters (empty-template invariant)', () => {
+  const resources = readFileSync(resourcesPath, 'utf8');
+  const params = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the wish entrypoint resources.ts', () => {
+    when('[t0] resources.ts is read', () => {
+      then('getResources yields only the ssm parameters', () => {
+        expect(resources).toContain('getAllParameters({ accessSlug: null })');
+      });
+
+      then('the wish imports no cluster/rds/aurora/database resource type', () => {
+        expect(resources).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+
+      then('the sole declared aws resource declaration is the ssm parameter secure', () => {
+        // the one resource-declaration import from declastruct-aws is DeclaredAwsSsmParameterSecure
+        // (via resources.parameters.ts). resources.ts itself declares no resource type directly.
+        expect(resources).not.toContain('DeclaredAwsRds');
+        expect(resources).not.toContain('DeclaredAwsAurora');
+      });
+    });
+  });
+
+  given('[case2] the resource set resources.parameters.ts', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('getAllParameters yields a DeclaredAwsSsmParameterSecure array (ssm params only)', () => {
+        expect(params).toContain('DeclaredAwsSsmParameterSecure[]');
+      });
+
+      then('the resource set declares no cluster/rds/aurora/database type', () => {
+        expect(params).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+    });
+  });
+});