declapract-typescript-ehmpathy 0.49.13 → 0.49.14

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -12,18 +12,45 @@ we use:
 | `databaseTunnelHost.{prep,prod}` | ssm proxy host for database tunnel | `aws.ssmproxy.ahbodedb.prep` |
 | `databaseClusterHost.{prep,prod}` | rds cluster endpoint | `ahbodedb.cluster-xxx.us-east-1.rds.amazonaws.com` |
 
+## optional variables
+
+| variable | description | default |
+|----------|-------------|---------|
+| `databaseClusterName` (or `databaseClusterName.{prep,prod}`) | the rds cluster the vpc tunnel targets (`database.tunnel.cluster.name`) | the first label of `databaseClusterHost.{env}` |
+
+set it only when the cluster endpoint is a custom dns alias whose first label is not the
+cluster identifier. a hand-set `database.tunnel.cluster.name` in a repo's own config is kept.
+
 ## ssm parameters
 
-terraform provisions these ssm parameters for database credentials:
+the provision wish (`provision/aws/resources.parameters.ts`) declares the db credentials at the
+names sdk-config derives for a bare `$.at(aws::param)`:
 
 | parameter name | description | environments |
 |----------------|-------------|--------------|
-| `{namespace}.database.role.cicd.password` | password for cicd database user | prep, prod |
-| `{namespace}.database.role.crud.password` | password for crud database user | prep, prod |
+| `/{org}/{project}/{config}/database.role.cicd.for-plan.password` | password for the cicd plan user | prep, prod |
+| `/{org}/{project}/{config}/database.role.cicd.for-apply.password` | password for the cicd apply user | prep, prod |
+| `/{org}/{project}/{config}/database.role.crud.password` | password for the crud user | prep, prod |
+
+a repo whose values sit at a prior name (or under `role.admin` / `role.service`) copies them to
+these names before its first provision apply — the map is in `provision/aws/readme.md`.
+
+prep users are created with the `__CHANG3_ME__` password by `provision/schema/deploy.database.sh`,
+so `config/prep.json` accepts either `__CHANG3_ME__` or `$.at(aws::param)` at each password.
+
+## config grants
+
+`src/utils/config/config.schema.ts` exports one schema per oidc grant:
+
+- `apply` (the default: the apply job, the cloud runtime, local dev, tests) requires every secret,
+  so `Config` carries no `| undefined` and consumers need no guards
+- `plan` marks `role.cicd.for-apply.password` and `role.crud.password` optional. the prod plan
+  job's oidc role may read only the for-plan credential, and sdk-config substitutes `undefined`
+  for each param a role is denied
+- `for-plan` and `for-apply` each carry a username, since a plan job may map to a readonly db user
 
-legacy parameters (kept for backwards compatibility):
-- `{namespace}.database.admin.password`
-- `{namespace}.database.service.password`
+the grant is an argument, never read inside the schema; `getConfig` picks the schema at call time
+(see the `config` practice readme).
 
 ## a stateful store gets an alias, never a copy, across the dual-publish transition
 
@@ -53,6 +80,6 @@ lives in `cicd-service/best-practice/.github/workflows/provision.yml.declapract.
 `contents` fn emits those 4 jobs **only** when `persist-with-rds` is in the resolved practice set, so
 a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) does not inherit a
 `provision` workflow that references files it lacks. it uses `CONTAINS`, not `EQUALS`, so a narrow
-`declapract fix --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
+`declapract apply --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
 EQUALS hazard). if you add a new rds-coupled provision job, add it to that gate the same way — a
 caller that names a callee this practice supplies must be reconciled against this practice's presence.

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

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

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

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

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')}"
   },
@@ -12,17 +13,17 @@
     "@types/pg": "@declapract{check.minVersion('8.6.1')}"
   },
   "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/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.