declapract-typescript-ehmpathy 0.49.7 → 0.49.9

package/dist/practices/git/.test/assets/repo-with-rhachet-only/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test
+# .why  = `rhachet-only` deliberately omits the `git` practice, to prove rhachet
+#         declares the ignore for the dir rhachet writes without help from a
+#         neighbor practice
+declarations: 'declarations/declapract.declare.yml'
+useCase: rhachet-only

package/dist/practices/git/.test/assets/repo-with-rhachet-only/package.json

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

package/dist/practices/git/.test/assets/repo-without-cache-ignores/declapract.use.yml

@@ -0,0 +1,9 @@
+# .note = declarations dir is symlinked by the test
+# .note = NO `variables:` block. the rule's top gotcha is that apply evaluates the
+#         whole practice, so every `@declapract{variable.*}` it references must be
+#         defined here. both `git` and `rhachet` reference ZERO -- verified by grep,
+#         and by this fixture, which applies clean without any. a variables block
+#         copied from another fixture "to be safe" would be a claim the practices
+#         make demands they do not.
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project

package/dist/practices/git/.test/assets/repo-without-cache-ignores/package.json

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

package/dist/practices/git/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,51 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`gitignore practices given: [case1] a repo whose .gitignore lacks both cache dirs when: [t0] before any apply then: the input file matches snapshot: .gitignore -- before 1`] = `
+"dist
+coverage
+.idea
+node_modules
+"
+`;
+
+exports[`gitignore practices given: [case1] a repo whose .gitignore lacks both cache dirs when: [t3] both practices are applied a second time then: the settled file matches snapshot: .gitignore -- settled 1`] = `
+"*.bak.*
+*.local.json
+*.log
+*.tsbuildinfo
+.agent/.cache/
+.artifact
+.cache/
+.env
+.idea
+.log/slowtest/
+.serverless
+.temp
+.terraform
+.terraform.lock
+.vscode
+.yalc
+coverage
+dist
+node_modules
+!.test*/**/node_modules
+!.test*/**/node_modules/**
+"
+`;
+
+exports[`gitignore practices given: [case2] a repo whose use case has rhachet but NOT git when: [t0] before any apply then: the input file matches snapshot: .gitignore -- rhachet only -- before 1`] = `
+"dist
+node_modules
+.idea
+"
+`;
+
+exports[`gitignore practices given: [case2] a repo whose use case has rhachet but NOT git when: [t1] the rhachet practice is applied then: the settled file matches snapshot: .gitignore -- rhachet only 1`] = `
+".agent/.cache/
+.idea
+dist
+node_modules
+!.test*/**/node_modules
+!.test*/**/node_modules/**
+"
+`;

package/dist/practices/git/best-practice/.declapract.readme.md

@@ -0,0 +1,23 @@
+the repo-root `.gitignore` and `.gitattributes`
+
+📖 several practices declare the `.gitignore`. the contract they share — one shared algorithm, the
+ordered tail, what a new declarer owes — is stated once at
+`.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitignore.md`. read that before you add
+a line here.
+
+## `.agent/.cache/` is declared here and by the rhachet practice
+
+deliberate, and neither is redundant. rhachet owns the dir in the causal sense — it creates it —
+which is a different claim from which practices declare the ignore for it.
+
+this line stays because `app-react-native-expo` (`src/useCases.yml`) takes `git` **without**
+`rhachet`, so for those repos it is the only explicit source of the ignore. `.cache/` happens to
+cover `.agent/.cache/` at any depth, but that coverage is implicit — narrow `.cache/` and it is
+gone. the same caution sits in `.gitignore.declapract.ts`, at the point of edit.
+
+## this repo consumes this practice
+
+`declapract.use.yml` sets `useCase: npm-package`, which extends `typescript-project`, which
+carries `git`. so `[case3]` in `src/practices/git/.declapract.integration.test.ts` checks this
+repo's own `.gitignore` against the declaration — add a line to `ignoresSortable` and it goes red
+until the practice is applied here too.

package/dist/practices/git/best-practice/.gitignore.declapract.ts

@@ -1,14 +1,40 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
-import { dedupe } from 'domain-objects';
 import expect from 'expect';
 
