declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/best-practice/.github/workflows/.declastruct.yml

@@ -18,18 +18,18 @@ on:
         required: true
       scope:
         type: string
-        description: "the provider backend this wish targets (github | aws); scopes the plan artifact name"
+        description: "the provider backend this wish targets (github | aws)"
         required: true
       access:
         type: string
-        description: "the access tier this wish targets (test | prep | prod); read by the wish via sdk-environment as the ACCESS envar (aws wishes), and scopes the plan artifact name so parallel calls do not collide"
+        description: "the access to provision with (test | prep | prod)"
         required: true
       github-environment-plan:
         type: string
-        description: "github environment for the plan job (empty = no env gate)"
+        description: "github environment for the plan job"
       github-environment-apply:
         type: string
-        description: "github environment for the apply job (empty = no env gate)"
+        description: "github environment for the apply job"
       allow-apply:
         type: boolean
         description: "whether the apply step is enabled. defaults to true on main"
@@ -69,7 +69,12 @@ jobs:
 
   plan:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-plan }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-plan }}
+      deployment: false
     needs: [install]
     env:
       ACCESS: ${{ inputs.access }} # aws wishes: sdk-environment getEnvironment reads ACCESS
@@ -119,8 +124,12 @@ jobs:
       - name: evaluate plan
         id: evaluate-plan
         run: |
-          # declastruct prints this exact phrase when there is no diff
-          if grep "in sync" ./plan.log
+          # declastruct prints `🎉 everything is in sync!` (LOWERCASE) when there is no diff.
+          # grep -qF: fixed-string (no char read as regex), quiet (the exit code is the whole
+          # signal), and the full phrase so an unrelated line that holds "in sync" cannot
+          # false-match. the marker is lowercase — a capital-lead grep never matches it, so the
+          # fast path would be dead code (#561).
+          if grep -qF "everything is in sync" ./plan.log
           then
             echo "has-changes-planned=false" >> "$GITHUB_OUTPUT"
           else
@@ -142,7 +151,12 @@ jobs:
 
   apply:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: [install, plan]
     if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
     env:

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/best-practice/.github/workflows/.test.yml

@@ -252,16 +252,7 @@ jobs:
 
       - name: report slow tests
         if: always() && hashFiles('jest-results.json') != ''
-        run: |
-          set -eu
-          jq -r '.testResults[] | select(.perfStats.runtime != null) | "\(.name):\(.perfStats.runtime)"' jest-results.json | while IFS=: read -r name runtime; do
-            seconds=$((runtime / 1000))
-            if [[ $seconds -ge 30 ]]; then
-              echo "::warning file=${name}::slow test: ${seconds}s"
-            elif [[ $seconds -ge 10 ]]; then
-              echo "::notice file=${name}::test duration: ${seconds}s"
-            fi
-          done
+        run: bash .github/workflows/report-slow-tests.sh jest-results.json
 
   test-shards-acceptance:
     runs-on: ubuntu-24.04
@@ -316,12 +307,18 @@ jobs:
       - name: build
         run: npm run build
 
+      # .why = the PR acceptance gate runs IN-PROCESS (LOCALLY=true), not against a deployed fleet.
+      #        a PR has no deployed lambda to invoke, and a service that publishes only dev/prep (no
+      #        `test` fleet) would target `svc-<name>-test-*` — a slug that does not exist — and 404
+      #        on every call. in-process runs the handler directly, so a fleetless service inherits a
+      #        green PR gate out of the box rather than hand-patching LOCALLY=true into this shard.
+      #        the deployed-fleet acceptance run is a separate post-deploy grain (.deploy-sls.yml).
       - name: test:acceptance (explicit ${{ matrix.shard.index }})
         if: matrix.shard.type == 'explicit'
         run: |
           set -eu
           patterns='${{ join(matrix.shard.patterns, '|') }}'
