# Source-of-Truth Hierarchy

This document is the authoritative reference for which files own which decisions.

---

## Tier 1: Authoritative sources (hand-authored; never generated)

### `domain/*.api.dsl`

**Single source of truth for the entire domain and API contract:**

- Entity names and structure
- Attribute names, scalar types, descriptions
- Primary keys (including natural string keys)
- Foreign keys and relations
- Enum definitions and their values
- Database-level constraints: `is required`, `is unique`, `default`
- DTO shapes per operation (Create, Update, Read, ListRequest, ListResponse)
- Which fields appear in each DTO and with what TypeScript modifier (`!` or `?`)
- HTTP method and path for each endpoint (via `label "METHOD /path"`)
- Endpoint names (camelCase identifiers)
- Pagination request/response contract

**Drives:** `server/prisma/schema.prisma`, `server/src/modules/`, `client/src/resources/`,
`server/src/app.module.ts`, `client/src/App.tsx`.

### `prompts/*.md` and `AGENTS.md`

**Authoritative for:**

- Agent generation workflow and reading order
- Auth seam patterns (Keycloak, JWT, PKCE S256, JWKS resolution chain)
- Runtime conventions (env examples, docker-compose topology)
- Framework scaffold baseline requirements (NestJS CLI, Vite React TypeScript)
- Filtering and sorting contract
- Naming conventions and implicit rules (pluralization, sort field priority, type mappings)
- Mutation boundaries (what agents must not overwrite)

---

## Tier 2: Deterministic derivatives (never edit manually)

| File              | Generated from     | Command                        |
| ----------------- | ------------------ | ------------------------------ |
| `api-summary.json` | `domain/*.api.dsl` | `npm run generate:api-summary` |

These files are regenerated from their sources. Manual edits are overwritten on the
next generation run.

---

## Tier 3: LLM-generated artifacts (never edit manually after generation)

| Zone                             | Generated from                                   |
| -------------------------------- | ------------------------------------------------ |
| `server/prisma/schema.prisma`    | `domain/*.api.dsl` + `prompts/prisma-rules.md`   |
| `server/src/modules/<entity>/`   | `domain/*.api.dsl` + `prompts/backend-rules.md`  |
| `client/src/resources/<entity>/` | `domain/*.api.dsl` + `prompts/frontend-rules.md` |
| `server/src/app.module.ts`       | Module list derived from api.dsl `api` blocks    |
| `client/src/App.tsx`             | Resource list derived from api.dsl `api` blocks  |

To change these files: update `domain/*.api.dsl` and regenerate.

---

## Tier 4: Handwritten (not generated; not derived)

- Auth seams: `client/src/auth/`, `server/src/auth/`
- `toir-realm.json`
- `docker-compose.yml`
- `server/.env.example`, `client/.env.example`
- Framework config: `nest-cli.json`, `tsconfig*.json`, `vite.config.*`, etc.
- All `prompts/*.md`, `AGENTS.md`, `domain/dsl-spec.md`, `domain/*.api.dsl`

---

## Validation gate

### Stage 1 — Structural gate

```
node tools/validate-generation.mjs --artifacts-only
```

Verifies that generated artifacts satisfy the contracts declared in Tier 1 sources.

### Stage 2 — Eval harness

```
npm run eval:generation
```

Fixture-based semantic checks from `tools/eval/fixtures/`.

Both stages must pass before any generation task is considered complete.