+import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGitignoreContents';
+
 /**
  * ignores that can be sorted alphabetically (no order dependencies)
+ *
+ * .note = `.agent/.cache/` is declared HERE and by
+ *         `src/practices/rhachet/best-practice/.gitignore.declapract.ts`. that is not drift, and
+ *         the line must not be "cleaned up" as a duplicate of rhachet's -- rhachet OWNS that dir
+ *         in the causal sense (it creates it), which is a different claim from which practices
+ *         declare the ignore for it.
+ *
+ *         two facts carry the load here:
+ *         - `app-react-native-expo` (`src/useCases.yml`) takes `git` WITHOUT `rhachet`, so for
+ *           every repo on that use case THIS line is the only explicit source of the ignore
+ *         - `.cache/` below happens to cover `.agent/.cache/` at any depth (a gitignore pattern
+ *           with no interior separator is unanchored -- measured with `git check-ignore -v`), so
+ *           a reader sees the overlap and reads it as redundant. that coverage is IMPLICIT --
+ *           narrow `.cache/` and it is gone
+ *
+ *         so removal here would un-ignore the agent cache for every git-without-rhachet repo, on
+ *         the day `.cache/` is next edited, with no line left to say why. if this ever moves, it
+ *         must land in a practice that still reaches every `git` consumer.
+ *
+ * .note = this list is NOT sorted here, and that is deliberate. `defineExpectedGitignoreContents`
+ *         sorts the union of these lines with the repo's own, so a `.sort()` at this site would
+ *         be a second sort that changes no output -- while it mutates a module-cached array in
+ *         place. `readonly` forbids that mutation outright rather than merely discourages it
+ *         (`rule.prefer.prevent-over-correct`), so the source may group lines by what they are
+ *         for, with their comments beside them, and the one sort that matters stays in one place.
  */
-const ignoresSortable = [
+const ignoresSortable: readonly string[] = [
   '*.log',
   '*.tsbuildinfo',
-  '.agent/.cache/', // agent cache (trash dir, temp files)
+  '.agent/.cache/', // agent cache -- kept even though rhachet declares it too; see .note above
   '.artifact', // deployment artifacts from `simple-artifact-builder` are produced here
   '.cache/', // cache directories from various tools
   '.env',
@@ -23,44 +49,44 @@ const ignoresSortable = [
   '*.bak.*', // backup files
   'coverage',
   'dist',
-].sort();
+];
 
 /**
- * ignores that must appear in a specific order (negations must follow their targets)
- *
- * note
- * - node_modules under .test* dirs are test fixtures (cloned repos via genTempDir)
- * - gitignore negation requires the negated pattern to come after the original
+ * .what = emits the `.gitignore` this practice declares, given the repo's extant one
+ * .why  = one algorithm serves both `check` and `fix`, so the gate and the repair can
+ *         never disagree about what the file should hold.
+ * .why  = the algorithm AND the ordered tail are imported, not declared here, because this
+ *         practice is not the only declarer of the repo-root `.gitignore`. declarers converge
+ *         only while every one of them emits an identical tail by an identical algorithm --
+ *         so they share one, and the drift that would break convergence cannot be written.
+ *         which practices those are is a `grep`; a count here would go stale the first time
+ *         one is added, as it already has once.
  */
-const ignoresOrdered = [
-  'node_modules',
-  '!.test*/**/node_modules',
-  '!.test*/**/node_modules/**',
-];
-
-const defineExpectedContents = (contents: string | null): string => {
-  // parse ignores from file
-  const ignoresFromFile = contents ? contents.split('\n') : [];
-
-  // separate into sortable vs ordered
-  const orderedPatterns = new Set(ignoresOrdered);
-  const ignoresFromFileSortable = ignoresFromFile.filter(
-    (line) => !!line && !orderedPatterns.has(line),
-  );
-
-  // combine and sort the sortable ignores
-  const sortedIgnores = dedupe([...ignoresFromFileSortable, ...ignoresSortable])
-    .sort()
-    .filter((line) => !!line);
-
-  // append ordered ignores at the end (order preserved)
-  return [...sortedIgnores, ...ignoresOrdered, ''].join('\n');
-};
+const defineExpectedContents = (contents: string | null): string =>
+  defineExpectedGitignoreContents({ contents, ignoresSortable });
 
+/**
+ * .what = throws when the repo's `.gitignore` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. so a line added to `ignoresSortable` above reaches a consumer
+ *         repo only because this throws on the file that lacks it.
+ * .note = best-practice semantics are inverted from what a reader expects -- a THROW
+ *         means the practice is violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
 export const check: FileCheckFunction = (contents) => {
   expect(contents).toEqual(defineExpectedContents(contents));
 };
 
+/**
+ * .what = unions this practice's declared ignores into the repo's `.gitignore`
+ * .why  = a findsert by construction -- a line already present stays present once,
+ *         and a repo's own custom ignores survive, because the file's extant lines
+ *         are unioned in before the sort.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output -- without both, `declapract fix` would rewrite this file forever.
+ *         clamped by `.gitignore.declapract.test.ts` -> `idempotency`.
+ */
 export const fix: FileFixFunction = (contents) => {
   return { contents: defineExpectedContents(contents) };
 };

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.