declapract-typescript-ehmpathy 0.49.13 → 0.49.15

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

@@ -1,5 +1,5 @@
 language: postgres
-dialect: 10.7
+dialect: 17
 declarations: provision/schema/domain/index.ts
 generates:
   sql:

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

@@ -1,5 +1,5 @@
 language: postgres
-dialect: 10.7
+dialect: 17
 resources: # where to find your tables, functions, views, procedures
   - 'provision/schema/sql/tables/**/*.sql'
   - 'provision/schema/sql/views/**/*.sql'

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

@@ -21,8 +21,12 @@
       }
     },
     "tunnel": {
-      "bastion": "vpc-main-bastion",
-      "cluster": "@declapract{variable.databaseName}",
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
       "local": {
         "host": "@declapract{variable.databaseTunnelHost.prep}",
         "port": 15432

package/dist/practices/persist-with-rds/best-practice/config/prep.json.declapract.ts

@@ -1,15 +1,11 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
 
-export const check = FileCheckType.CONTAINS;
-
-export const fix: FileFixFunction = (contents, context) => {
-  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
-
-  return {
-    contents: JSON.stringify(
-      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
-      null,
-      2,
-    ),
-  };
-};
+/**
+ * .what = the contents, check, and fix that deep-merge the rds keys into config/prep.json.
+ * .why  = a deep merge adds the absent rds keys and keeps the leaves a repo holds on purpose, so an
+ *         apply never clobbers a value a service tuned (#638, #683); see genRdsConfigDeclaration.
+ */
+export const { contents, check, fix } = genRdsConfigDeclaration({
+  env: 'prep',
+  templatePath: `${__dirname}/prep.json`,
+});

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

@@ -21,8 +21,12 @@
       }
     },
     "tunnel": {
-      "bastion": "vpc-main-bastion",
-      "cluster": "@declapract{variable.databaseName}",
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
       "local": {
         "host": "@declapract{variable.databaseTunnelHost.prod}",
         "port": 15433

package/dist/practices/persist-with-rds/best-practice/config/prod.json.declapract.ts

@@ -1,15 +1,11 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
 
-export const check = FileCheckType.CONTAINS;
-
-export const fix: FileFixFunction = (contents, context) => {
-  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
-
-  return {
-    contents: JSON.stringify(
-      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
-      null,
-      2,
-    ),
-  };
-};
+/**
+ * .what = the contents, check, and fix that deep-merge the rds keys into config/prod.json.
+ * .why  = a deep merge adds the absent rds keys and keeps the leaves a repo holds on purpose, so an
+ *         apply never clobbers a value a service tuned (#638); see genRdsConfigDeclaration.
+ */
+export const { contents, check, fix } = genRdsConfigDeclaration({
+  env: 'prod',
+  templatePath: `${__dirname}/prod.json`,
+});

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

@@ -21,8 +21,12 @@
       }
     },
     "tunnel": {
-      "bastion": "vpc-main-bastion",
-      "cluster": "@declapract{variable.databaseName}",
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
       "local": {
         "host": "localhost",
         "port": 7821

package/dist/practices/persist-with-rds/best-practice/config/test.json.declapract.ts

@@ -1,15 +1,11 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
 
-export const check = FileCheckType.CONTAINS;
-
-export const fix: FileFixFunction = (contents, context) => {
-  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
-
-  return {
-    contents: JSON.stringify(
-      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
-      null,
-      2,
-    ),
-  };
-};
+/**
+ * .what = the contents, check, and fix that deep-merge the rds keys into config/test.json.
+ * .why  = a deep merge adds the absent rds keys and keeps the leaves a repo holds on purpose, so an
+ *         apply never clobbers a value a service tuned (#638); see genRdsConfigDeclaration.
+ */
+export const { contents, check, fix } = genRdsConfigDeclaration({
+  env: 'test',
+  templatePath: `${__dirname}/test.json`,
+});

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

@@ -1,5 +1,6 @@
 {
   "dependencies": {
+    "iso-time": "@declapract{check.minVersion('1.11.7')}",
     "pg": "@declapract{check.minVersion('8.3.0')}",
     "yesql": "@declapract{check.minVersion('3.2.2')}"
   },
@@ -11,18 +12,23 @@
     "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
     "@types/pg": "@declapract{check.minVersion('8.6.1')}"
   },
+  "pnpm": {
+    "patchedDependencies": {
+      "pg-pool": "patches/pg-pool.patch"
+    }
+  },
   "scripts": {
-    "generate:dao:postgres": "npx sql-dao-generator generate && npm run fix:format",
-    "generate:schema": "npx sql-schema-generator generate -c codegen.sql.schema.yml && npm run fix:format",
-    "generate:types-from-sql": "npx sql-code-generator generate -c codegen.sql.types.yml && npm run fix:format",
-    "provision:schema:plan": "npx sql-schema-control plan -c provision/schema/control.yml",
-    "provision:schema:apply": "npx sql-schema-control apply -c provision/schema/control.yml",
-    "provision:schema:sync": "npx sql-schema-control sync -c provision/schema/control.yml",
-    "provision:testdb:docker:clear": "for port in $(docker compose -f ./provision/docker/testdb/docker-compose.yml config --format json | jq -r '.services[].ports[]?.published'); do docker rm -f $(docker ps -a -f \"publish=$port\" -q) 2>/dev/null || true; done && echo 'ensured ports are available 👍'",
+    "generate:dao:postgres": "sql-dao-generator generate && npm run fix:format",
+    "generate:schema": "sql-schema-generator generate -c codegen.sql.schema.yml && npm run fix:format",
+    "generate:types-from-sql": "sql-code-generator generate -c codegen.sql.types.yml && npm run fix:format",
+    "provision:schema:plan": "sql-schema-control plan -c provision/schema/control.yml",
+    "provision:schema:apply": "sql-schema-control apply -c provision/schema/control.yml",
+    "provision:schema:sync": "sql-schema-control sync -c provision/schema/control.yml",
+    "provision:testdb:docker:clear": "for port in $(bash provision/docker/testdb/compose.sh config --format json | jq -r '.services[].ports[]?.published'); do docker rm -f $(docker ps -a -f \"publish=$port\" -q) 2>/dev/null || true; done && echo 'ensured ports are available 👍'",
     "provision:testdb:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/testdb/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/testdb/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/testdb/init/user.cicd.sql",
-    "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:docker:up": "bash provision/docker/testdb/compose.sh up -d --force-recreate --build --renew-anon-volumes",
+    "provision:testdb:docker:await": "bash provision/docker/testdb/compose.sh exec -T postgres /root/wait-for-postgres.sh",
+    "provision:testdb:docker:down": "bash provision/docker/testdb/compose.sh 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 && 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/patches/pg-pool.patch

@@ -0,0 +1,21 @@
+.what = drops pg-pool's lazy `require('pg')` fallback, so dpdm sees no pg <-> pg-pool require cycle
+.why  = pg passes its own Client into every pool it builds, so the fallback never runs under pg; but
+        dpdm reads it statically, and `test:lint:cycles` checks node_modules (exclude: []) by policy
+.note = shipped by declapract-typescript-ehmpathy, practice persist-with-rds. if pnpm warns that this
+        patch failed to apply, pg-pool moved the line: upgrade declapract-typescript-ehmpathy and
+        re-apply. if no fix has shipped yet, pin your own `pg-pool@<version>` patch: an exact key
+        outranks this bare one. code that calls `new Pool()` from pg-pool directly must pass
+        `{ Client: require('pg').Client }`. after an apply, run `pnpm install` and commit the
+        lockfile: it records this file's hash.
+.recut = keep one context line on each side of the changed line. wider context misfits older
+        pg-pool releases, and pnpm then warns and installs pg-pool unpatched. edit this file only
+        when the hunk must move: its hash sits in every adopter's lockfile, header included.
+
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -94,3 +94,3 @@ class Pool extends EventEmitter {
+     this.log = this.options.log || function () {}
+-    this.Client = this.options.Client || Client || require('pg').Client
++    this.Client = this.options.Client || Client
+     this.Promise = this.options.Promise || global.Promise

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

@@ -3,7 +3,7 @@
 the declastruct-aws wish for this service's aws resources.
 
 - `resources.ts` — the wish entrypoint (providers + `getResources`).
-- `resources.parameters.ts` — the secret SSM parameters, adopted from terraform.
+- `resources.parameters.ts` — the secret ssm parameters, adopted from terraform.
 - `product/parameter-store.tf` — the terraform FORGET blocks (transitional).
 
 ## why declastruct-aws, not terraform
@@ -19,19 +19,63 @@ drifted. that hides real drift and forces the secret through terraform state.
 | plan  | never        | no kms:Decrypt | DescribeParameters (metadata only) |
 | apply | only when a value is supplied | kms:Encrypt | PutParameter |
 
-## adoption by absence (no seed machinery)
+## the param names
 
-the go-forward params ALREADY hold their values in aws — terraform seeded them once,
-and the values live only there. so the wish supplies **no `value`**: a value-less
-secret is write-only KEEP. plan reports KEEP for every extant param and never reads or
-rewrites it. there is no value to "move" or "seed" — adoption is pure KEEP.
+each name is the one sdk-config (>= 0.3.0) derives for a bare `$.at(aws::param)` in
+`config/{env}.json`:
 
-- a **CREATE at plan** means the declared name does not match a live param → STOP and
-  fix the name.
+```
+/{org}/{project}/{config}/{keyPath}
+```
+
+| config key | ssm name (prep) |
+| ---------- | --------------- |
+| `database.role.crud.password` | `/{org}/{project}/prep/database.role.crud.password` |
+| `database.role.cicd.for-plan.password` | `/{org}/{project}/prep/database.role.cicd.for-plan.password` |
+| `database.role.cicd.for-apply.password` | `/{org}/{project}/prep/database.role.cicd.for-apply.password` |
+
+the config segment is the CONFIG slug (`CONFIG`), never the access: config's reader, the
+oidc iam policy, and the declared `name` must be byte-identical.
+
+## adoption by absence
+
+the wish supplies **no `value`**: a value-less secret is write-only KEEP. plan reports
+KEEP for every extant param and never reads or rewrites it.
+
+- a **CREATE at plan** means no live param holds that name yet → copy its value first
+  (below), never let the apply create it.
 - a value-less secret that is **ABSENT** throws on apply (declastruct-aws
-  `setSsmParameterSecure`). the wish declares the db-role creds for every tier with no
-  per-tier conditional; only prep + prod apply it (there is no `aws-test-declastruct`
-  provision job), so the absent-throw never triggers in test.
+  `setSsmParameterSecure`). only prep + prod apply the wish, so test never meets it.
+
+## copy params to the derived names (before the first plan at a new name)
+
+a repo whose values sit at a prior name holds no value at the derived name, so its
+first `provision` apply throws at the absent param. copy each value first, per env
+(prep, then prod). a copy keeps the source param, so it is safe to repeat.
+
+| prior name | derived name |
+| ---------- | ------------ |
+| `{org}.{project}.{dev\|prod}.database.role.crud.password` | `/{org}/{project}/{config}/database.role.crud.password` |
+| `/{org}/{project}/database/role/cicd/for-plan/password` | `/{org}/{project}/{config}/database.role.cicd.for-plan.password` |
+| `/{org}/{project}/database/role/cicd/for-apply/password` | `/{org}/{project}/{config}/database.role.cicd.for-apply.password` |
+
+where the roles were also renamed (`role.admin` / `role.service` in an older config), the
+values move with the rename:
+
+| prior role | derived name it seeds |
+| ---------- | --------------------- |
+| `admin` | `/{org}/{project}/{config}/database.role.cicd.for-plan.password` |
+| `admin` | `/{org}/{project}/{config}/database.role.cicd.for-apply.password` |
+| `service` | `/{org}/{project}/{config}/database.role.crud.password` |
+
+the copy is a manual aws ssm step, run with the access for the env:
+
+```sh
+VALUE=$(aws ssm get-parameter --with-decryption --name "<prior name>" --query Parameter.Value --output text)
+aws ssm put-parameter --type SecureString --name "<derived name>" --value "$VALUE"
+```
+
+then set each `config/{env}.json` password to the bare `$.at(aws::param)`.
 
 ## iam boundary (the two oidc roles)
 
@@ -41,39 +85,29 @@ 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
-  `/{org}/{project}/database/role/cicd/for-plan/password` credential — a SLASH path with
-  no tier segment, byte-identical to the arn the policy pins.
+  `/{org}/{project}/{config}/database.role.cicd.for-plan.password` credential.
 - **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.
 
-the param **name** is the join point: config's reader, the oidc iam policy, and the
-declared `name` must be byte-identical. do NOT reshape the path.
-
-## the prep→dev name cast
-
-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
-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).
+tags conform to the access vocab (`prep`), so an apply reconciles a live `dev` tag to
+`prep` (a metadata-only change, no value write).
 
 ## order of operations (once per env — prep, then prod)
 
 the handoff is lossless because terraform forgets the param without a destroy of the
 live value. run ONCE per env, in order:
 
-1. apply the `terraform-parameters` bad-practice (`declapract fix`) — it rewrites every
+1. copy params to the derived names (above).
+2. `npx declapract apply` — the `terraform-parameters` bad-practice rewrites every
    `resource "aws_ssm_parameter"` in `product/parameter-store.tf` into a `removed{}`
-   forget block (`destroy = false`) and drops the `data` reads. requires terraform
-   >= 1.7 (bump `versions.tf#required_version` if below).
-2. `terraform apply` (the `aws-*-terraform` provision jobs) — terraform drops the
+   forget block (`destroy = false`) and drops the `data` reads; a forget of an
+   admin/service param names its copy target in a comment. requires terraform >= 1.7
+   (bump `versions.tf#required_version` if below).
+3. `terraform apply` (the `aws-*-terraform` provision jobs) — terraform drops the
    params from state; live values untouched. 🚩 if the plan shows any
    `DeleteParameter`, STOP — the forget is wrong.
-3. declastruct plan/apply the wish (the `aws-*-declastruct` provision jobs) — plan
-   shows KEEP for every param (no decrypt). a CREATE means a name mismatch → STOP.
+4. declastruct plan/apply the wish (the `aws-*-declastruct` provision jobs) — plan
+   shows KEEP for every param (no decrypt). a CREATE means a value was not copied → STOP.
 
 after both land in every env, the `removed{}` blocks (and this transitional tf file)
 can be pruned in a follow-up.

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

@@ -3,56 +3,31 @@ import { getEnvironment } from 'sdk-environment';
 
 /**
  * .what = the secret ssm parameters this service manages via declastruct.
- * .why = these params were migrated off terraform (provision/aws/product/parameter-store.tf,
- *        now a forget). declastruct-aws owns them. every param is a real secret, so each is a
- *        DeclaredAwsSsmParameterSecure (write-only): the plan role reads metadata only
- *        (DescribeParameters + ListTagsForResource — no GetParameter, no kms:Decrypt), and the
- *        value is never read back.
- * .note = adoption supplies NO `value`: the live values were seeded once by terraform and live
- *         only in aws. a value-less secret is write-only KEEP, so plan reports KEEP for extant
- *         params and never rewrites them. a CREATE at plan means the name does not match a live
- *         param — stop and fix. (a value-less secret that is ABSENT throws on apply, per
- *         declastruct-aws setSsmParameterSecure. only prep + prod apply this wish — there is no
- *         aws-test-declastruct job — so the params are declared for every tier without a
- *         conditional, and the absent-throw never triggers in test.)
- * .scope = only the db-role credentials the service + migrations use are managed here. any
- *          service-specific secrets (third-party api keys, etc) are declared alongside these by
- *          the service that owns them. legacy param names with zero consumers are left unmanaged
- *          (terraform forgets them, no delete touches the live values) and can be pruned from aws
- *          once confirmed unreferenced everywhere.
+ * .why = declastruct-aws owns them, off terraform (provision/aws/product/parameter-store.tf is a
+ *        forget). each is a write-only DeclaredAwsSsmParameterSecure: plan reads metadata only and
+ *        never the value.
+ * .note = no `value` is supplied: plan KEEPs an extant param and never rewrites it. a value-less
+ *         param that is ABSENT throws on apply (declastruct-aws setSsmParameterSecure). only prep
+ *         and prod apply this wish, so test never meets that throw.
+ * .scope = the db-role credentials only. a service declares its own other secrets beside these.
  */
 
 /**
- * .what = the conformed environment this wish runs in (access ∈ test | prep | prod).
- * .why = resolved once, as a module global, via sdk-environment's getEnvironment (reads the
- *        ACCESS envar). the wish speaks the org-standard access vocab everywhere it can.
+ * .what = the environment this wish runs in.
+ * .why = `config` NAMES each param (the segment sdk-config derives); `access` TAGS it. the two may
+ *        differ (ACCESS=prep CONFIG=prod is legal), and the app reads the params of its config.
  */
-const { access } = getEnvironment.static();
-
-/**
- * .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` 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 accessSlug = access === 'prep' ? 'dev' : access;
+const { access, config } = getEnvironment.static();
 
 /**
  * .what = declare a secret ssm parameter for adoption (write-only, default key).
- * .why = every param here is a secret whose value already lives in aws; we supply no `value` so
- *        plan KEEPs the extant value and never reads or rewrites it. keyId=null selects the
- *        account default aws/ssm key (what terraform used, no kms_key_id). tags conform to the
- *        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).
+ * .why = the value already lives in aws, so plan KEEPs it and never reads or rewrites it.
+ *        keyId=null selects the account default aws/ssm key.
  */
 const secret = (input: { name: string }): DeclaredAwsSsmParameterSecure =>
   DeclaredAwsSsmParameterSecure.as({
     name: input.name,
-    keyId: null, // default aws/ssm key (matches the terraform resources)
+    keyId: null, // default aws/ssm key
     description: null,
     tags: {
       app: '@declapract{variable.organizationName}',
@@ -64,43 +39,22 @@ const secret = (input: { 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 —
- *        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 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.
+ * .why = each name is the one sdk-config derives for a bare `$.at(aws::param)` placeholder in
+ *        config/{env}.json: `/{org}/{project}/{config}/{keyPath}`. the provision declares exactly
+ *        the names the app reads.
+ * .note = @declapract:review — a param whose value still sits only at a prior name has no value
+ *         here, and its first apply throws at the absent param. copy each value to its derived
+ *         name first (see provision/aws/readme.md, "copy params to the derived names").
  */
 export const getAllParameters = (input: {
-  accessSlug: string | null;
+  choice: 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 slug = input.accessSlug ?? accessSlug;
-  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${slug}`;
+  // the derived namespace: org, project, then the config slug as the segment
+  const namespace = `/@declapract{variable.organizationName}/@declapract{variable.projectName}/${input.choice ?? config}`;
 
   return [
-    // 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`,
-    }),
+    secret({ name: `${namespace}/database.role.crud.password` }),
+    secret({ name: `${namespace}/database.role.cicd.for-plan.password` }),
+    secret({ name: `${namespace}/database.role.cicd.for-apply.password` }),
   ];
 };

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

@@ -27,4 +27,4 @@ export const getProviders = async (): Promise<DeclastructProvider[]> => [
 ];
 
 export const getResources = async (): Promise<DomainEntity<any>[]> =>
-  getAllParameters({ accessSlug: null });
+  getAllParameters({ choice: null });

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/build-image.dockerfile.declapract.ts

@@ -0,0 +1,37 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+const POSTGRES_PIN_LINE = /^FROM postgres:\S+$/m;
+
+/**
+ * .what = the declared image, with the repo's own postgres pin kept in place of the template's
+ * .why = each repo pins the testdb to its own livedb's major, and the majors differ across the
+ *        fleet. an exact compare would move every testdb onto the template's pin, which lands
+ *        some ahead of their livedb — the skew where a suite passes on sql the livedb rejects.
+ *        check-engine-skew.sh guards that the pin never leads the livedb (#664)
+ */
+const asDeclaredWithPinFound = (input: {
+  declared: string;
+  found: string | null;
+}): string => {
+  const pinFound = input.found?.match(POSTGRES_PIN_LINE)?.[0];
+  if (!pinFound) return input.declared;
+  return input.declared.replace(POSTGRES_PIN_LINE, pinFound);
+};
+
+export const check: FileCheckFunction = (contents, context) => {
+  const expected = asDeclaredWithPinFound({
+    declared: context.declaredFileContents!,
+    found: contents,
+  });
+  if (contents === expected) return; // the image matches, whatever postgres major it pins
+  throw new Error(
+    'best practice violated: build-image.dockerfile must match the template, with any `FROM postgres:<version>` pin',
+  );
+};
+
+export const fix: FileFixFunction = (contents, context) => ({
+  contents: asDeclaredWithPinFound({
+    declared: context.declaredFileContents!,
+    found: contents,
+  }),
+});