# Prisma Rules

<!-- prompt-version: 2.0 -->
<!-- applies-to: server/prisma/schema.prisma -->
<!-- generated-by: LLM following these rules -->
<!-- source-of-truth: domain/toir.api.dsl -->
<!-- validated-by: tools/validate-generation.mjs §validateBuildChecks -->

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

## Purpose

Generate `server/prisma/schema.prisma` as a faithful reflection of `domain/toir.api.dsl`.

## Mandatory Inputs

- `prompts/general-prompt.md`
- the relevant entity/enum definitions from `domain/toir.api.dsl`
- the existing Prisma header if `server/prisma/schema.prisma` already exists

`api-summary.json` may be used only as an auxiliary validator/inventory artifact. It is not part of the authoritative Prisma source hierarchy.

## Expected Output

- `server/prisma/schema.prisma`

Never edit the schema manually during normal generation. Change the DSL and regenerate instead.

## Source Of Truth

Entity definitions, field types, PKs, FKs, enums, optionality, uniqueness, and defaults come from `domain/toir.api.dsl`.

## Scalar Type Mapping

| DSL type  | Prisma scalar type |
| --------- | ------------------ |
| `uuid`    | `String`           |
| `string`  | `String`           |
| `text`    | `String`           |
| `integer` | `Int`              |
| `number`  | `Float`            |
| `decimal` | `Decimal`          |
| `date`    | `DateTime`         |
| `boolean` | `Boolean`          |
| enum name | enum name as-is    |

Unknown DSL types pass through as-is for forward compatibility.

## Primary Key Rules

- a field marked `key primary` becomes `@id`
- if the primary key type is `uuid` or the field name is `id`, use `@id @default(uuid())`
- non-uuid natural keys keep plain `@id`
- every entity must resolve to exactly one primary key

## Optionality And Defaults

- primary keys are required
- fields marked `is required` are required
- all other fields are optional with Prisma `?`
- non-primary unique fields get `@unique`
- `default <value>` maps to Prisma `@default(...)`

## Foreign Key And Relation Rules

For a DSL field declared `key foreign { relates Entity.field }`:

1. emit the FK scalar field first
2. add a relation field named `lowerFirst(relatedEntity)`
3. if that relation name collides, append `Ref`
4. annotate with `@relation(fields: [<fkField>], references: [<referencedField>])`

Inverse array relations:

- add inverse array fields for referencing entities automatically
- pluralization rules:
  - `equipment` stays `equipment`
  - names ending in `s` add `es`
  - all others add `s`
- if the inverse name collides, append `List`

## Enum Rules

- every DSL enum becomes a Prisma enum
- preserve declaration order
- preserve the enum name exactly

## Header Preservation

If `server/prisma/schema.prisma` already contains a `generator client { ... }` block, preserve everything before the first `enum` or `model` keyword.

If no valid header exists, emit:

```prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

## Forbidden Patterns

- do not add fields not declared in the DSL
- do not add `@@index`, `@@map`, or schema-level directives not declared by the DSL
- do not add `@db.*` modifiers
- do not change the datasource provider away from `postgresql`

## Completion Expectations

Prisma generation is incomplete if any of the following is true:

- `server/prisma/schema.prisma` does not exist
- the schema no longer reflects the DSL
- required relation fields or inverse arrays are missing
- header generation or preservation breaks Prisma baseline behavior