froid-plane-test-architecture-enterprise 1.23.4

package/src/workflows/testarch/froid-testarch-automate/resources/knowledge/pact-consumer-framework-setup.md

@@ -0,0 +1,704 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+// See pact-consumer-framework-setup.md Example 2 "Key Points" for rationale on
+// fileParallelism + pool:forks + singleFork. Do not remove those three settings.
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+    fileParallelism: false,
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
+  },
+});
+```
+
+**Key Points**:
+
+- **`fileParallelism: false` is required** — primary defense against non-deterministic pact generation. Without it, parallel workers race on the shared pact JSON file and corrupt interactions. Symptom: local runs pass, CI randomly fails with `Cannot change pact content for already published pact`. The `publish-pact.sh` `jq` sort (Example 4) provides byte-stability at publish time.
+- **`pool: 'forks'` + `singleFork: true` is required for multi-file consumer suites** — same config the provider side uses (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; with the default threads pool (Vitest v1) and multiple `.pacttest.ts` files on the same consumer+provider pair, we observed reproducible "request was expected but not received" flakes on Linux CI only. `singleFork: true` serializes every pact file into one forked subprocess and eliminated the flake across multiple repos. Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
+- **One `.pacttest.ts` per consumer+provider pair is the canonical pattern** — not just an observation. Two files for the same pair in one process (which `singleFork: true` guarantees) cause an FFI handle collision: the second file's `new PactV4(...)` call re-enters the FFI handle still holding stale state from the first file → "request was expected but not received" sporadically on Linux CI. The fix is structural — merge the files, not the config. `pool: 'forks'` is still required for pact JSON write safety but does NOT prevent same-pair file splits from colliding. Multiple files for **different** pairs (different consumer or provider name) are correct and safe. See Example 10 for the ✅/❌ pattern.
+- **Interacting settings**: leave `isolate` at its default (`true`). Do NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, or `maxWorkers > 1` in this config — they defeat the serialization this rule relies on. `hookTimeout` may be raised if mock-server startup is slow, but keep `testTimeout` ≥ `hookTimeout`.
+- Do NOT add `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker.
+#
+# Before publish, normalize each pact JSON: sort interactions by (description, provider state name,
+# method, path) and sort object keys via `jq -S`. This gives byte-stable output to the broker even
+# if the PactV4 generator produces ordering drift between runs. Ensures "Cannot change pact content"
+# from PactFlow never fires on ordering-only changes.
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH, jq
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+# Defense-in-depth: normalize interaction order for byte-stable publishes.
+for f in "$PACT_DIR"/*.json; do
+  tmp="$(mktemp)"
+  jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)' \
+     "$f" > "$tmp"
+  mv "$tmp" "$f"
+done
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — ensures byte-stable payload to the broker regardless of generator ordering quirks.
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker (publish-pact.sh also normalizes interaction order as defense-in-depth)
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **1:1 local/CI parity is a hard rule**: every CI step is `npm run <same-name-a-dev-uses>`. Never let CI invoke `vitest` or `pact-broker` directly — that divergence is how "works on my machine" slips in. Consumer tests, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        setJsonBody(
+          like({
+            id: integer(1),
+            name: string('The Matrix'),
+            year: integer(1999),
+            rating: like(8.7),
+            director: string('Wachowskis'),
+          }),
+        ),
+      )
+      .executeTest(async (mockServer: V3MockServer) => {
+        // Inject mock server URL into the REAL consumer code
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- Consumer code MUST expose a URL injection mechanism: `setApiUrl()`, env var override, or constructor parameter
+- If the consumer code doesn't support URL injection, add it — this is a design prerequisite for CDC testing
+- Use PactV4 `addInteraction()` builder (not PactV3 fluent API with `withRequest({...})` object)
+- **Interaction naming convention**: Use the pattern `"a request to <action> <resource> [<condition>]"` for `uponReceiving()`. Examples: `"a request to get a movie by ID"`, `"a request to delete a non-existing movie"`, `"a request to create a movie that already exists"`. These names appear in Pact Broker UI and verification logs — keep them descriptive and unique within the consumer-provider pair.
+- Use `setJsonContent` for request/response builder callbacks with query/header/body concerns; use `setJsonBody` for body-only response callbacks
+- Provider state factory functions (`movieExists`) return `ProviderStateInput` objects
+- `createProviderState` converts to `[stateName, stateParams]` tuple for `.given()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+### Example 10: Test File Organization — One File Per Consumer+Provider Pair
+
+**Context**: Avoiding Pact Rust FFI handle collisions when structuring consumer test files.
+
+**Rule**: Every consumer+provider pair maps to exactly one `.pacttest.ts` file. Never split interactions for the same pair across multiple files.
+
+**Root cause**: The Pact Rust FFI maintains one handle per consumer+provider pair per process. With `singleFork: true` (all files run sequentially in one forked process), two files for the same pair access the same FFI handle back-to-back. The second file's `new PactV4({ consumer, provider })` call re-enters the handle still holding stale interaction state from the first file. The first test in the second file starts the mock server in this corrupted state — "request was expected but not received" results, sporadic and Linux-CI-only (execution order differs between environments).
+
+**Evidence**: In `pactjs-utils`, `movies-read.pacttest.ts` and `movies-write.pacttest.ts` both used `consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI'`. The vitest config and CI workflow were correct throughout. The fix was merging the two files into `movies.pacttest.ts`. The config was not changed.
+
+```typescript
+// ❌ WRONG — same consumer+provider pair split across two files
+// movies-read.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Read Operations', () => { /* 4 tests: GET /movies, GET /movies/:id */ })
+
+// movies-write.pacttest.ts  ← second PactV4 for the SAME pair = FFI handle collision
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Write Operations', () => { /* 5 tests: POST, PUT, DELETE */ })
+
+// ✅ RIGHT — one file per consumer+provider pair, describe blocks for organization
+// movies.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Movies API', () => {
+  describe('Read Operations', () => { /* 4 tests */ })
+  describe('Write Operations', () => { /* 5 tests */ })
+})
+```
+
+**Key Points**:
+
+- **File = contract**: A `.pacttest.ts` file represents one consumer+provider contract. One contract = one file.
+- **Describe blocks, not files**: Organize by operation type (`Read Operations`, `Write Operations`), resource, or feature — always within one file per pair.
+- **Different pairs = different files**: `ServiceA / BackendAPI` and `ServiceA / AuthAPI` are two contracts and correctly use two separate files. This rule only forbids splitting ONE pair.
+- **`singleFork: true` is not a fix for this**: It ensures correct pact JSON write semantics across files, but when two files share a pair it actually guarantees the FFI collision (both land in the same process). Without it you'd get file-write races instead. Neither is safe. The fix is one file per pair.
+- **Naming convention**: `{domain}.pacttest.ts` when one domain maps to one pair. `{consumer-kebab}-{provider-kebab}.pacttest.ts` when the filename must be self-describing about which pair it covers.
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal **and sets `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`** (`fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks + `singleFork: true` is required for pact JSON write safety across files — see Example 2 Key Points for mechanism and evidence)
+- [ ] Each consumer+provider pair is covered by exactly ONE `.pacttest.ts` file — never split interactions for the same pair across multiple files (two `PactV4` instances for the same pair in one process cause FFI handle collision → "request was expected but not received" on Linux CI; `singleFork: true` does NOT prevent this — it ensures both files share one process, which guarantees the collision; see Example 10)
+- [ ] `vitest.config.pact.ts` does NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, or `isolate: false` — all four defeat the serialization the rule relies on
+- [ ] `scripts/publish-pact.sh` normalizes interactions with `jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)'` before the `pact-broker publish` call (ensures byte-stable payload to PactFlow regardless of generator ordering)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step (1) generates pact files (calls `npm run test:pact:consumer`) — its own visible step, not folded into publish
+- [ ] CI steps are 1:1 with developer commands — every CI step calls `npm run <same-name>` a dev would run locally (no direct `vitest` or `pact-broker` invocation)
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.github/actions/detect-breaking-change/action.yml` exists
+- [ ] Consumer tests use `.pacttest.ts` extension
+- [ ] Consumer tests use PactV4 `addInteraction()` builder
+- [ ] `uponReceiving()` names follow `"a request to <action> <resource> [<condition>]"` pattern and are unique within the consumer-provider pair
+- [ ] Interaction callbacks use `setJsonContent` for query/header/body and `setJsonBody` for body-only responses
+- [ ] Request bodies use exact values (no `like()` wrapper) — Postel's Law: be strict in what you send
+- [ ] `like()`, `eachLike()`, `string()`, `integer()` matchers are only used in `willRespondWith` (responses), not in `withRequest` (requests) — matchers check type/shape, not exact values
+- [ ] Consumer tests call REAL consumer code (actual API client functions), NOT raw `fetch()`
+- [ ] Consumer code exposes URL injection mechanism (`setApiUrl()`, env var, or constructor param)
+- [ ] Local consumer-helpers shim present if pactjs-utils not installed
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, **one-interaction-per-`it()` rule**
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns; consumer and provider BOTH require `pool: 'forks'` + `singleFork: true` — same FFI-safety rule applies on both sides
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth pattern (dedicated user, classic PAT, PactFlow secret) and staleness monitoring
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage