froid-plane-test-architecture-enterprise 1.23.4

package/src/workflows/testarch/froid-testarch-trace/resources/knowledge/pact-mcp.md

@@ -0,0 +1,242 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = global)
+claude mcp add-json -s user smartbear \
+  '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "<your-api-token>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## When the Tools Are Not Reachable
+
+`tea_pact_mcp` defaults to `"mcp"`, so every contract-testing step reaches this fragment on a normal install. Most installs have no broker. That is expected, and it must cost nothing.
+
+### The probe is a tool-list check, never a broker call
+
+Reachability means **the SmartBear MCP tools are present in this session's tool list**. Nothing else. Do not call `Can I Deploy`, `Matrix`, or any other tool to discover whether the broker answers: a missing server is instant and free to detect, while a misconfigured or unreachable broker is a network round trip that can hang the step. The two failure modes have very different costs and only the free one is worth probing for.
+
+Credentials are likewise not probed. `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` being unset is a reason the first real tool call will fail, not a reason to make one.
+
+### Probe once per run
+
+Record the result in run state as `pact_mcp_reachable` the first time any step needs it, and have every later step read that value instead of probing again. A run that touches test design, generation, and review must not ask three times, and "probe once" is only true if the answer is stored.
+
+### Fallback order, in this order
+
+1. **Provider source.** Route handlers, types, DTOs, validation schemas. Most authoritative.
+2. **An OpenAPI or Swagger spec** (`openapi.yaml`, `openapi.json`, `swagger.json`) when provider source is not readable.
+3. **Neither available:** apply `confidence-gate.md`. Stop and ask. Do not invent a provider state, a status code, or a response shape.
+
+There is no fourth branch, and inference is not one of the three.
+
+### What the output must say
+
+State it once per run, in the workflow summary, in this form:
+
+`Pact broker: unreachable (SmartBear MCP tools not available). Provider states derived from <provider source | OpenAPI spec>.`
+
+Then continue. Specifically:
+
+- **Never block a workflow** on the broker. A missing broker is not a HALT condition.
+- **Never retry.** One probe, one answer, no loop and no backoff.
+- **Never present inferred data as broker data.** A provider state read from a handler is provider-sourced; saying or implying it came from the broker misrepresents its authority, and a contract built on that is worse than one built on an acknowledged guess.
+- **`tea_pact_mcp: "none"`** skips the probe entirely. Treat it as "unreachable" without the check and without the report line: the user already said not to look.
+
+Everything above applies to the tools in this fragment only. It has no bearing on whether a Pact suite belongs in the project at all — that is the relevance gate in `pactjs-utils-mandate.md`.
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth pattern and staleness monitoring; `Metrics - All` / `Matrix` MCP tools are useful here for dashboards
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_

package/src/workflows/testarch/froid-testarch-trace/resources/knowledge/pactjs-utils-consumer-helpers.md

@@ -0,0 +1,379 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+### Example 6: One `addInteraction()` per `it()` Block (PactV4 Determinism Rule)
+
+**Context**: PactV4's `pact.addInteraction()` feeds the Rust FFI layer that writes interactions to the pact JSON. Chaining multiple `.addInteraction()...executeTest()` blocks inside a single `it()` — or otherwise registering multiple interactions before a single `executeTest` — causes the FFI to **non-deterministically drop whole interactions** (not individual fields) in roughly 1 out of N runs. The pattern passes locally, then fails intermittently in CI or at publish time with `Cannot change pact content for already published pact` once the dropped interaction reappears on a re-run.
+
+**Rule**: Exactly one `pact.addInteraction()` per `it()` block. For N interactions, write N `it()` blocks, or use `it.each(...)`.
+
+```typescript
+// ❌ WRONG — two addInteraction() inside one it() — FFI non-deterministically drops one
+it('handles movie lookup scenarios', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+
+  // Sometimes this second interaction never makes it to the pact JSON:
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — one addInteraction() per it()
+it('gets a movie by id', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+it('returns empty list when no movies exist', async () => {
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — parameterized via it.each for data-driven coverage
+it.each([
+  { id: 1, name: 'The Matrix' },
+  { id: 2, name: 'Inception' },
+])('gets movie $id', async ({ id, name }) => {
+  await pact
+    .addInteraction()
+    .given('movie exists', { id, name })
+    .uponReceiving(`a request to get movie ${id}`)
+    .withRequest('GET', `/movies/${id}`)
+    .willRespondWith(200, setJsonBody({ id: integer(id), name: string(name) }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+```
+
+**Key Points**:
+
+- **This rule stacks with two MANDATORY vitest settings and one file-organization rule. All four address different failure modes; none substitutes for the others**: (1) `fileParallelism: false` — prevents parallel workers racing on the shared pact JSON file; (2) `pool: 'forks'` with `singleFork: true` — required for pact JSON write safety across multiple files; (3) **one `.pacttest.ts` per consumer+provider pair** — `singleFork: true` keeps all files in one process, so two files for the same pair produce an FFI handle collision ("request was expected but not received" on Linux CI, sporadic); (4) one-interaction-per-`it()` (this rule) — prevents the FFI from dropping interactions within a single test body. See `pact-consumer-framework-setup.md` Example 10 for the file-organization ✅/❌ pattern.
+- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; PactFlow rejects a republish with `Cannot change pact content`.
+- The rule applies to both HTTP consumer pacts (`PactV4`) and message consumer pacts (`MessageConsumerPact`).
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **Message pacts**: Works identically with `MessageConsumerPact` — same `.given()` API
+- **Builder reuse**: `setJsonContent` works for both `.withRequest(...)` and `.willRespondWith(...)` callbacks (query is ignored on response builders)
+- **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
+- **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
+- **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
+- **One `addInteraction()` per `it()` block (MANDATORY for PactV4)**: Multiple interactions inside one `it()` cause the Rust FFI to non-deterministically drop interactions. Use one `it()` per interaction or `it.each(...)` for parameterized cases. See Example 6.
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation; same `pool: 'forks'` + `singleFork: true` rule as consumer
+- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config and CI wiring
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+### Wrong: Multiple `addInteraction()` in a single `it()`
+
+```typescript
+// ❌ PactV4 FFI non-deterministically drops one of these interactions ~1/N runs
+it('handles both success and empty list', async () => {
+  await pact.addInteraction().uponReceiving('get movie').withRequest(/* ... */).executeTest(/* ... */);
+  await pact.addInteraction().uponReceiving('empty list').withRequest(/* ... */).executeTest(/* ... */);
+});
+```
+
+### Right: One `addInteraction()` per `it()` (or use `it.each`)
+
+```typescript
+// ✅ Deterministic pact JSON — FFI receives one interaction per test
+it('gets a movie', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+it('returns empty list', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+```
+
+See Example 6 above for the full rationale.
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_