declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/pnpm/declarations/practices/pnpm/__snapshots__/.declapract.integration.test.ts.snap

@@ -4,7 +4,7 @@ exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migrat
 "{
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",
@@ -23,7 +23,7 @@ exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migrat
 "{
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",
@@ -66,3 +66,10 @@ if changed 'package-lock.json'; then
 fi
 "
 `;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case4] a repo carrying an inert v11 allowBuilds block under the v10 pin when: [t0] the pnpm practice is applied to pnpm-workspace.yaml then: before matches snapshot (the inert block that was removed): pnpm-workspace.yaml — before 1`] = `
+"allowBuilds:
+  esbuild: true
+  node-pty: true
+"
+`;

package/dist/.test/assets/pnpm/declarations/practices/pnpm/bad-practices/inert-build-allowlist/pnpm-workspace.yaml.declapract.ts

@@ -0,0 +1,59 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects a `pnpm-workspace.yaml` that carries an `allowBuilds:` block and removes it.
+ *         when the block is the file's sole content, the whole file is deleted.
+ * .why  = `allowBuilds:` is pnpm v11 syntax; the pnpm practice pins v10 (`pnpm@10.34.5`), where
+ *         the build allowlist key is `pnpm.onlyBuiltDependencies` (an ARRAY, in package.json).
+ *         so an `allowBuilds:` block under the v10 pin does ZERO work — yet it READS like a live
+ *         allowlist, the exact trap #575 / ehmpathy/rhachet#475 burned an hour on.
+ * .note = the fix is DELETE, not a boolean-fill and not a fail-loud stub. (1) rhachet retired the
+ *         manual allowlist step ("by subtraction"); declapract emits no allowlist to converge to.
+ *         (2) a real allowlist is repo-specific (the v10 `pnpm.onlyBuiltDependencies` array the
+ *         repo adds itself). an inert block does no work, so its removal cannot regress a build.
+ * .note = idempotent — after fix the key is gone, check no longer detects it, re-run is a no-op.
+ */
+const ALLOW_BUILDS_KEY = /^allowBuilds:/;
+
+/** a yaml child line: whitespace-indented, then non-whitespace (the block's nested entries). */
+const isIndentedChild = (line: string): boolean => /^\s+\S/.test(line);
+
+/**
+ * strip the `allowBuilds:` key line + its contiguous indented child lines. a pure fold over the
+ * lines with an immutable `{ inBlock, kept }` accumulator (no `let`, no in-place push): the key
+ * line opens the block (and is dropped), each indented child is dropped while open, and the first
+ * non-indented (or blank) line closes the block and is kept. handles more than one block, since a
+ * later key line simply re-opens.
+ */
+const stripAllowBuildsBlock = (contents: string): string =>
+  contents
+    .split('\n')
+    .reduce<{ inBlock: boolean; kept: string[] }>(
+      (acc, line) => {
+        // the key line opens the block and is itself dropped
+        if (ALLOW_BUILDS_KEY.test(line))
+          return { inBlock: true, kept: acc.kept };
+        // an indented child of an open block is dropped
+        if (acc.inBlock && isIndentedChild(line)) return acc;
+        // any non-indented (or blank) line closes the block and is kept
+        return { inBlock: false, kept: [...acc.kept, line] };
+      },
+      { inBlock: false, kept: [] },
+    )
+    .kept.join('\n');
+
+const hasAllowBuilds = (contents: string): boolean =>
+  contents.split('\n').some((line) => ALLOW_BUILDS_KEY.test(line));
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents === null) throw new Error('does not match bad practice');
+  if (!hasAllowBuilds(contents)) throw new Error('does not match bad practice');
+  return;
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+  const stripped = stripAllowBuildsBlock(contents);
+  if (stripped.trim() === '') return { contents: null };
+  return { contents: stripped };
+};

package/dist/.test/assets/pnpm/declarations/practices/pnpm/best-practice/.declapract.readme.md

@@ -1,7 +1,7 @@
 # pnpm best-practice — what this practice owns, and what it does NOT
 
 this practice owns the pnpm **adoption** signal: the `packageManager` exact pin
-(`pnpm@10.31.7`, an intentional org-convergence requirement — see the `.declapract.ts` note).
+(`pnpm@10.34.5`, an intentional org-convergence requirement — see the `.declapract.ts` note).
 
 ## where the hoisted-linker `.npmrc` lives — NOT here
 

package/dist/.test/assets/pnpm/declarations/practices/pnpm/best-practice/package.json

@@ -1,3 +1,3 @@
 {
-  "packageManager": "pnpm@10.31.7"
+  "packageManager": "pnpm@10.34.5"
 }

