declapract-typescript-ehmpathy 0.49.7 → 0.49.8

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

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 
-export const schema = z.object({
+/** .what = the two oidc grant scopes config can be read under. */
+export type Grant = 'plan' | 'apply';
+
+/**
+ * .what = the base config shape, before any grant-scoped secrets are added.
+ * .why = this base template carries no reader-denied secrets, so plan and apply
+ *        infer the same schema. services that add secrets (e.g. api keys, db
+ *        credentials) should make each reader-denied secret grant-aware via a
+ *        secret() helper so the prod plan job's oidc role tolerates the miss —
+ *        see the persist-with-rds config.schema.ts for the full pattern.
+ */
+const base = z.object({
   organization: z.string(),
   project: z.string(),
   environment: z.object({
@@ -12,4 +23,22 @@ export const schema = z.object({
   }),
 });
 
-export type Config = z.infer<typeof schema>;
+/**
+ * .what = one schema per grant. apply = the default (every secret required);
+ *         plan = the reader-denied secrets optional.
+ * .why = getConfig picks which to parse with by grant (see getConfig.ts).
+ */
+export const schema = {
+  apply: base,
+  plan: base,
+} as const;
+
+/**
+ * .what = the config type for a grant, default apply.
+ * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
+ *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
+ *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
+ */
+export type Config<TGrant extends Grant = 'apply'> = z.infer<
+  (typeof schema)[TGrant]
+>;

package/dist/practices/config/best-practice/src/utils/config/getCacheDirectory.ts

@@ -1,3 +1,4 @@
+import { sdkAwsS3 } from 'sdk-aws-s3';
 import type { DirectoryToPersistTo } from 'simple-on-disk-cache';
 import { isPresent } from 'type-fns';
 
@@ -20,14 +21,22 @@ export const getProjectBucket = async (): Promise<string> => {
  * .what = gets the project's default cache directory, based on config
  */
 export const getCacheDirectory = async (
-  input: {
-    scope?: string;
-  } = {},
-): Promise<DirectoryToPersistTo> => ({
-  s3: {
-    bucket: await getProjectBucket(),
-    prefix: ['purpose=cache', input.scope ? `scope=${input.scope}` : undefined]
-      .filter(isPresent)
-      .join('/'),
-  },
-});
+  input: { scope?: string } = {},
+): Promise<DirectoryToPersistTo> => {
+  // build the s3 uri prefix from the project bucket + cache scope
+  const bucket = await getProjectBucket();
+  const prefix = [
+    'purpose=cache',
+    input.scope ? `scope=${input.scope}` : undefined,
+  ]
+    .filter(isPresent)
+    .join('/');
+
+  // persist to s3 via the sdk-aws-s3 cloud adapter
+  return {
+    cloud: {
+      path: `s3://${bucket}/${prefix}`,
+      via: sdkAwsS3,
+    },
+  };
+};

package/dist/practices/config/best-practice/src/utils/config/getConfig.ts

@@ -5,15 +5,46 @@ import {
 import { createCache } from 'simple-in-memory-cache';
 
 import { envStatic } from '../environment';
-import { schema } from './config.schema';
+import { type Config, type Grant, schema } from './config.schema';
 
-export const getConfig = genGetConfig({
-  schema,
-  statics: 'config/*.json',
-  cache: createCache({ expiration: { minutes: 5 } }),
+// one loader per grant. both read the same config/*.json + suppliers; they differ
+// only in which schema arbitrates the reader-denied secrets (see config.schema.ts).
+// caches are separate so a plan miss never poisons the apply cache.
+const common = {
+  statics: 'config/*.json' as const,
   suppliers: [genSdkConfigSupplierAwsParameterStore()],
   environment: {
     config: envStatic.config,
     server: envStatic.server,
   },
-});
+};
+const loaders = {
+  apply: genGetConfig({
+    ...common,
+    schema: schema.apply,
+    cache: createCache({ expiration: { minutes: 5 } }),
+  }),
+  plan: genGetConfig({
+    ...common,
+    schema: schema.plan,
+    cache: createCache({ expiration: { minutes: 5 } }),
+  }),
+} as const;
+
+/**
+ * .what = load the config, scoped to an oidc grant (default apply).
+ * .why = default 'apply' returns the fully-required Config, so ordinary consumers
+ *        get no `| undefined` in their config type. the plan job opts into 'plan'
+ *        (which tolerates the reader-denied secrets) either explicitly via
+ *        { grant: 'plan' } or implicitly via the GRANT=plan env — the latter lets
+ *        the ghlitch vpc tunnel (which calls getConfig() with no args) pick the
+ *        plan scope at runtime without a code change.
+ */
+export function getConfig<TGrant extends Grant = 'apply'>(input?: {
+  grant?: TGrant;
+}): Promise<Config<TGrant>> {
+  const grant = (input?.grant ??
+    (process.env.GRANT === 'plan' ? 'plan' : 'apply')) as TGrant;
+
+  return loaders[grant]() as Promise<Config<TGrant>>;
+}

package/dist/practices/lint/best-practice/.depcheckrc.yml

@@ -1,14 +1,13 @@
 ignores:
   - "@src/*"
   - "@src/.*"
-  - rhachet
-  - rhachet-brains-anthropic
-  - rhachet-brains-fireworksai
-  - rhachet-brains-xai
-  - rhachet-roles-bhrain
-  - rhachet-roles-bhuild
-  - rhachet-roles-ehmpathy
-  - rhachet-roles-rhachet
+  # all rhachet packages (roles/brains churn as prepare:rhachet installs vary)
+  - "rhachet*"
+  # runtime deps of the ghlitch operator use.vpc.tunnel skill (installed under
+  # .agent/repo=ghlitch via prepare:rhachet); no committed src imports them, so
+  # depcheck cannot attribute them in the ci lint job where the skill is absent
+  - declastruct-aws
+  - declastruct-unix-network
   - declapract
   - declapract-typescript-ehmpathy
   - "@commitlint/config-conventional"

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

@@ -0,0 +1,88 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the terraform-parameters forget, run through the REAL
+ *   declapract apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = the bad-practice fix must rewrite every `resource "aws_ssm_parameter"` into
+ *   a `removed{}` forget block (never a destroy), and drop the `data` seed-reads —
+ *   so terraform lets go of the params without loss of the live value. the
+ *   go-forward declastruct wish declares its own names separately; the OLD names
+ *   here are simply orphaned (forgotten from terraform, not adopted by declastruct).
+ * .note = the terraform file is snapshotted in full (before AND after) so a reviewer
+ *   can eyeball the exact end-state, per rule.require.declapract-integration-tests.
+ */
+describe('terraform-parameters forget', () => {
+  given(
+    '[case1] a repo with terraform-managed ssm params',
+    () => {
+      const tempDir = genTempDir({
+        slug: 'declapract-terraform-parameters',
+        clone: './src/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm',
+        symlink: [{ at: 'src', to: 'src' }],
+      });
+
+      const tfPath = 'provision/aws/product/parameter-store.tf';
+      const read = (relativePath: string) =>
+        fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+      const applyForget = () =>
+        executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file: tfPath,
+        });
+
+      when('[t0] the migration input (before any fix)', () => {
+        then('the terraform input matches snapshot', async () => {
+          expect(await read(tfPath)).toMatchSnapshot(
+            'parameter-store.tf — before',
+          );
+        });
+      });
+
+      when('[t1] the bad-practice forget fix is applied', () => {
+        useThen('forget the terraform params', async () => applyForget());
+
+        then(
+          'the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot',
+          async () => {
+            const tf = await read(tfPath);
+            expect(tf).not.toContain('resource "aws_ssm_parameter"');
+            expect(tf).not.toContain('data "aws_ssm_parameter"');
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_database_role_crud_password',
+            );
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_twilio_authToken',
+            );
+            expect(tf).toContain('destroy = false');
+            // full content, for the reviewer's eye
+            expect(tf).toMatchSnapshot('parameter-store.tf — after');
+          },
+        );
+      });
+
+      when('[t2] the forget fix is applied a second time (idempotency)', () => {
+        // capture the post-first-forget state, apply again, capture again — assert
+        // zero change. the forget regex must not re-match its own removed{} output
+        // (per rule.require.idempotent-fixes).
+        const passes = useThen(
+          'a second forget over its own output',
+          async () => {
+            const before = await read(tfPath); // post-first-forget
+            await applyForget(); // second apply
+            const after = await read(tfPath);
+            return { before, after };
+          },
+        );
+
+        then('the second forget is a no-op', () => {
+          expect(passes.after).toEqual(passes.before);
+        });
+      });
+    },
+  );
+});

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.declare.yml

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

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.use.yml

@@ -0,0 +1,18 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: 'testdb'
+  databaseUserName:
+    cicdUser: 'testdb_cicd'
+    serviceUser: 'testdb_service'
+  databaseTunnelHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  databaseClusterHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/package.json

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

package/dist/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/provision/aws/product/parameter-store.tf

@@ -0,0 +1,23 @@
+data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}

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

