declapract-typescript-ehmpathy 0.49.14 → 0.50.0

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

@@ -0,0 +1,37 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "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}",
+        "password": "__CHANG3_ME__"
+      }
+    },
+    "tunnel": {
+      "bastion": {
+        "exid": "vpc-main-bastion"
+      },
+      "cluster": {
+        "name": "@declapract{variable.databaseClusterName}"
+      },
+      "local": {
+        "host": "localhost",
+        "port": 7821
+      },
+      "lambda": null
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+import { genRdsConfigDeclaration } from '../../../../utils/genRdsConfigDeclaration';
+
+/**
+ * .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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/package.json

@@ -0,0 +1,36 @@
+{
+  "dependencies": {
+    "iso-time": "@declapract{check.minVersion('1.11.7')}",
+    "pg": "@declapract{check.minVersion('8.3.0')}",
+    "yesql": "@declapract{check.minVersion('3.2.2')}"
+  },
+  "devDependencies": {
+    "sql-code-generator": "@declapract{check.minVersion('0.10.2')}",
+    "sql-dao-generator": "@declapract{check.minVersion('0.13.1')}",
+    "sql-schema-control": "@declapract{check.minVersion('1.8.1')}",
+    "sql-schema-generator": "@declapract{check.minVersion('0.26.1')}",
+    "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
+    "@types/pg": "@declapract{check.minVersion('8.6.1')}"
+  },
+  "pnpm": {
+    "patchedDependencies": {
+      "pg-pool": "patches/pg-pool.patch"
+    }
+  },
+  "scripts": {
+    "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": "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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/git/declarations/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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/aws/readme.md

@@ -0,0 +1,113 @@
+# 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 |
+
+## the param names
+
+each name is the one sdk-config (>= 0.3.0) derives for a bare `$.at(aws::param)` in
+`config/{env}.json`:
+
+```
+/{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`). 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)
+
+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
+  `/{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.
+
+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. 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; 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.
+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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts

@@ -0,0 +1,60 @@
+import { DeclaredAwsSsmParameterSecure } from 'declastruct-aws';
+import { getEnvironment } from 'sdk-environment';
+
+/**
+ * .what = the secret ssm parameters this service manages via declastruct.
+ * .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 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, config } = getEnvironment.static();
+
+/**
+ * .what = declare a secret ssm parameter for adoption (write-only, default key).
+ * .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
+    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 = 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: {
+  choice: string | null;
+}): DeclaredAwsSsmParameterSecure[] => {
+  // the derived namespace: org, project, then the config slug as the segment
+  const namespace = `/@declapract{variable.organizationName}/@declapract{variable.projectName}/${input.choice ?? config}`;
+
+  return [
+    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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/aws/resources.ts

@@ -0,0 +1,30 @@
+import type { DeclastructProvider } from 'declastruct';
+import { getDeclastructAwsProvider } from 'declastruct-aws';
+import type { DomainEntity } from 'domain-objects';
+import { genLogMethods } from 'sdk-logs';
+
+import { getAllParameters } from './resources.parameters';
+
+/**
+ * .what = the declastruct wish for this service's aws resources.
+ * .why = declastruct-aws owns the ssm parameters that terraform now forgets (see
+ *        provision/aws/product/parameter-store.tf). the plan role reconciles secrets
+ *        without any ssm:GetParameter or kms:Decrypt; apply writes via PutParameter +
+ *        kms:Encrypt.
+ * .name = `getProviders` + `getResources` are declastruct's REQUIRED wish entrypoint names, so
+ *         both are exempt from the get-set-gen One/All cardinality rule (a `getAll*` rename makes
+ *         declastruct find no entrypoint — the wish dies). external-framework contract names.
+ */
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  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>[]> =>
+  getAllParameters({ choice: null });

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/build-image.dockerfile

@@ -0,0 +1,7 @@
+FROM postgres:13.20
+
+COPY init/ /docker-entrypoint-initdb.d/
+
+ADD wait-for-postgres.sh /root/
+RUN chmod +x /root/wait-for-postgres.sh
+

package/dist/.test/assets/git/declarations/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,
+  }),
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/check-engine-skew.integration.test.ts