-          THOROUGH=true npm run test:acceptance -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
+          LOCALLY=true THOROUGH=true npm run test:acceptance -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
 
       - name: test:acceptance (dynamic ${{ matrix.shard.shard }}/${{ matrix.shard.total }})
         if: matrix.shard.type == 'dynamic'
@@ -329,23 +326,14 @@ jobs:
           set -eu
           exclude='${{ needs.enshard.outputs.acceptance-patterns }}'
           if [[ -n "$exclude" ]]; then
-            THOROUGH=true npm run test:acceptance -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+            LOCALLY=true THOROUGH=true npm run test:acceptance -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
           else
-            THOROUGH=true npm run test:acceptance -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+            LOCALLY=true THOROUGH=true npm run test:acceptance -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
           fi
 
       - name: report slow tests
         if: always() && hashFiles('jest-results.json') != ''
-        run: |
-          set -eu
-          jq -r '.testResults[] | select(.perfStats.runtime != null) | "\(.name):\(.perfStats.runtime)"' jest-results.json | while IFS=: read -r name runtime; do
-            seconds=$((runtime / 1000))
-            if [[ $seconds -ge 30 ]]; then
-              echo "::warning file=${name}::slow test: ${seconds}s"
-            elif [[ $seconds -ge 10 ]]; then
-              echo "::notice file=${name}::test duration: ${seconds}s"
-            fi
-          done
+        run: bash .github/workflows/report-slow-tests.sh jest-results.json
 
   # union job: aggregates shard results into single status for pr merge constraints
   test-integration:

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/best-practice/.github/workflows/.test.yml.declapract.ts

