# Validation Rules

<!-- prompt-version: 2.0 -->
<!-- applies-to: tools/validate-generation.mjs and npm run eval:generation -->
<!-- validated-by: self -->

Use this document during the **Verification / Success Gate** stage defined in `prompts/general-prompt.md`.

## Purpose

Define the repository gates that convert a plausible generation run into a verified one.

## Primary Gates

- `node tools/validate-generation.mjs --artifacts-only`
- `npm run eval:generation`

## Auxiliary Freshness Prep

- `npm run generate:api-summary`

Run the freshness prep when the repository validator or supporting tooling expects `api-summary.json` to exist and match the current DSL. This artifact is auxiliary to validation and inventory, not the generation source of truth.

## Prompt-Gate Alignment Rule

- every invariant marked required in the active prompt corpus must either be enforced by a gate or called out as manual/runtime-only
- validation must not silently ignore a forbidden pattern
- build verification must not be reported as green when it was skipped

## Gate Groups

### Build Checks

- at least one `domain/*.api.dsl` file exists
- required artifacts exist:
  - `server/prisma/schema.prisma`
  - env examples
  - required scaffold files
  - auth/runtime/realm artifacts
- if the current validator policy checks `api-summary.json`, it exists and is fresh relative to the DSL
- `server/` remains a valid Nest workspace
- `client/` remains a valid Vite workspace
- if dependencies are installed, backend and frontend build verification runs
- if dependencies are missing, build verification is reported as skipped with reason instead of green

### Auth Checks

- frontend auth seam files exist
- backend auth seam files exist
- `401` and `403` semantics remain split
- auth code keeps the required Keycloak/JWT contracts
- JWKS resolution order remains:
  1. explicit `KEYCLOAK_JWKS_URL`
  2. OIDC discovery
  3. certs fallback

### Filter And UI Checks

- list resources expose filter UI including `FilterButton`
- reference filters use `ReferenceInput` + `AutocompleteInput` with `filterToQuery`
- `dataProvider` preserves repeated query params for array filters
- backend FK filters remain exact-match
- repeated enum params map to Prisma `in`
- Create/Edit forms keep type-correct inputs
- navigable references keep `ReferenceField link="show"`
- resources keep `show={...}` registration in `App.tsx`

### Natural-Key Checks

- response records expose `id`
- route/update contracts use the real primary key
- natural-key sort/update paths do not regress to a fake physical `id`

### Realm Checks

- a root `*-realm.json` artifact exists
- required roles, audience delivery, and claims remain explicit
- SPA and backend client structure remains explicit

### Runtime Checks

- Docker topology remains PostgreSQL-only
- Prisma lifecycle commands remain available where required
- `/health` remains public
- backend build runs inside `server/`
- frontend build runs inside `client/`
- client/server `.env.example` stay aligned with repository defaults

### Output Contract Checks

- every generated Create/Update DTO imports from `'class-validator'`
- DTO fields have type-correct decorators
- optional/nullable fields carry `@IsOptional()` before the type decorator
- controllers carry the required guards and roles
- React Admin components use correct input/field types

### Eval Harness

- `npm run eval:generation` runs fixture-based semantic checks
- eval failures block completion
- prompt changes that break evals are regressions, not acceptable simplifications