@@ -0,0 +1,115 @@
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * .what = run the skew check, against a testdb pin and a supplied livedb version, or the livedb
+ */
+const runSkewCheck = (input: {
+  testdbPin: string | null;
+  livedbVersion: string | null;
+}): { status: number | null; stdout: string; stderr: string } => {
+  const dockerfileArgs = (() => {
+    if (input.testdbPin === null) return [];
+    const dockerfile = join(
+      genTempDir({ slug: 'check-engine-skew' }),
+      'build-image.dockerfile',
+    );
+    writeFileSync(dockerfile, `${input.testdbPin}\n`);
+    return ['--dockerfile', dockerfile];
+  })();
+  const result = spawnSync(
+    'bash',
+    [
+      join(__dirname, 'check-engine-skew.sh'),
+      ...dockerfileArgs,
+      ...(input.livedbVersion === null
+        ? []
+        : ['--livedb-version', input.livedbVersion]),
+    ],
+    { encoding: 'utf-8', env: process.env },
+  );
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+};
+
+describe('check-engine-skew', () => {
+  given('[case1] the testdb leads the livedb', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it halts', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:17.11',
+          livedbVersion: '13.23',
+        }),
+      );
+
+      then('it exits 2 and names both fixes', () => {
+        expect(result.status).toEqual(2);
+        expect(result.stderr).toContain('✋ ConstraintError');
+        expect(result.stderr).toContain('pin the testdb to postgres 13');
+      });
+    });
+  });
+
+  given('[case2] the testdb trails the livedb', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it passes with a warn', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:13.20',
+          livedbVersion: '17.11',
+        }),
+      );
+
+      then('it exits 0 and emits a github warn', () => {
+        expect(result.status).toEqual(0);
+        expect(result.stdout).toContain('::warning title=engine skew::');
+      });
+    });
+  });
+
+  given('[case3] the majors match', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it passes', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:17.11',
+          livedbVersion: '17.7',
+        }),
+      );
+
+      then('it exits 0 with no warn', () => {
+        expect(result.status).toEqual(0);
+        expect(result.stdout).toContain('majors match');
+        expect(result.stdout).not.toContain('::warning');
+      });
+    });
+  });
+
+  // the gate: the one case that reads the livedb through aws. it needs rds:DescribeDBClusters on
+  // the livedb's account, and with no grant it fails loud on the MalfunctionError, which names it
+  given('[case4] the livedb, read through aws', () => {
+    when('[t0] the check runs against this repo testdb pin', () => {
+      const result = useThen('the read completes', async () =>
+        runSkewCheck({ testdbPin: null, livedbVersion: null }),
+      );
+
+      then('the read succeeds, never a malfunction', () => {
+        expect(result.stderr).not.toContain('💥 MalfunctionError');
+        expect(result.status).not.toEqual(1);
+      });
+
+      then('the testdb does not lead the livedb', () => {
+        expect(result.stderr).not.toContain('✋ ConstraintError');
+        expect(result.status).toEqual(0);
+      });
+
+      then('it reports the version the livedb returned', () => {
+        expect(result.stdout).toMatch(/livedb: postgres \d+(\.\d+)*\n/);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/check-engine-skew.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = compare the testdb's postgres major against the livedb's.
+#         halt when the testdb leads; warn when it trails
+#
+# .why  = the suite runs against the testdb alone. a testdb ahead of the
+#         livedb can pass on a feature the livedb rejects — a false green
+#         that ships. a testdb behind the livedb is the safe skew: the newer
+#         major accepts near all of the older one's sql
+#
+# .note = the livedb is the cluster config/test.json names, read with the
+#         aws access the integration suite already holds. the integration
+#         suite runs this check against the livedb, so a testdb that leads
+#         it fails the suite
+#
+# usage:
+#   bash provision/docker/testdb/check-engine-skew.sh
+#   bash provision/docker/testdb/check-engine-skew.sh --livedb-version 13.23
+#   bash provision/docker/testdb/check-engine-skew.sh --dockerfile path/to/build-image.dockerfile
+#   bash provision/docker/testdb/check-engine-skew.sh --declared-version 17.11
+#
+# options:
+#   --livedb-version    the livedb's engine version; skips the aws read when given
+#   --declared-version  the engine version the infrastructure declares; when
+#                       given, a halt names how the skew arrived and prints the
+#                       one fix for it. absent, the halt prints both fixes
+#   --dockerfile        the testdb image (default: beside this file)
+#   --config            the config that names the livedb (default: config/test.json)
+#   --help, -h          print this block and exit
+#
+#   the livedb read names the aws cluster from the config's tunnel
+#
+# guarantee:
+#   - exit 0 = majors match, or the testdb trails the livedb (a warn)
+#   - exit 1 = malfunction (the config names no cluster, the aws read failed or returned no version, the dockerfile is unreadable or has no postgres pin)
+#   - exit 2 = constraint (the testdb leads the livedb, or an arg is absent or malformed)
+######################################################################
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCKERFILE="$SELF_DIR/build-image.dockerfile"
+CONFIG="$SELF_DIR/../../../config/test.json"
+LIVEDB_VERSION=""
+DECLARED_VERSION=""
+
+# fail on a flag given with no value, or with the next flag where its value was owed
+require_value() {
+  local flag="" value=""
+  local pair
+  for pair in "$@"; do
+    case "$pair" in
+      flag=*) flag="${pair#flag=}" ;;
+      value=*) value="${pair#value=}" ;;
+    esac
+  done
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "✋ ConstraintError: $flag needs a value" >&2
+    echo "   └─ fix: see $0 --help" >&2
+    exit 2
+  fi
+}
+
+# parse named args
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h) sed -n '3,/^######/{/^######/!p;}' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --livedb-version) require_value flag="$1" value="${2:-}"; LIVEDB_VERSION="$2"; shift 2 ;;
+    --declared-version) require_value flag="$1" value="${2:-}"; DECLARED_VERSION="$2"; shift 2 ;;
+    --dockerfile) require_value flag="$1" value="${2:-}"; DOCKERFILE="$2"; shift 2 ;;
+    --config) require_value flag="$1" value="${2:-}"; CONFIG="$2"; shift 2 ;;
+    *)
+      echo "✋ ConstraintError: unknown arg '$1'" >&2
+      echo "   └─ fix: see $0 --help" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# fail on a dockerfile the grep cannot read, so a read failure never reads as an absent pin
+if [[ ! -f "$DOCKERFILE" || ! -r "$DOCKERFILE" ]]; then
+  echo "💥 MalfunctionError: cannot read the testdb dockerfile at $DOCKERFILE" >&2
+  echo "   └─ fix: pass --dockerfile with a readable path, or restore build-image.dockerfile beside this file" >&2
+  exit 1
+fi
+
+# read the testdb major from its image pin; the grep exits 1 on no match, which the guard below reports
+TESTDB_MAJOR="$(grep -oE '^FROM postgres:[0-9]+' "$DOCKERFILE" | grep -oE '[0-9]+$' || true)"
+if [[ -z "$TESTDB_MAJOR" ]]; then
+  echo "💥 MalfunctionError: no 'FROM postgres:<major>' pin found in $DOCKERFILE" >&2
+  echo "   └─ fix: pin a major, like 'FROM postgres:17.11', or pass --dockerfile with the testdb image" >&2
+  exit 1
+fi
+
+# reject a supplied version that is not a postgres version
+VERSION_SHAPE='^[0-9]+(\.[0-9]+)*$'
+for supplied in "$LIVEDB_VERSION" "$DECLARED_VERSION"; do
+  if [[ -n "$supplied" && ! "$supplied" =~ $VERSION_SHAPE ]]; then
+    echo "✋ ConstraintError: '$supplied' is not a postgres version" >&2
+    echo "   └─ fix: pass a version like 17.11 or 17" >&2
+    exit 2
+  fi
+done
+
+# read the livedb version, unless supplied
+if [[ -z "$LIVEDB_VERSION" ]]; then
+  CLUSTER="$(jq -r '.database.tunnel.cluster.name // empty' "$CONFIG" || true)"
+  if [[ -z "$CLUSTER" ]]; then
+    echo "💥 MalfunctionError: no cluster name at .database.tunnel.cluster.name in $CONFIG" >&2
+    echo "   └─ fix: the file must exist, parse as json, and name the aws cluster the tunnel reaches" >&2
+    exit 1
+  fi
+  if ! LIVEDB_VERSION="$(aws rds describe-db-clusters \
+    --db-cluster-identifier "$CLUSTER" \
+    --query 'DBClusters[0].EngineVersion' \
+    --output text)"; then
+    echo "💥 MalfunctionError: could not read the engine version of cluster '$CLUSTER'" >&2
+    echo "   └─ fix: the caller needs aws auth with rds:DescribeDBClusters on the livedb's account" >&2
+    exit 1
+  fi
+  if [[ ! "$LIVEDB_VERSION" =~ $VERSION_SHAPE ]]; then
+    echo "💥 MalfunctionError: cluster '$CLUSTER' reported engine version '$LIVEDB_VERSION', which is not a postgres version" >&2
+    exit 1
+  fi
+fi
+
+# the livedb major: its version up to the first dot (17.11 → 17)
+LIVEDB_MAJOR="${LIVEDB_VERSION%%.*}"
+
+# report the two engines
+echo "🔭 engine skew"
+echo "   ├─ testdb: postgres $TESTDB_MAJOR ($DOCKERFILE)"
+echo "   └─ livedb: postgres $LIVEDB_VERSION"
+
+# halt when the testdb leads the livedb
+if (( TESTDB_MAJOR > LIVEDB_MAJOR )); then
+  echo "✋ ConstraintError: the testdb (postgres $TESTDB_MAJOR) leads the livedb (postgres $LIVEDB_MAJOR)" >&2
+  echo "   ├─ why: a green suite here can rest on a postgres $TESTDB_MAJOR feature the livedb rejects" >&2
+
+  # name the arrival when the declared target is known
+  DECLARED_MAJOR="${DECLARED_VERSION%%.*}"
+  if [[ -n "$DECLARED_MAJOR" ]] && (( DECLARED_MAJOR > LIVEDB_MAJOR )); then
+    echo "   ├─ how: the livedb sits below its declared target $DECLARED_MAJOR — a flip was reverted, or has not yet applied" >&2
+    echo "   └─ fix: pin the testdb to postgres $LIVEDB_MAJOR until the flip holds. do not re-flip a reverted livedb from here" >&2
+    exit 2
+  fi
+  if [[ -n "$DECLARED_MAJOR" ]]; then
+    echo "   ├─ how: the livedb matches its declared target $DECLARED_MAJOR — the testdb pin moved ahead of the flip" >&2
+    echo "   └─ fix: declare postgres $TESTDB_MAJOR in the infrastructure, then merge after the livedb reads it" >&2
+    exit 2
+  fi
+
+  echo "   └─ fix: one of two, by how the skew arrived" >&2
+  echo "      ├─ the pin moved before the flip: merge after the livedb reads postgres $TESTDB_MAJOR" >&2
+  echo "      └─ the livedb fell back:          pin the testdb to postgres $LIVEDB_MAJOR until the flip holds" >&2
+  exit 2
+fi
+
+# warn when the testdb trails the livedb
+if (( TESTDB_MAJOR < LIVEDB_MAJOR )); then
+  echo ""
+  echo "::warning title=engine skew::testdb postgres $TESTDB_MAJOR trails the livedb's postgres $LIVEDB_MAJOR. safe, but bump the pin on the next declapract upgrade"
+  exit 0
+fi
+
+echo "✨ majors match"