# Database Models

## Factory Function Pattern

Each model is a `createXType<const F>(params)` factory:

- Params interface generic: `F extends Record<string, TailorAnyDBField>`
- `fields?: F` — optional custom fields from parent modules
- Spread as `...(params.fields ?? {}) as F` to preserve type information
- Include `...db.fields.timestamps()`
- Use `.description()` for field docs
- Apply permissions at model level
- Export a default instance with stubs for cross-module types: `export const x = createXType({ unitType: unitStub })`
  - Cross-module type params are **required** — pass stubs from `lib/_db_deps.ts` explicitly
  - Never use `??` fallback to stubs inside the factory function body

## Stateful Model Enums

Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.

```typescript
// Good: extension only
const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];

// Bad: allows replacement
const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
```

- Name parameter `additionalX` to signal extension-only
- Parent modules handle their additional status transitions