@@ -1,4 +1,5 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
 
 /**
  * .what = validates .test.yml matches the template exactly
@@ -9,7 +10,17 @@ export const check = FileCheckType.EQUALS;
 /**
  * .what = replaces .test.yml with the template content
  * .why = ensures workflow has firewall step for keyrack secrets
+ * .note = fail-fast on absent declared contents. a declared file ALWAYS has content — declapract
+ *         reads the template beside this declaration. so a null/undefined `declaredFileContents`
+ *         is an internal invariant violation (a build wired wrong), never a valid state; a `?? ''`
+ *         would swallow it and write a ZERO-BYTE workflow to a consumer — a silent break the wish
+ *         forbids. throw loud so the misconfigured build surfaces, rather than ship an empty file.
  */
 export const fix: FileFixFunction = async (_contents, context) => {
-  return { contents: context.declaredFileContents ?? '' };
+  if (context.declaredFileContents === null || context.declaredFileContents === undefined)
+    throw new MalfunctionError(
+      'no declaredFileContents for .test.yml — declapract could not read the template beside its declaration',
+      { relativeFilePath: '.github/workflows/.test.yml' },
+    );
+  return { contents: context.declaredFileContents };
 };

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/best-practice/.github/workflows/report-slow-tests.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = rank test files by wall-clock duration from a jest --json report
+#
+# .why  = jest 30 dropped the perfStats key that the prior report filtered on
+#         (`perfStats.runtime`), so the filter matched zero rows and the report
+#         went silent-green for its whole life (radio #602). endTime-startTime
+#         (epoch ms) is the only per-file duration jest 30 still emits, so read
+#         the wall-clock span instead — and fail LOUD if a future schema change
+#         zeroes it again, never silent-green.
+#
+# usage:
+#   report-slow-tests.sh [jest-results.json]
+#
+# guarantee:
+#   - exit 0 = report written to $GITHUB_STEP_SUMMARY (or /dev/null locally)
+#   - exit 0 = empty shard (0 test files) — a legitimate state, stated explicitly
+#   - exit 1 = non-empty report yielded zero real durations (schema drift)
+######################################################################
+set -eu
+
+results="${1:-jest-results.json}"
+
+total=$(jq '.testResults | length' "$results")
+durations=$(jq -r '.testResults[] | "\((.endTime // 0) - (.startTime // 0)):\(.name)"' "$results" | sort -t: -k1 -rn)
+
+summary="${GITHUB_STEP_SUMMARY:-/dev/null}"
+
+# an empty shard (no matched files) is legitimate — say so explicitly, never fail.
+if [[ "$total" -eq 0 ]]; then
+  echo "slow-test report: 0 test files in $results (empty shard)" >> "$summary"
+  exit 0
+fi
+
+# a non-empty testResults that yields zero real durations means the jest --json duration
+# schema changed again — the exact silent-death #602 fixed. fail loud, never silent-green.
+nonzero=$(printf '%s\n' "$durations" | awk -F: '$1 > 0' | wc -l | tr -d ' ')
+if [[ "$nonzero" -eq 0 ]]; then
+  echo "::error::slow-test report parsed 0 durations from $total test files — the jest --json duration schema likely changed (see radio #602)"
+  exit 1
+fi
+
+# a ranked table into the step summary — annotations cannot be sorted, and a diagnosis
+# needs the order (the single slowest file sets the suite's wall-clock floor).
+{
+  echo "### slowest test files"
+  echo ""
+  echo "| duration | file |"
+  echo "| --- | --- |"
+  printf '%s\n' "$durations" | while IFS=: read -r ms name; do
+    [ -z "$name" ] && continue
+    printf '| %ds | %s |\n' "$((ms / 1000))" "$name"
+  done
+} >> "$summary"
+
+# inline annotations flag the outliers at their file (the 30s/10s thresholds are inherited).
+printf '%s\n' "$durations" | while IFS=: read -r ms name; do
+  [ -z "$name" ] && continue
+  seconds=$((ms / 1000))
+  if [[ $seconds -ge 30 ]]; then
+    echo "::warning file=${name}::slow test: ${seconds}s"
+  elif [[ $seconds -ge 10 ]]; then
+    echo "::notice file=${name}::test duration: ${seconds}s"
+  fi
+done

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/declastruct-insync-grep.declapract.integration.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #561: the .declastruct.yml apply-gate greps the LOWERCASE marker declastruct
+ *         actually emits (`🎉 everything is in sync!`), so the in-sync fast path is live, not dead.
+ * .why  = declastruct's marker is lowercase (planChanges.ts: `context.log.info('🎉 everything is in
+ *         sync!')`). a capital-E `Everything is in sync` grep is case-sensitive and never matches, so
+ *         every plan falls to the has-changes-planned=true arm — a fast path dead its whole life. it
+ *         fails SAFE (over-gates), so no alarm ever fired; a clamp is the only thing that keeps the
+ *         grep tied to the tool's real output.
+ * .teeth = revert the grep to `grep "Everything is in sync"` (capital E) and the "greps the
+ *          lowercase marker" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the practice
+ *         ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('cicd-common .declastruct.yml in-sync grep', () => {
+  given('the shipped .declastruct.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.declastruct.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // declastruct emits this literal phrase, lowercase; the workflow must match it verbatim
+      const markerLower = 'everything is in sync';
+      const markerCapital = 'Everything is in sync';
+
+      then('it greps the lowercase marker declastruct actually emits', () => {
+        expect(yml).toContain(`grep -qF "${markerLower}"`);
+      });
+
+      then('it does NOT grep the capital-E form that never matches (#561)', () => {
+        expect(yml).not.toContain(markerCapital);
+      });
+
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        // snapshot the caller-faced contract itself, so a reword that keeps the
+        // marker token green (a re-ordered -qF, a re-phrased fallback) reddens a vibecheck
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep -qF "'));
+        expect(grepLine?.trim()).toMatchSnapshot('declastruct apply-gate grep');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/cicd-common/report-slow-tests.play.declapract.integration.test.ts

@@ -0,0 +1,144 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+/**
+ * .what = integration test for the report-slow-tests shell the .test.yml workflow shells out to.
+ * .why  = the prior inline report filtered on `perfStats.runtime`, a key jest 30 dropped — so it
+ *         matched zero rows and went silent-green for its whole life (radio #602). this clamps the
+ *         go-forward: it reads endTime-startTime, ranks by wall-clock, and — the whole point of the
+ *         fix — fails LOUD if a future schema change zeroes the durations again, never silent-green.
+ * .how  = spawn the shipped best-practice/.github/workflows/report-slow-tests.sh against fixture
+ *         jest-results.json files, with GITHUB_STEP_SUMMARY pointed at a temp file, and assert the
+ *         exit code, the summary table, and the stdout annotations.
+ * .note = subject is the SHIPPED shell template. this file sits at the PRACTICE ROOT (not under
+ *         best-practice/), so declapract's loader — which walks only best-practice/ for templates —
+ *         never reads it as a declaration and never copies it to a consumer. it is the play-test
+ *         counterpart to husky/check.timestamps.play.declapract.integration.test.ts.
+ */
+
+// the shell under test (the distributed best-practice template)
+const scriptPath = path.join(
+  __dirname,
+  'best-practice/.github/workflows/report-slow-tests.sh',
+);
+
+// write a fixture jest-results.json + a fresh summary sink into a temp dir; return their paths
+const genFixture = (
+  jestResults: unknown,
+): { resultsPath: string; summaryPath: string } => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'report-slow-tests-'));
+  const resultsPath = path.join(dir, 'jest-results.json');
+  const summaryPath = path.join(dir, 'step-summary.md');
+  fs.writeFileSync(resultsPath, JSON.stringify(jestResults));
+  fs.writeFileSync(summaryPath, '');
+  return { resultsPath, summaryPath };
+};
+
+// spawn the report against a fixture; return exit code + stdout + the summary file contents
+const runReport = (
+  jestResults: unknown,
+): { code: number | null; stdout: string; summary: string } => {
+  const { resultsPath, summaryPath } = genFixture(jestResults);
+  const res = spawnSync('bash', [scriptPath, resultsPath], {
+    encoding: 'utf-8',
+    env: { ...process.env, GITHUB_STEP_SUMMARY: summaryPath },
+  });
+  return {
+    code: res.status,
+    stdout: res.stdout,
+    summary: fs.readFileSync(summaryPath, 'utf-8'),
+  };
+};
+
+describe('report-slow-tests', () => {
+  given('[case1] a report with a slow (>30s), a medium (>10s), and a fast file', () => {
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() =>
+        runReport({
+          testResults: [
+            { name: '/repo/src/medium.test.ts', startTime: 1000, endTime: 16000 }, // 15s
+            { name: '/repo/src/fast.test.ts', startTime: 1000, endTime: 3000 }, // 2s
+            { name: '/repo/src/slow.test.ts', startTime: 1000, endTime: 41000 }, // 40s
+          ],
+        }),
+      );
+
+      then('it exits 0', () => {
+        expect(result.code).toEqual(0);
+      });
+
+      then('the summary carries the ranked table', () => {
+        expect(result.summary).toContain('### slowest test files');
+        expect(result.summary).toContain('| duration | file |');
+      });
+
+      then('the slowest file is ranked first in the table', () => {
+        const slowIdx = result.summary.indexOf('/repo/src/slow.test.ts');
+        const mediumIdx = result.summary.indexOf('/repo/src/medium.test.ts');
+        const fastIdx = result.summary.indexOf('/repo/src/fast.test.ts');
+        expect(slowIdx).toBeGreaterThan(-1);
+        expect(slowIdx).toBeLessThan(mediumIdx);
+        expect(mediumIdx).toBeLessThan(fastIdx);
+      });
+
+      then('it emits a warn annotation for the >30s file', () => {
+        expect(result.stdout).toContain(
+          '::warning file=/repo/src/slow.test.ts::slow test: 40s',
+        );
+      });
+
+      then('it emits a notice annotation for the >10s file', () => {
+        expect(result.stdout).toContain(
+          '::notice file=/repo/src/medium.test.ts::test duration: 15s',
+        );
+      });
+
+      then('it emits no annotation for the fast file', () => {
+        expect(result.stdout).not.toContain('/repo/src/fast.test.ts::');
+      });
+    });
+  });
+
+  given('[case2] a non-empty report whose durations are all zero (schema drift)', () => {
+    // the exact silent-death #602 fixed: testResults present, but no real duration to be read.
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() =>
+        runReport({
+          testResults: [
+            { name: '/repo/src/a.test.ts', startTime: 1000, endTime: 1000 },
+            { name: '/repo/src/b.test.ts', startTime: 2000, endTime: 2000 },
+          ],
+        }),
+      );
+
+      then('it fails loud with exit 1 (never silent-green)', () => {
+        expect(result.code).toEqual(1);
+      });
+
+      then('it prints an error annotation that names the schema drift', () => {
+        expect(result.stdout).toContain('::error::');
+        expect(result.stdout).toContain('jest --json duration schema');
+        expect(result.stdout).toContain('#602');
+      });
+    });
+  });
+
+  given('[case3] an empty shard (0 test files)', () => {
+    when('[t0] the report runs', () => {
+      const result = useBeforeAll(() => runReport({ testResults: [] }));
+
+      then('it exits 0 (an empty shard is legitimate)', () => {
+        expect(result.code).toEqual(0);
+      });
+
+      then('the summary states the empty-shard state explicitly', () => {
+        expect(result.summary).toContain('0 test files');
+        expect(result.summary).toContain('empty shard');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/__snapshots__/commitlint-body-max-line.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`conventional-commits commitlint body-max-line-length given: the shipped commitlint.config.js when: the body-max-line-length rule is read then: the emitted rule line matches snapshot: commitlint body-max-line-length rule line 1`] = `"'body-max-line-length': [1, 'always', 140],"`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/best-practice/commitlint.config.js

@@ -2,6 +2,11 @@ module.exports = {
   extends: ['@commitlint/config-conventional'],
   rules: {
     'header-max-length': [1, 'always', 140],
+    // match the header allowance: a squash-merge turns each commit header
+    // into a `* ` body bullet, so a 140-char header becomes a ~142-char body
+    // line. keep body lines aligned with the 140-char header cap so a long
+    // header can never fail the release-branch commit lint.
+    'body-max-line-length': [1, 'always', 140],
     'type-enum': [
       2,
       'always',

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "scripts": {
     "commit:with-cli": "npx cz",
-    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose"
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from \"${LAST_TAG:-}\" --to HEAD --verbose"
   },
   "devDependencies": {
     "@commitlint/cli": "@declapract{check.minVersion('19.5.0')}",

package/dist/.test/assets/expo-fullusecase/declarations/practices/conventional-commits/commitlint-body-max-line.declapract.integration.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #554/#570: the shipped commitlint.config.js overrides body-max-line-length
+ *         to warn-level 140, aligned with the header-max-length cap, so a squash-merge release PR
+ *         cannot fail test:commits on a long header-turned-body-bullet.
+ * .why  = config-conventional's default body-max-line-length is error-level 100. a github
+ *         squash-merge collapses a PR's sub-commit headers into `* ` body bullets, so a header
+ *         near the 140-char header cap becomes a body line over 100 — which errors the
+ *         release-branch lint even though every source header was valid. the template MUST carry
+ *         the override (not just this repo's own root config, which #570 fixed) so every consumer
+ *         inherits it.
+ * .teeth = delete the body-max-line-length line from best-practice/commitlint.config.js and the
+ *          "declares body-max-line-length" assertion reddens (the config-conventional default,
+ *          error-level 100, reasserts).
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the practice
+ *         ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('conventional-commits commitlint body-max-line-length', () => {
+  given('the shipped commitlint.config.js', () => {
+    const source = readFileSync(
+      join(__dirname, 'best-practice/commitlint.config.js'),
+      'utf8',
+    );
+    const ruleLine = source
+      .split('\n')
+      .find((line) => line.includes('body-max-line-length'));
+
+    when('the body-max-line-length rule is read', () => {
+      then('it declares body-max-line-length (not the config-conventional default)', () => {
+        expect(ruleLine).toBeDefined();
+      });
+
+      then('it is warn-level 140, aligned with the header cap (a long header cannot block a release)', () => {
+        expect(ruleLine).toContain('[1, ');
+        expect(ruleLine).toContain('140]');
+      });
+
+      // the emitted rule line is the caller-faced contract: snapshot it so a reword that keeps
+      // the tokens green (a re-ordered tuple, a level change) reddens a vibecheck.
+      then('the emitted rule line matches snapshot', () => {
+        expect(ruleLine?.trim()).toMatchSnapshot('commitlint body-max-line-length rule line');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/domain/.declapract.integration.test.ts

@@ -0,0 +1,115 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `domain` best-practice to the go-forward `src/domain.objects/` layout, so it
+ *         can never again require a file that its kin `directory-structure-src`'s `domain-dir`
+ *         bad-practice forbids (D51 / #574).
+ * .why  = both practices sit in `typescript-project-core`, so every service repo carries both.
+ *         `domain-dir` forbids EVERY file under `src/**​/domain/**` and its fix RELOCATES them to
+ *         `src/domain.objects/`. while `domain` required `src/domain/objects/index.ts`, a repo that
+ *         satisfied `domain` VIOLATED `domain-dir`, and `domain-dir`'s fix moved the required file
+ *         AWAY — a terminal, unrepairable state. keyed on `domain.objects`, the two agree:
+ *         `domain-dir`'s fix produces exactly what `domain` requires.
+ * .note = this is an INTEGRATION test by the same rule the sibling `actionPins` walk cites — it
+ *         reads the filesystem (`readdirSync` over the `domain` best-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any filesystem-crossing test in the integration
+ *         suite. it needs no credential and no network; the boundary alone classifies it.
+ * .note = this is the FOCUSED clamp for the one collision D51 named. the wish's broader durable
+ *         guard — "no best-practice path is matched by a bad-practice glob in the SAME usecase,
+ *         across every practice" — is owed as a follow-on; it must land with a full collision audit,
+ *         since a repo-wide lint may surface other overlaps already present that each need a verdict.
+ */
+
+const BEST_PRACTICE_DIR = `${__dirname}/best-practice`;
+
+// the `schematic-joi-model` bad-practice DETECTS joi models by content and rewrites them to
+// domain-objects. its subject glob scopes WHERE it looks; keyed at the deprecated `src/domain/`
+// path it is inert on any migrated repo (D51 / #574, ask 2) — the go-forward path is
+// `src/domain.objects/`, exactly where `directory-structure-src`'s `domain-dir` relocates files.
+const JOI_DETECTOR_DIR = `${__dirname}/bad-practices/schematic-joi-model`;
+
+/**
+ * .what = the CONSUMER target path a declaration governs, relative to a practice-half base dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix; any other file is
+ *         a template that governs itself.
+ */
+const asConsumerTargetPath = (input: { absPath: string; baseDir: string }): string => {
+  const rel = relative(input.baseDir, input.absPath);
+  return rel.replace(/\.declapract\.ts$/, '');
+};
+
+/**
+ * .what = does a consumer target path sit under a bare `domain/` path segment?
+ * .why = that is precisely the set `domain-dir`'s `src/**​/domain/**` glob forbids. a
+ *        `domain.objects` segment is NOT a `domain` segment (the `.objects` makes it a distinct
+ *        directory name), so the go-forward layout reads false here.
+ */
+const isUnderBareDomainSegment = (input: { targetPath: string }): boolean =>
+  input.targetPath.split('/').includes('domain');
+
+/**
+ * .what = every declared CONSUMER target path under a practice-half dir — the walk minus the files
+ *         that are not governed consumer paths (readmes, todos, `.test.ts`, `__snapshots__`).
+ * .why  = both scenes below gather the same set from different base dirs; one named transformer
+ *         holds the exclusion list in one place rather than an inline `.filter` chain a reader
+ *         must simulate twice (rule.require.named-transformers).
+ */
+const getConsumerTargetPaths = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null })
+    .filter((path) => !/\.declapract\.readme\.md$/.test(path))
+    .filter((path) => !/\.declapract\.todo\.md$/.test(path))
+    // a test file is not a governed consumer path — exclude it so the walk holds
+    // only real declarations to the layout, not `.test.ts` / `__snapshots__`
+    .filter((path) => !/\.test\.ts$/.test(path))
+    .filter((path) => !/\/__snapshots__\//.test(path))
+    .map((absPath) => asConsumerTargetPath({ absPath, baseDir: input.dir }));
+
+describe('domain practice — go-forward layout (D51 clamp)', () => {
+  given('[case1] the `domain` best-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: BEST_PRACTICE_DIR }),
+    }));
+
+    when('[t0] its declared consumer target paths are gathered', () => {
+      then('none sits under a bare `domain/` segment that `domain-dir` forbids', () => {
+        // teeth: the pre-fix declaration at `src/domain/objects/index.ts.declapract.ts` targets
+        // `src/domain/objects/index.ts`, whose `domain` segment is exactly what `domain-dir`
+        // relocates — so a revert of the move to the deprecated path reddens this assertion.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the objects index is declared at the `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/index.ts');
+      });
+    });
+  });
+
+  given('[case2] the `schematic-joi-model` bad-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: JOI_DETECTOR_DIR }),
+    }));
+
+    when('[t0] its declared subject glob paths are gathered', () => {
+      then('none sits under a bare `domain/` segment (else the detector is inert post-migration)', () => {
+        // teeth: revert the glob to `src/domain/**/*.ts.declapract.ts` and its subject path
+        // `src/domain/**/*.ts` carries a bare `domain` segment — the deprecated location a
+        // migrated repo no longer holds — so this assertion reddens.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the joi detector targets the go-forward `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/**/*.ts');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/domain/bad-practices/schematic-joi-model/src/{domain → domain.objects}/<star><star>/<star>.ts.declapract.ts

@@ -3,7 +3,10 @@ import type { FileCheckFunction, FileFixFunction } from 'declapract';
 export const check: FileCheckFunction = (contents) => {
   if (contents?.includes('SchematicJoiModel')) return; // if it includes that, then this file matches a bad practice
   if (contents?.includes('schematic-joi-model')) return; // if it includes that, then this file matches a bad practice
-  throw new Error('passes'); // otherwise, does not match the bad practice
+  // otherwise, does not match the bad practice: no SchematicJoiModel import or schematic-joi-model reference found
+  throw new Error(
+    'does not match bad practice: no SchematicJoiModel or schematic-joi-model reference found',
+  );
 };
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {}; // shouldnt be called if file does not exist, but handle it in case anyway

package/dist/.test/assets/expo-fullusecase/declarations/practices/domain/best-practice/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "domain-objects": "@declapract{check.minVersion('0.31.13')}",
-    "type-fns": "@declapract{check.minVersion('1.21.3')}"
+    "domain-objects": "@declapract{check.minVersion('0.34.0')}",
+    "type-fns": "@declapract{check.minVersion('1.21.4')}"
   }
 }

package/dist/.test/assets/expo-fullusecase/declarations/practices/domain/best-practice/src/domain.objects/index.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType } from 'declapract';
+
+// a project should declare domain objects — otherwise, what does the service operate on?
+//
+// this requires the `src/domain.objects/` layout that `directory-structure-src`'s `domain-dir`
+// bad-practice enforces. it deliberately does NOT require the deprecated `src/domain/objects/`
+// path: `domain-dir` forbids every file under `src/**/domain/**` and its fix relocates them to
+// `src/domain.objects/`, so a check that required `src/domain/objects/index.ts` (D51) contradicted
+// its own kin — `domain-dir`'s fix moved the required file away, so a repo reached a terminal,
+// unrepairable state. keyed on the go-forward layout, the two practices agree: `domain-dir`'s fix
+// produces exactly this path.
+export const check = FileCheckType.EXISTS;