toir-light/prompts/prisma-rules.md

Prisma Rules

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:

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