@@ -0,0 +1,44 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t0] the migration input (before any fix) then: the terraform input matches snapshot: parameter-store.tf — before 1`] = `
+"data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "\${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "\${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "\${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+"
+`;
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t1] the bad-practice forget fix is applied then: the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot: parameter-store.tf — after 1`] = `
+"removed {
+  from = aws_ssm_parameter.secret_database_role_crud_password
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+removed {
+  from = aws_ssm_parameter.secret_twilio_authToken
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+"
+`;

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

@@ -0,0 +1,55 @@
+import { type FileCheckFunction, type FileFixFunction } from 'declapract';
+
+/**
+ * .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
+ *   real values live ONLY in aws (seeded once), so a plain resource-block delete
+ *   would issue DeleteParameter = permanent loss. the fix instead rewrites each
+ *   `resource "aws_ssm_parameter"` into a `removed{}` forget block (`destroy = false`)
+ *   — terraform drops it from state and preserves the live value. requires terraform
+ *   >= 1.7 for the `removed{}` block.
+ *
+ * .pair = this bad-practice removes terraform's ownership; the best-practice
+ *   provision/aws/resources.parameters.ts declares the declastruct owner (value-less
+ *   write-only KEEP — it adopts the live values terraform seeded). declare the wish
+ *   BEFORE this forget lands so declastruct owns every param first.
+ */
+
+// bad practice detected while terraform still declares an ssm parameter resource.
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('resource "aws_ssm_parameter"')) return; // detected
+  throw new Error(
+    'no terraform-managed ssm parameter resources; not the terraform-parameters bad practice',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  // drop the `data "aws_ssm_parameter"` reads — they existed only to seed values
+  // that declastruct-aws now owns.
+  const withoutDataReads = contents.replace(
+    /data\s+"aws_ssm_parameter"\s+"\w+"\s*\{[\s\S]*?\n\}\n?/g,
+    '',
+  );
+
+  // rewrite each `resource "aws_ssm_parameter" "<label>" { ... }` into a forget
+  // block. `[\s\S]*?\n\}` stops at the first column-0 `}` (the block close); the
+  // 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) =>
+      [
+        `removed {`,
+        `  from = aws_ssm_parameter.${label}`,
+        `  lifecycle {`,
+        `    destroy = false # forget from state; keep the live param`,
+        `  }`,
+        `}`,
+      ].join('\n'),
+  );
+
+  return { contents: withForgetBlocks };
+};

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

