# 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`, and the generated auth/runtime/deploy
artifacts named by the companion prompt contracts.

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

**Authoritative for:**

- Agent generation workflow and reading order
- Parent-versus-specialist orchestration ownership
- Approved stack versions and dependency pinning policy
- 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)
- Runtime/deploy artifact classification and preservation rules

### `docs/completion-contract.md`

**Operational definition of done for generation runs:**

- prioritized success tiers
- failure modes and recovery procedures
- reviewer signoff requirement
- runtime/deploy readiness requirements

---

## 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)

These are end-state outputs. A repo-wide full regeneration may begin with some or all Tier 3 artifacts absent and then recreate them from Tier 1 inputs plus official CLI scaffolding.

| 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  |
| `docker-compose.yml`             | `prompts/runtime-rules.md`                       |
| `server/Dockerfile`              | `prompts/runtime-rules.md`                       |
| `client/Dockerfile`              | `prompts/runtime-rules.md`                       |
| `client/nginx/default.conf`      | `prompts/runtime-rules.md`                       |
| `server/.env.example`            | `prompts/runtime-rules.md`                       |
| `client/.env.example`            | `prompts/runtime-rules.md`                       |
| `server/docker-entrypoint.sh`    | `prompts/runtime-rules.md`                       |
| `db-seed/Dockerfile`             | `prompts/runtime-rules.md`                       |
| `db-seed/import.sh`              | `prompts/runtime-rules.md`                       |
| `server/src/auth/`               | `prompts/auth-rules.md`                          |
| `client/src/auth/`               | `prompts/auth-rules.md`                          |
| `client/src/dataProvider.ts`     | `prompts/auth-rules.md`                          |
| `toir-realm.json`                | `prompts/auth-rules.md`                          |

To change DSL-driven domain artifacts: update `domain/*.api.dsl` and regenerate.
To change auth/runtime/deploy artifacts: update the governing prompt contracts and regenerate or repair them through the orchestrator.

Ownership rule for Tier 3:

- parent owns shared scaffold, auth platform skeleton, deploy/runtime skeleton, env conventions, integration, and validation
- `generator_prisma` owns `server/prisma/schema.prisma`
- `generator_nest_resources` owns `server/src/modules/**` plus delegated backend registration touchpoints
- `generator_react_admin_resources` owns `client/src/resources/**` plus delegated frontend registration touchpoints
- `generator_data_access` owns `client/src/dataProvider.ts` and any parent-delegated narrow frontend integration seam
- specialized generators must not redesign shared auth/runtime/platform seams outside their delegated zones

Contract freeze rule:

- before specialized generation, the parent must freeze a structured handoff covering entities, fields, types, ids/composite keys, relations, enums, endpoint/path conventions, naming rules, auth surface expectations, validator/eval constraints, and allowed write-zones per generator
- this handoff is an orchestration protocol, not a replacement for the DSL

---

## Tier 4: Framework-managed support

- Prisma migrations under `server/prisma/migrations/` when created by the official Prisma CLI
- Framework config: `nest-cli.json`, `tsconfig*.json`, `vite.config.*`, etc.
- All `prompts/*.md`, `AGENTS.md`, `domain/dsl-spec.md`, `domain/*.api.dsl`

Runtime/deploy policy:

- Tier 3 runtime/deploy outputs are first-class generation targets and should be regenerated or repaired from the companion rules when they drift.
- Tier 4 support files are framework-managed rather than hand-authored sources of truth.

---

## Validation gate

### Stage 1 — Structural gate

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

Verifies scaffold/build readiness, required runtime/deploy artifacts, auth/runtime seams,
realm structure, and other stable repository invariants.
This gate validates the post-generation state, not the clean-slate starting state for a full regeneration run.

### Stage 2 — Eval harness

```
npm run eval:generation
```

Fixture-based semantic checks from `tools/eval/fixtures/` for DSL fidelity, CRUD behavior,
natural-key handling, and UI invariants.

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