declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/practices/git/.gitattributes.declapract.integration.test.ts

@@ -4,9 +4,24 @@ import path from 'node:path';
 import { executeApply } from 'declapract';
 import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
 
-// executeApply evaluates the whole git practice before the `file` filter narrows it
+import { check as checkGit } from './best-practice/.gitattributes.declapract';
+
+// executeApply evaluates the whole practice before the `file` filter narrows it
 jest.setTimeout(5 * 60 * 1000);
 
+const context = {} as Parameters<typeof checkGit>[1]; // .note = the check reads no context
+
+// .note = a literal, independent of the declaration: the check is `x === fix(x)`, so it passes on
+//         any fixed point and cannot by itself prove the bytes are the ones the practice promises
+const MANAGED_SECTIONS = `# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
+pnpm-lock.yaml -diff
+package-lock.json -diff
+
+# [git] auto-resolve lock file conflicts by taking theirs; run install after merge
+pnpm-lock.yaml merge=theirs
+package-lock.json merge=theirs
+`;
+
 const MANAGED_ENTRIES = [
   'pnpm-lock.yaml -diff',
   'package-lock.json -diff',
@@ -15,15 +30,13 @@ const MANAGED_ENTRIES = [
 ];
 
 /**
- * .what = proves the .gitattributes fix through the real declapract pipeline
- * .why  = the unit suite proves the fix in isolation; only executeApply proves the declared path
- *         reaches the repo-root file, the CONTAINS check gates the fix, and the settled file
- *         satisfies that check — so a rerun is a no-op and the plan stops to flag it
+ * .what = proves the git `.gitattributes` declaration through the real declapract pipeline
+ * .why  = the unit suite proves the fix in isolation; only executeApply proves the declared
+ *         path reaches the repo-root file, the check gates the fix, and the settled file
+ *         satisfies the check — so a rerun is a no-op and the plan stops to flag it
  *         (rule.require.declapract-integration-tests, rule.require.idempotent-fixes)
- * .teeth = emit any section's entries out of declared order, and [t1] `contains the template`
- *          reddens while [t2] stays a byte-identical fixed point — the reflag loop a fixed-point
- *          test alone cannot see. the prior fix (sections re-assembled in place, a stray entry
- *          left outside its section) was in exactly that state
+ * .note = all five declarers together, and this repo's own file, are proven in
+ *         `src/gitattributesDeclarers.declapract.integration.test.ts`
  */
 describe('git .gitattributes', () => {
   given('[case1] a repo whose .gitattributes holds a legacy header, a legacy entry, and an out-of-section entry', () => {
@@ -31,7 +44,7 @@ describe('git .gitattributes', () => {
       slug: 'git-gitattributes-legacy',
       clone: './src/practices/git/.test/assets/repo-with-legacy-gitattributes',
       symlink: [
-        { at: 'declarations', to: './.test/assets/git/declarations' },
+        { at: 'declarations', to: './src/.test/assets/git/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -53,15 +66,15 @@ describe('git .gitattributes', () => {
     when('[t1] apply runs', () => {
       const scene = useThen('apply settles', async () => {
         await apply();
-        const template = await fs.readFile(
-          path.join(__dirname, 'best-practice/.gitattributes'),
-          'utf-8',
-        );
-        return { after: await read(), template };
+        return { after: await read() };
+      });
+
+      then('the git check passes on the file', () => {
+        expect(() => checkGit(scene.after, context)).not.toThrow();
       });
 
-      then('the file contains the template verbatim — the CONTAINS check passes', () => {
-        expect(scene.after).toContain(scene.template.trim());
+      then('the file holds the managed sections verbatim, then the repo-own line', () => {
+        expect(scene.after).toEqual(`${MANAGED_SECTIONS}\n*.png binary\n`);
       });
 
       then('the legacy header and the legacy entry are gone', () => {
@@ -77,8 +90,10 @@ describe('git .gitattributes', () => {
         );
       });
 
-      then('the repo-own line survives', () => {
-        expect(scene.after).toContain('*.png binary');
+      then('the repo-own line survives, after the managed sections', () => {
+        expect(scene.after.trim().split('\n').slice(-1)[0]).toEqual(
+          '*.png binary',
+        );
       });
 
       then('no declapract template syntax leaked', () => {

package/dist/practices/git/.test/assets/repo-with-legacy-gitattributes/declapract.use.yml

@@ -1,7 +1,7 @@
-# .note = declarations dir is symlinked by the test to .test/assets/git/declarations
+# .note = declarations dir is symlinked by the test to src/.test/assets/git/declarations
 # .why  = a repo whose .gitattributes predates the current template: a legacy header, a legacy
-#         entry, and a managed entry outside any section — so the CONTAINS check fails and the
-#         git practice's fix runs
+#         entry, and a managed entry outside any section — so the check fails and the git
+#         practice's fix runs
 # .note = NO `variables:` block — `git` and `rhachet` reference zero `@declapract{variable.*}`
 declarations: 'declarations/declapract.declare.yml'
 useCase: typescript-project

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

@@ -11,14 +11,14 @@ pnpm-lock.yaml merge=theirs
 `;
 
 exports[`git .gitattributes given: [case1] a repo whose .gitattributes holds a legacy header, a legacy entry, and an out-of-section entry when: [t1] apply runs then: the output matches snapshot: .gitattributes — after 1`] = `
-"*.png binary
-
-# exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
+"# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233
 pnpm-lock.yaml -diff
 package-lock.json -diff
 
-# auto-resolve lock file conflicts by taking theirs; run install after merge
+# [git] auto-resolve lock file conflicts by taking theirs; run install after merge
 pnpm-lock.yaml merge=theirs
 package-lock.json merge=theirs
+
+*.png binary
 "
 `;

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

@@ -5,6 +5,43 @@ 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.
 
+📖 several practices declare the `.gitattributes` too, and there order carries load. their shared
+contract — the canonical layout, the declarer tag, what a new declarer owes — is stated once at
+`.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitattributes.md`.
+
+## what folds in a pr, and how to un-fold a path
+
+a repo that adopts these practices gets `linguist-generated` lines, so github renders robocode
+collapsed in a pr. each stays one click away.
+
+| folds | declared by |
+|-------|-------------|
+| `*.test.ts`, `*.test.tsx` | `tests-any` |
+| `src/access/daos/**/.generated/**`, `provision/schema/**/.generated/**` | `persist-with-rds` |
+| `src/access/daos/**/.generated/**` | `persist-with-dynamodb` |
+| `.route/**`, `.behavior/**`, except `*.yield.*` and `.radio/**` | `rhachet` |
+
+snapshots (`*.snap`) stay open: no line names them. the daos and the schemas stay open too: they
+are the internal contracts. only the `.generated/` dirs within them fold.
+
+to un-fold a path, add a line at the bottom of `.gitattributes`, below every `# [<declarer>]`
+section and apart from them by a blank line:
+
+```
+src/access/daos/.generated/** -linguist-generated
+```
+
+the repo's own lines always sit last, and git takes the last line that matches, so this line wins.
+
+- a dir-level line un-folds every file under it, test files included, since it outranks the
+  `tests-any` line too
+- one file un-folds with a line of its own:
+  `src/access/daos/.generated/queryFunctions.ts -linguist-generated`
+- leave your own lines untagged. a `# [<word>]` header marks a managed block: it floats above the
+  repo-own lines, and one that names a declarer is rewritten by that declarer's fix
+
+a folded file may also drop out of github code search, which skips generated files.
+
 ## `.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 —

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

@@ -1,98 +1,77 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
 
-/**
- * check that they're contained in the file
- */
-export const check: FileCheckType = FileCheckType.CONTAINS;
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
 
 /**
- * sections of gitattributes entries to ensure exist
+ * .what = the `.gitattributes` sections this practice owns: lock-file diff and merge rules
+ * .why  = lock files churn on every install. `-diff` folds them out of `git diff`, and
+ *         `merge=theirs` takes the incoming lock on a conflict, so an install after the merge
+ *         rebuilds it
+ * .note = `retired` hold every form these sections once took — the untagged headers, the
+ *         `pnpm-lock.json` typo — so a fix lifts them out of an extant file
  */
-const SECTIONS: {
-  header: { latest: string; priors: string[] };
-  entries: { latest: string[]; priors: string[] };
-}[] = [
+const sections: readonly GitattributesSection[] = [
   {
     header: {
       latest:
+        '# [git] exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233',
+      retired: [
         '# exclude package locks from git diff; https://stackoverflow.com/a/72834452/3068233',
-      priors: [
         '# exclude package-lock from git diff; https://stackoverflow.com/a/72834452/3068233',
       ],
     },
     entries: {
       latest: ['pnpm-lock.yaml -diff', 'package-lock.json -diff'],
-      priors: ['pnpm-lock.json -diff'],
+      retired: ['pnpm-lock.json -diff'],
     },
   },
   {
     header: {
       latest:
+        '# [git] auto-resolve lock file conflicts by taking theirs; run install after merge',
+      retired: [
         '# auto-resolve lock file conflicts by taking theirs; run install after merge',
-      priors: [],
+      ],
     },
     entries: {
       latest: ['pnpm-lock.yaml merge=theirs', 'package-lock.json merge=theirs'],
-      priors: ['pnpm-lock.json merge=theirs'],
+      retired: ['pnpm-lock.json merge=theirs'],
     },
   },
 ];
 
 /**
- * .what = every line this practice manages: each section's header and entries, latest and prior
- * .why  = the fix lifts each of these out of wherever it sits, so none can linger out of place,
- *         out of order, or twice
+ * .what = emits the `.gitattributes` this practice declares, given the repo's extant one
+ * .why  = tests-any, rhachet, and the persist practices declare this same file. they converge
+ *         only through one shared algorithm, so this file declares its sections and imports
+ *         the rest
  */
-const ALL_MANAGED_LINES = SECTIONS.flatMap((s) => [
-  s.header.latest,
-  ...s.header.priors,
-  ...s.entries.latest,
-  ...s.entries.priors,
-]);
+const defineExpectedContents = (input: { contents: string | null }): string =>
+  defineExpectedGitattributesContents({
+    contents: input.contents,
+    declarer: 'git',
+    sections,
+  });
 
 /**
- * .what = the canonical block: each section's latest header + latest entries, in declared order
- * .why  = the check is CONTAINS — the file must hold the whole template as one contiguous run of
- *         text — so the fix must emit this block verbatim. a section re-assembled in place (an
- *         entry inserted after its header, or a stray entry left outside its section) is a fixed
- *         point that never CONTAINS the template, so the plan would flag the file on every run
+ * .what = throws when the repo's `.gitattributes` differs from what the shared layout emits
+ * .why  = `check` gates `fix`: a throw means violated (best-practice semantics). an exact
+ *         equality, not CONTAINS, since order carries load and `check(x) ⟺ x === fix(x)`
+ *         keeps `declapract apply` from a loop
  */
-const CANONICAL_BLOCK = SECTIONS.map((s) =>
-  [s.header.latest, ...s.entries.latest].join('\n'),
-).join('\n\n');
-
-/**
- * .what = the repo-own lines of a .gitattributes: every managed line dropped, runs of blank
- *         lines collapsed to one, and the edges trimmed
- * .why  = the repo keeps every line this practice does not manage, in its own order
- */
-const asRepoOwnBlock = (input: { contents: string }): string => {
-  // drop every managed line, wherever it sits
-  const linesRepoOwn = input.contents
-    .split('\n')
-    .filter((line) => !ALL_MANAGED_LINES.includes(line.trim()));
-
-  // collapse runs of blank lines into one (drop a blank that follows a blank)
-  const linesCollapsed = linesRepoOwn.filter(
-    (line, index) =>
-      !(
-        line.trim() === '' &&
-        index > 0 &&
-        linesRepoOwn[index - 1]!.trim() === ''
-      ),
-  );
-
-  return linesCollapsed.join('\n').trim();
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents({ contents }));
 };
 
 /**
- * .what = the repo-own lines first, then the canonical block, with exactly one final newline
- * .why  = legacy headers and entries drop, duplicates collapse to one, and the output CONTAINS the
- *         template — so the check passes on the fixed output and a second fix changes zero
+ * .what = sets this practice's sections into the repo's `.gitattributes`
+ * .why  = legacy headers and entries drop, duplicates collapse to one, repo-own lines move
+ *         last; a fixed point, so a second fix changes zero
  */
-export const fix: FileFixFunction = (contents) => {
-  const repoOwnBlock = asRepoOwnBlock({ contents: contents ?? '' });
-  return {
-    contents: `${[repoOwnBlock, CANONICAL_BLOCK].filter((block) => block).join('\n\n')}\n`,
-  };
-};
+export const fix: FileFixFunction = (contents) => ({
+  contents: defineExpectedContents({ contents }),
+});

package/dist/practices/persist-with-dynamodb/best-practice/.gitattributes.declapract.ts

@@ -0,0 +1,56 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import {
+  defineExpectedGitattributesContents,
+  type GitattributesSection,
+} from '../../../utils/defineExpectedGitattributesContents';
+
+/**
+ * .what = the `.gitattributes` section this practice owns: the dao `.generated/` dir folds in pr diffs
+ * .why  = the daos are the internal contracts, so a reviewer reads them open. a `.generated/` dir
+ *         under `src/access/daos` holds derived code that every regen rewrites. github folds a
+ *         file marked `linguist-generated`, one click away
+ * .note = the generator's terraform dir, `provision/aws/product`, also holds hand-written infra,
+ *         and an infra change owes open eyes, so it stays open
+ */
+const sections: readonly GitattributesSection[] = [
+  {
+    header: {
+      latest:
+        '# [persist-with-dynamodb] collapse dao-generator output in pr diffs',
+      retired: [],
+    },
+    entries: {
+      latest: ['src/access/daos/**/.generated/** linguist-generated'],
+      retired: ['src/access/daos/** linguist-generated'],
+    },
+  },
+];
+
+/**
+ * .what = emits the `.gitattributes` this practice declares, given the repo's extant one
+ * .why  = several practices declare this file; they converge only through the shared util
+ */
+const defineExpectedContents = (input: { contents: string | null }): string =>
+  defineExpectedGitattributesContents({
+    contents: input.contents,
+    declarer: 'persist-with-dynamodb',
+    sections,
+  });
+
+/**
+ * .what = throws when the repo's `.gitattributes` differs from what the shared layout emits
+ * .why  = `check` gates `fix` (a throw means violated); exact equality, so `check(x) ⟺ x === fix(x)`
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents({ contents }));
+};
+
+/**
+ * .what = sets this practice's section into the repo's `.gitattributes`
+ * .why  = a fixed point: a second fix changes zero, and `check` passes on the output
+ */
+export const fix: FileFixFunction = (contents) => ({
+  contents: defineExpectedContents({ contents }),
+});

package/dist/practices/persist-with-rds/.test/assets/repo-with-hand-patch/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = the test writes declarations/ into the temp clone (genDeclarationsOfPackageJsonOnly)
+# .why  = an rds repo that already holds its own exact-version pg-pool hand patch (vision case=2)
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/practices/persist-with-rds/.test/assets/repo-with-hand-patch/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "repo-with-hand-patch",
+  "version": "1.0.0",
+  "dependencies": {
+    "pg": "8.3.0",
+    "pg-pool": "3.14.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "pg-pool@3.14.0": "patches/pg-pool@3.14.0.patch",
+      "left-pad@1.3.0": "patches/left-pad@1.3.0.patch"
+    }
+  }
+}

package/dist/practices/persist-with-rds/.test/assets/repo-with-hand-patch/patches/left-pad@1.3.0.patch

@@ -0,0 +1,6 @@
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -1,1 +1,1 @@
+-/* This program is free software. It comes without any warranty, to
++/* This program is free software. It comes without any warranty, to (hand patch)

package/dist/practices/persist-with-rds/.test/assets/repo-with-hand-patch/patches/pg-pool@3.14.0.patch

@@ -0,0 +1,12 @@
+diff --git a/index.js b/index.js
+--- a/index.js
++++ b/index.js
+@@ -92,7 +92,7 @@ class Pool extends EventEmitter {
+     this.options.allowExitOnIdle = this.options.allowExitOnIdle || false
+     this.options.maxLifetimeSeconds = this.options.maxLifetimeSeconds || 0
+     this.log = this.options.log || function () {}
+-    this.Client = this.options.Client || Client || require('pg').Client
++    this.Client = this.options.Client || Client // hand patch
+     this.Promise = this.options.Promise || global.Promise
+
+     if (typeof this.options.idleTimeoutMillis === 'undefined') {

package/dist/practices/persist-with-rds/__snapshots__/pg-pool-patch.declapract.integration.test.ts.snap

@@ -0,0 +1,147 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.2.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.2.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.2.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.2.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.3.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.3.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.4.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.4.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.4.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.4.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.5.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.5.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.5.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.5.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.6.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.6.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.7.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.7.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.7.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.7.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.8.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.8.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.2, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.2 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.5, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.5 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.9.6, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.9.6 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.10.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.10.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.10.1, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.10.1 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.11.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.11.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.12.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.12.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.13.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.13.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case2] pg-pool 3.14.0, installed with the shipped patch when: [t0] pnpm install runs then: the patch lines an adopter reads match snapshot: pnpm install — patch lines, pg-pool 3.14.0 1`] = `[]`;
+
+exports[`persist-with-rds pg-pool patch given: [case4] an rds repo that already holds its own "pg-pool@3.14.0" hand patch when: [t0] the persist-with-rds practice is applied then: the before + after contents match snapshot: package.json — after 1`] = `
+"{
+  "name": "repo-with-hand-patch",
+  "version": "1.0.0",
+  "dependencies": {
+    "pg": "8.3.0",
+    "pg-pool": "3.14.0",
+    "iso-time": "@declapract{check.minVersion('<floor>')}",
+    "yesql": "@declapract{check.minVersion('<floor>')}"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "pg-pool@3.14.0": "patches/pg-pool@3.14.0.patch",
+      "left-pad@1.3.0": "patches/left-pad@1.3.0.patch",
+      "pg-pool": "patches/pg-pool.patch"
+    }
+  },
+  "devDependencies": {
+    "sql-code-generator": "@declapract{check.minVersion('<floor>')}",
+    "sql-dao-generator": "@declapract{check.minVersion('<floor>')}",
+    "sql-schema-control": "@declapract{check.minVersion('<floor>')}",
+    "sql-schema-generator": "@declapract{check.minVersion('<floor>')}",
+    "@types/yesql": "@declapract{check.minVersion('<floor>')}",
+    "@types/pg": "@declapract{check.minVersion('<floor>')}"
+  },
+  "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"
+  }
+}
+"
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case4] an rds repo that already holds its own "pg-pool@3.14.0" hand patch when: [t0] the persist-with-rds practice is applied then: the before + after contents match snapshot: package.json — before 1`] = `
+"{
+  "name": "repo-with-hand-patch",
+  "version": "1.0.0",
+  "dependencies": {
+    "pg": "8.3.0",
+    "pg-pool": "3.14.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "pg-pool@3.14.0": "patches/pg-pool@3.14.0.patch",
+      "left-pad@1.3.0": "patches/left-pad@1.3.0.patch"
+    }
+  }
+}
+"
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case5] a pg-pool release where the patched line moved, so the hunk fails when: [t0] pnpm install runs then: the warn an adopter reads matches snapshot: pnpm install — patch failure warn 1`] = `
+[
+  " WARN  Could not apply patch <tempdir>/patches/pg-pool.patch to <tempdir>/node_modules/.pnpm/pg-pool@3.14.0_patch_hash=<hash>_pg@8.3.0/node_modules/pg-pool",
+]
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case6] a bare rds adopter: pg, pg-pool, the shipped cycle check, and one src file that imports pg when: [t0] its cycle check runs, with the shipped patch then: the verdict an adopter reads matches snapshot: test:lint:cycles — with the shipped patch 1`] = `
+[
+  "> pg-pool-patch-demo@ test:lint:cycles <tempdir>",
+  "> EXCL=$(node -p "(require('yaml').parse(require('fs').readFileSync('.dpdmrc.yaml','utf8'))?.exclude ?? []).join('|')") && dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude "$EXCL" 'src/**/!(*.test).ts'",
+  "• Circular Dependencies",
+  "  ✅ Congratulations, no circular dependency was found in your project.",
+  "- Start analyzing dependencies...",
+  "✔ [37/37] Analyze done!",
+]
+`;
+
+exports[`persist-with-rds pg-pool patch given: [case6] a bare rds adopter: pg, pg-pool, the shipped cycle check, and one src file that imports pg when: [t1] its cycle check runs, with no patch then: the verdict an adopter reads matches snapshot: test:lint:cycles — with no patch 1`] = `
+[
+  "> pg-pool-patch-demo@ test:lint:cycles <tempdir>",
+  "> EXCL=$(node -p "(require('yaml').parse(require('fs').readFileSync('.dpdmrc.yaml','utf8'))?.exclude ?? []).join('|')") && dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude "$EXCL" 'src/**/!(*.test).ts'",
+  "• Circular Dependencies",
+  "  1) node_modules/.pnpm/pg@<floor>/node_modules/pg/lib/index.js -> node_modules/.pnpm/pg-pool@3.14.0_pg@<floor>/node_modules/pg-pool/index.js",
+  " ELIFECYCLE  Command failed with exit code 1.",
+  "- Start analyzing dependencies...",
+  "✔ [37/37] Analyze done!",
+]
+`;

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

@@ -21,6 +21,28 @@ we use:
 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.
 
+## the pg-pool patch
+
+pg-pool's pool falls back to `require('pg').Client` when no `Client` is passed. dpdm reads that
+require statically, so every repo with pg + pg-pool fails `test:lint:cycles` on `pg <-> pg-pool`
+(the check reads node_modules too, by policy). this practice ships
+`patches/pg-pool.patch`, which drops the fallback, under the bare-name key
+`pnpm.patchedDependencies["pg-pool"]`:
+
+- the bare name never goes stale, so the stale-patch check never retires it; the hunk fits every
+  stable pg-pool release in `^3.2.1`, which `pg@8.3.0` asks for
+- a repo's own exact-version key (`pg-pool@<version>`) outranks it at install, and both survive the apply.
+  a hand patch of the same line may be deleted, key and file
+- after an apply, run `pnpm install` and commit the lockfile: it records the patch hash, so a ci
+  `--frozen-lockfile` install fails until it does
+- pg passes its own `Client` into every pool it builds, so code that goes through `pg` sees no change.
+  code that calls `new Pool()` from pg-pool directly must pass `{ Client: require('pg').Client }`
+- if pnpm warns that the 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; its exact key outranks the bare one
+- to recut the hunk, keep one context line on each side of the changed line. wider context misfits
+  older releases in `^3.2.1` (3.2.1–3.4.1), and pnpm then installs pg-pool unpatched
+
 ## ssm parameters
 
 the provision wish (`provision/aws/resources.parameters.ts`) declares the db credentials at the
@@ -83,3 +105,10 @@ a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) doe
 `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.
+
+## the dao-generator output folds in a pr
+
+this practice declares a `# [persist-with-rds]` section of the repo-root `.gitattributes`: it marks
+`src/access/daos/**/.generated/**` and `provision/schema/**/.generated/**` as
+`linguist-generated`, so github renders them collapsed. the daos and the schemas themselves stay
+open: they are the internal contracts, so a reviewer reads them. to un-fold a path, see "what folds in a pr" in `src/practices/git/best-practice/.declapract.readme.md`.