@@ -6,8 +6,14 @@
     },
     "role": {
       "cicd": {
-        "username": "@declapract{variable.databaseUserName.cicdUser}",
-        "password": "$.at(aws::param)"
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
       },
       "crud": {
         "username": "@declapract{variable.databaseUserName.serviceUser}",

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

@@ -6,8 +6,14 @@
     },
     "role": {
       "cicd": {
-        "username": "@declapract{variable.databaseUserName.cicdUser}",
-        "password": "$.at(aws::param)"
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
       },
       "crud": {
         "username": "@declapract{variable.databaseUserName.serviceUser}",

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

@@ -6,8 +6,14 @@
     },
     "role": {
       "cicd": {
-        "username": "@declapract{variable.databaseUserName.cicdUser}",
-        "password": "__CHANG3_ME__"
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "__CHANG3_ME__"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "__CHANG3_ME__"
+        }
       },
       "crud": {
         "username": "@declapract{variable.databaseUserName.serviceUser}",

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

@@ -25,6 +25,6 @@
     "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",
     "start:testdb": "npm run provision:testdb",
-    "start:livedb:prep": "echo 'will ping the database until assured its not asleep' && ACCESS=prep .agent/repo=.this/skills/use.rds.capacity.sh"
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
   }
 }

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

@@ -0,0 +1,76 @@
+# provision / aws
+
+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.
+- `product/parameter-store.tf` — the terraform FORGET blocks (transitional).
+
+## why declastruct-aws, not terraform
+
+terraform managed these secrets with the `__IGNORED__` + `ignore_changes = [value]`
+workaround: the value was written once at seed, then terraform pretended it never
+drifted. that hides real drift and forces the secret through terraform state.
+
+`DeclaredAwsSsmParameterSecure` is **write-only by contract**:
+
+| phase | reads value? | kms | api |
+| ----- | ------------ | --- | --- |
+| 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 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.
+
+- a **CREATE at plan** means the declared name does not match a live param → STOP and
+  fix the name.
+- 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.
+
+## iam boundary (the two oidc roles)
+
+the prod oidc plan/apply split (see `.github/workflows/.declastruct.yml`, the aws-auth
+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.
+- **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
+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).
+
+## 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
+   `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
+   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.
+
+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

@@ -0,0 +1,82 @@
+import { DeclaredAwsSsmParameterSecure } from 'declastruct-aws';
+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.
+ */
+
+/**
+ * .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.
+ */
+const { access } = getEnvironment.static();
+
+/**
+ * .what = the legacy terraform stage label used inside the live param NAMES.
+ * .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
+ *        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.)
+ */
+const stage = access === 'prep' ? 'dev' : access;
+
+/**
+ * .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).
+ */
+const secret = (name: string): DeclaredAwsSsmParameterSecure =>
+  DeclaredAwsSsmParameterSecure.as({
+    name,
+    keyId: null, // default aws/ssm key (matches the terraform resources)
+    description: null,
+    tags: {
+      app: '@declapract{variable.organizationName}',
+      environment: access,
+      product: '@declapract{variable.projectName}',
+    },
+    // no `value` → write-only KEEP: adopt the live value, never read or rewrite it
+  });
+
+/**
+ * .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 —
+ *        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.
+ */
+export const getParameters = (): DeclaredAwsSsmParameterSecure[] => {
+  // dotted namespace that prefixes the env-scoped param names
+  // keep in sync with terraform local.parameter_store_namespace + config/${env}.json
+  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${stage}`;
+
+  return [
+    secret(`${namespace}.database.role.crud.password`),
+    secret(`${namespace}.database.role.cicd.for-plan.password`),
+    secret(`${namespace}.database.role.cicd.for-apply.password`),
+  ];
+};

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

@@ -0,0 +1,27 @@
+import type { DeclastructProvider } from 'declastruct';
+import { getDeclastructAwsProvider } from 'declastruct-aws';
+import type { DomainEntity } from 'domain-objects';
+import { genLogMethods } from 'sdk-logs';
+
+import { getParameters } 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 +
+ *        kms:Encrypt.
+ */
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  await getDeclastructAwsProvider(
+    {},
+    {
+      // MUST be an sdk-logs logger — the DAOs read log._.level via as-procedure
+      log: genLogMethods(),
+    },
+  ),
+];
+
+export const getResources = async (): Promise<DomainEntity<any>[]> =>
+  getParameters();