package/dist/.test/assets/pnpm/declarations/practices/pnpm/best-practice/package.json.declapract.ts

@@ -1,13 +1,15 @@
 import { FileCheckType } from 'declapract';
 
 /**
- * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.31.7`), not a minVersion.
+ * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.34.5`), not a minVersion.
  * .why  = this is an intentional org-standardization REQUIREMENT, not an oversight. every pnpm
  *         consumer runs ONE blessed pnpm version, so `corepack` / `pnpm/action-setup@v4` load the
  *         identical toolchain across CI, local, and every repo — reproducible installs, no per-repo
  *         drift. an exact pin is also the ONLY correct shape here: the `packageManager` field is a
  *         corepack spec that requires the `pnpm@<version>` prefix, which declapract's bare-semver
- *         `check.minVersion(..)` cannot emit.
+ *         `check.minVersion(..)` cannot emit. the pin's major stays v10 by hard rule — see
+ *         `.agent/repo=.this/role=any/briefs/rule.require.pnpm-major-v10.md` (v11 inverts the
+ *         build-allowlist model the peer practices encode).
  * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
  *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
  *         the org bumps the blessed version, this pin bumps and every consumer follows.

package/dist/.test/assets/runtime-schemas/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the runtime-schemas practice integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/.declapract.integration.test.ts

@@ -0,0 +1,102 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the joi->zod migration, run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo. per
+ *   rule.require.declapract-integration-tests, a fix that TRANSFORMS a file (regex rewrite + a
+ *   value-rewrite @declapract:review marker) owes a pipeline test — a unit test of the exported
+ *   `fix` never exercises the source-file glob -> file match, nor that the marker lands on disk.
+ * .why = the shape-for-shape rewrite makes three silent semantic changes a regex cannot get right
+ *   (optionality, unknown-key policy, date coercion), so the fix prepends a @declapract:review
+ *   marker that names them rather than ship a silent guess (#594).
+ * .note = the target file is snapshotted in full (before AND after), so a reviewer can eyeball the
+ *   exact end-state, per rule.require.declapract-integration-tests.
+ * .teeth = the input imports joi + declares a `Joi.object` schema. the after-state proves the import
+ *   is rewritten to `zod`, the `Joi.*` calls become `z.*`, and the @declapract:review marker lands
+ *   on disk — the glue a mocked-context unit test cannot show.
+ */
+describe('joi->zod migration', () => {
+  given('[case1] a repo with a joi schema in a src file', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-joi',
+      clone: './src/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/runtime-schemas/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/contract/schemas/widget.schema.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'runtime-schemas',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the src file imports joi + declares a Joi schema + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain("from 'joi'");
+        expect(before).toContain('Joi.object(');
+        expect(before).not.toContain('@declapract:review');
+        expect(before).toMatchSnapshot('widget.schema.ts — before');
+      });
+    });
+
+    when('[t1] the joi fix is applied', () => {
+      useThen('migrate the joi schema to zod', async () => applyMigrate());
+
+      then(
+        'the import + schema are rewritten to zod, the review marker lands, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the import is rewritten to zod
+          expect(after).toContain("import { z } from 'zod'");
+          expect(after).not.toContain("from 'joi'");
+
+          // the Joi.* schema calls become z.*
+          expect(after).toContain('z.object(');
+          expect(after).not.toContain('Joi.object(');
+
+          // the value-rewrite marker lands on disk — the three silent semantic guesses
+          // (optionality, unknown keys, date coercion) are loud, per #594
+          expect(after).toContain('@declapract:review');
+          expect(after).toContain('optionality');
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('widget.schema.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // post-rewrite the file imports from zod, so the check no longer detects the bad practice and
+      // the fix does not run — the second apply changes zero bytes, and the marker is never
+      // double-prepended (per rule.require.idempotent-fixes).
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = await read(targetPath); // post-first-migrate
+        await applyMigrate(); // second apply
+        const after = await read(targetPath);
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/.declapract.readme.md

@@ -0,0 +1,3 @@
+joi has been replaced by zod as the preferred runtime type-checking library.
+
+zod provides better TypeScript integration with automatic type inference, smaller bundle size, and a more modern API.

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/declapract.use.yml

@@ -0,0 +1,5 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/runtime-schemas symlink to the real practice), so the consumer's own src/ tree
+#         stays free to hold the target .ts file the src/**/*.ts glob matches.
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/package.json

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

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/src/contract/schemas/widget.schema.ts

@@ -0,0 +1,9 @@
+import Joi from 'joi';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = Joi.object({
+  name: Joi.string().required(),
+  count: Joi.number(),
+  createdAt: Joi.date(),
+});

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t0] the migration input (before any fix) then: the src file imports joi + declares a Joi schema + matches snapshot: widget.schema.ts — before 1`] = `
+"import Joi from 'joi';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = Joi.object({
+  name: Joi.string().required(),
+  count: Joi.number(),
+  createdAt: Joi.date(),
+});
+"
+`;
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t1] the joi fix is applied then: the import + schema are rewritten to zod, the review marker lands, and it matches snapshot: widget.schema.ts — after 1`] = `
+"/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+import { z } from 'zod';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  createdAt: z.date(),
+});
+"
+`;

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "joi": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/package.json.declapract.ts

@@ -0,0 +1,23 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = JSON.parse(contents);
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: {
+      ...packageJSON.dependencies,
+      joi: undefined,
+      zod: packageJSON.dependencies?.zod ?? '^3.24.0',
+    },
+    devDependencies: {
+      ...packageJSON.devDependencies,
+      '@types/joi': undefined,
+    },
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/bad-practices/joi/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,79 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects joi imports in source files
+ * .why = joi should be replaced with zod for better typescript integration
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match if file imports from joi
+  if (contents?.includes("from 'joi'")) return;
+  if (contents?.includes('from "joi"')) return;
+
+  // no match
+  throw new Error('does not import from joi');
+};
+
+/**
+ * .what = a loud marker prepended to every rewritten file, so the three SILENT semantic
+ *         changes this mechanical rewrite makes become visible to the consumer.
+ * .why = the rewrite is a regex, and a regex cannot know a field's intended optionality, its
+ *        unknown-key policy, or whether a date arrives as a string. it therefore GUESSES, and each
+ *        guess typechecks. per the value-rewrite guard, a rewrite that must guess emits a review
+ *        marker rather than a silent, possibly-wrong result (#594). the consumer deletes the marker
+ *        once each point is verified by hand.
+ */
+const reviewMarker = `/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+`;
+
+/**
+ * .what = transforms joi imports and basic schema patterns to zod, with a review marker
+ * .why = automated migration reduces manual toil, but the shape-for-shape rewrite makes three
+ *        silent semantic changes a regex cannot get right — so it prepends a @declapract:review
+ *        marker that flags them, rather than ship a silent guess (#594).
+ *
+ * .note = basic transforms only; complex patterns require manual fix
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  const transformed = contents
+    // transform imports: import Joi from 'joi' → import { z } from 'zod'
+    .replace(/import\s+Joi\s+from\s+['"]joi['"]/g, "import { z } from 'zod'")
+    // transform imports: import * as Joi from 'joi' → import { z } from 'zod'
+    .replace(
+      /import\s+\*\s+as\s+Joi\s+from\s+['"]joi['"]/g,
+      "import { z } from 'zod'",
+    )
+    // transform imports: import { ... } from 'joi' → import { z } from 'zod'
+    .replace(
+      /import\s+\{[^}]*\}\s+from\s+['"]joi['"]/g,
+      "import { z } from 'zod'",
+    )
+    // transform basic schema patterns: Joi.* → z.*
+    .replace(/Joi\.object/g, 'z.object')
+    .replace(/Joi\.string/g, 'z.string')
+    .replace(/Joi\.number/g, 'z.number')
+    .replace(/Joi\.boolean/g, 'z.boolean')
+    .replace(/Joi\.array/g, 'z.array')
+    .replace(/Joi\.date/g, 'z.date')
+    .replace(/Joi\.any/g, 'z.any')
+    // transform .required() → remove (zod is required by default)
+    .replace(/\.required\(\)/g, '');
+
+  // prepend the review marker once, so the silent semantic guesses are loud (idempotent: the
+  // check no longer fires post-rewrite, and a second pass would find the marker already present)
+  const updated = transformed.includes('@declapract:review')
+    ? transformed
+    : reviewMarker + transformed;
+
+  return { contents: updated };
+};

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/best-practice/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "zod": "@declapract{check.minVersion('3.24.0')}"
+  }
+}

package/dist/.test/assets/runtime-schemas/declarations/practices/runtime-schemas/best-practice/package.json.declapract.ts

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

package/dist/.test/assets/runtime-schemas/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the runtime-schemas practice integration test
+use-cases:
+  lambda-service:
+    practices:
+      - runtime-schemas

package/dist/.test/assets/tests-service/declarations/declapract.declare.yml

@@ -0,0 +1,10 @@
+# minimal declarations for the tests-service package.json (#598 wake-command gate) integration test.
+# .why = a `file`-only apply (never `--practice`, so `projectPractices` keeps every usecase
+#        practice) compiles EVERY practice under `practices:`. pointed at the real `src/practices`
+#        (~40 practices) that blows the jest hook timeout, so this mirror holds a symlink to only
+#        the one practice the applied declaration lives in: tests-service. the #598 emit gate keys
+#        off the CONSUMER's config/prep.json tunnel (written by the test), not projectPractices, so
+#        a single lean practice suffices.
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/tests-service/declarations/practices/tests-service/.test/assets/demo-repo-service/declapract.use.yml

@@ -0,0 +1,5 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: service-tests
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'

package/dist/.test/assets/tests-service/declarations/practices/tests-service/.test/assets/demo-repo-service/package.json

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

package/dist/.test/assets/tests-service/declarations/practices/tests-service/__snapshots__/package.json.declapract.integration.test.ts.snap

@@ -0,0 +1,26 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`tests-service package.json — the #598 wake-command gate, end to end given: [case1] a consumer that reaches the shared cluster (tunnel declared) when: [t0] the tests-service package.json declaration is applied then: the emitted package.json matches snapshot: package.json — tunnel consumer (wake command emitted) 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "devDependencies": {
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  },
+  "scripts": {
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
+  }
+}
+"
+`;
+
+exports[`tests-service package.json — the #598 wake-command gate, end to end given: [case2] a consumer that reaches NO cluster (no tunnel declared) when: [t0] the tests-service package.json declaration is applied then: the emitted package.json matches snapshot (the stripped shape): package.json — no-tunnel consumer (wake command stripped) 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "devDependencies": {
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  }
+}
+"
+`;

package/dist/.test/assets/tests-service/declarations/practices/tests-service/asFunctionNameFromTestFileName.ts

@@ -0,0 +1,7 @@
+import { basename } from 'node:path';
+
+export const asFunctionNameFromTestFileName = (input: {
+  relativeFilePath: string;
+}): string =>
+  // the function name = the test file's basename, minus the acceptance-test extension
+  basename(input.relativeFilePath).replace('.acceptance.test.ts', '');

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/.declapract.readme.md

@@ -0,0 +1,68 @@
+# tests-service
+
+the acceptance-test layer for a lambda service — blackbox tests that invoke a deployed (or local)
+lambda fleet through its real contract.
+
+## acceptance targets the contemp fleet
+
+a service that dual-publishes (see the `serverless` + `environments` practices) ships its fleet
+under BOTH slugs through the ancient→contemp transition: `-dev-` (ancient) and `-prep-`/`-prod-`
+(contemp) — the SAME artifact under two names. so its own acceptance suite proves ONE fleet, the
+contemp one: a run against contemp proves the deployed code, and the ancient slug is an alias for
+inbound callers still on the old name, never a second target for the self-acceptance gate.
+
+contemp is the service's own access-tier slug — `-prep-` at prep, `-prod-` at prod — so a single
+access-keyed run covers every tier the deploy job ships. there is no per-fleet fan-out and no
+per-tier skip.
+
+the reusable primitive lives in the `environments` practice, one procedure per file:
+`src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts` — `sdkAwsLambdaEnvAccessContemp()` emits the
+access direct (`-prep-` at prep, `-prod-` at prod). its ancient sibling
+`sdkAwsLambdaEnvAccessAncient()` (emits the `-dev-` slug below prod) serves OUTBOUND calls to
+unmigrated peers, not the self-acceptance suite.
+
+the composition atop that primitive is per-service (a service wraps `invokeLambdaForTesting` once,
+at a local seam, so the contemp-slug target lands in one place rather than at every call site):
+
+```ts
+// blackbox/lambdaTestMethods.ts — a per-service seam onto simple-lambda-testing-methods
+import { invokeLambdaForTesting as invokeLambdaForTestingRaw } from 'simple-lambda-testing-methods';
+import { sdkAwsLambdaEnvAccessContemp } from '../src/access/sdks/sdkAwsLambdaEnvAccessContemp';
+
+export const invokeLambdaForTesting: typeof invokeLambdaForTestingRaw = (input) =>
+  invokeLambdaForTestingRaw({ ...input, stage: sdkAwsLambdaEnvAccessContemp() });
+```
+
+each blackbox test imports `invokeLambdaForTesting` from that seam, and one package command runs the
+suite against the contemp fleet:
+
+```jsonc
+"test:acceptance": "set -eu && npm run test:acceptance:jest"
+```
+
+## why the seam is per-service, not a shipped template
+
+the seam is composition, not a primitive: a given service re-exports its own extra test operations
+through it (an apigateway-event builder, a graphql event builder), and its blackbox tree shape
+varies. so the practice ships the reusable primitive (the `EnvAccess` helper) and documents this
+composition, rather than a one-shape-fits-all seam file. lift the seam to a shipped template only
+once two or more services share the identical composition (`rule.prefer.wet-over-dry`).
+
+## the PR acceptance gate runs in-process; the deployed-fleet run is post-deploy
+
+the shared `.test.yml` PR gate (cicd-common) runs its acceptance shards IN-PROCESS (`LOCALLY=true`),
+because a PR has no deployed lambda to invoke. a service that publishes only dev/prep (no `test`
+fleet) would otherwise target `svc-<name>-test-*` — a slug that does not exist — and 404 on every
+call, so the PR gate would regress to all-404 the moment the suite is non-empty. the in-process
+default lets a fleetless service inherit a green PR gate out of the box, with no hand-patch. the
+acceptance run against a DEPLOYED fleet is a separate post-deploy grain (`.deploy-sls.yml`'s
+`assure` job), which invokes the real deployed lambda.
+
+## the CI acceptance gate runs contemp only
+
+`.deploy-sls.yml`'s `assure` job runs `ACCESS=${{ inputs.access }} npm run test:acceptance` ONCE —
+against the contemp fleet the same job just deployed. contemp maps to the deployed access at
+both prep and prod, so one run covers every tier this job ships. the ancient slug is proven by
+identity: dual-publish deploys the SAME artifact under the `-dev-` name, so a green contemp run is
+a green ancient run. the self-acceptance gate never invokes the ancient fleet — that slug exists
+for inbound callers still on the old name, an alias, never a second target to test.

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/blackbox/<star><star>/<star>.acceptance.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should be atleast one acceptance test

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/blackbox/lambdas/<star>.acceptance.test.ts.declapract.ts

@@ -0,0 +1,56 @@
+import type { FileCheckFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { asFunctionNameFromTestFileName } from '../../../asFunctionNameFromTestFileName';
+
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents)
+    throw new ConstraintError(
+      'expected at least one lambda acceptance test; add a `describe` block that invokes the lambda',
+      { relativeFilePath: context.relativeFilePath },
+    );
+
+  // check that each import was found.
+  // D52: this check no longer MANDATES `import { stage } from '.../environment'`. that line was
+  // break-by-conformance: it forced 88 blackbox files onto the legacy `dev`-slug axis to build a
+  // target fleet name no peer publishes below prod. a consumer may still import what it needs, but
+  // the practice must not require the exact token the north-star exists to retire. the fleet-
+  // name rewrite (dev↔prep) is the collapse-coupled half (D52b) and is out of this check.
+  //
+  // .note = the match below is literal, not semantic. it holds by construction on the file the
+  // practice itself stamps, but a consumer's own import-sorter may later wrap a line, merge it with
+  // a co-specifier import, or swap the quote style — any of which trips a cryptic `Expected imports`
+  // throw against a functionally-equivalent file. the literal match is deliberate (both lines dodge
+  // a typical print-width wrap), and a lenient regex/ast match is a tracked follow-on; this comment
+  // is the durable disclosure, so the brittleness is legible in-code, not only in the route yield
+  // (i015 r10 §3).
+  const expectedImports = [
+    "import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';",
+    "import { locally } from '../environment';",
+  ];
+  const missedImports = expectedImports.filter(
+    (expectedImport) => !contents.includes(expectedImport),
+  );
+  if (missedImports.length)
+    throw new ConstraintError(
+      `
+${`- Expected imports ${['', ...expectedImports].join('\n  - ')}`}
+      `.trim(),
+      { relativeFilePath: context.relativeFilePath, missedImports },
+    );
+
+  const expectedTestName = asFunctionNameFromTestFileName({
+    relativeFilePath: context.relativeFilePath,
+  });
+  const expectedDescribe = `
+describe('${expectedTestName}', () => {
+  `.trim();
+  // route the describe-name mismatch through a ConstraintError, same as the paths above —
+  // a bare `expect(...).toContain(...)` throws jest's raw ANSI+middle-dot diff, which snapshots
+  // as terminal noise (rule.forbid.snapshot-visual-blemishes). name the derived describe plainly.
+  if (!contents.includes(expectedDescribe))
+    throw new ConstraintError(
+      `expected a \`describe\` block that names the derived function: ${expectedDescribe}`,
+      { relativeFilePath: context.relativeFilePath, expectedTestName },
+    );
+};

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/package.json

@@ -0,0 +1,8 @@
+{
+  "devDependencies": {
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  },
+  "scripts": {
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
+  }
+}