@c0x12c/ai-toolkit 1.15.0

package/rules/core/TIMEZONE.md

@@ -0,0 +1,316 @@
+# Timezone Rules
+
+## One Rule: Everything is UTC
+
+**Server stores UTC. API sends UTC. API receives UTC. No exceptions.**
+
+The frontend is the only place that converts to/from local time — for display only.
+
+```
+Database (TIMESTAMPTZ/UTC) → Backend (Instant/UTC) → API JSON (ISO 8601 Z) → Frontend (UTC) → Display (local)
+                                                                              ← Send (local → UTC) ←  Input
+```
+
+---
+
+## Database
+
+### Use `TIMESTAMPTZ` — Not `TIMESTAMP`
+
+**Always use `TIMESTAMPTZ` (with timezone).** PostgreSQL docs and wiki both say this.
+
+Why: `TIMESTAMPTZ` converts to UTC on insert and converts back on read. If a connection has a non-UTC session timezone (DBA tools, connection pool quirks, migration scripts), `TIMESTAMPTZ` still stores the correct UTC value. `TIMESTAMP` without timezone silently stores whatever you give it — if the session isn't UTC, you get wrong data and can't tell.
+
+```sql
+-- CORRECT — TIMESTAMPTZ is the safe default
+CREATE TABLE events (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  starts_at TIMESTAMPTZ NOT NULL,
+  ends_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ,
+  deleted_at TIMESTAMPTZ
+);
+
+-- WRONG — TIMESTAMP without timezone is fragile
+CREATE TABLE events (
+  id UUID PRIMARY KEY,
+  starts_at TIMESTAMP NOT NULL,  -- Breaks if session timezone isn't UTC
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+Both types use 8 bytes internally. No storage difference.
+
+### Server Must Run in UTC
+
+The database server, application server, and all containers must run in UTC:
+
+```yaml
+# application.yml
+datasources:
+  default:
+    connection-properties:
+      timezone: UTC
+```
+
+```sql
+-- PostgreSQL: verify
+SHOW timezone;  -- Should return 'UTC'
+```
+
+```dockerfile
+# Dockerfile
+ENV TZ=UTC
+```
+
+```yaml
+# Kubernetes pod spec
+env:
+  - name: TZ
+    value: "UTC"
+```
+
+---
+
+## Backend (Kotlin)
+
+### Always Use `Instant` — Never `LocalDateTime`
+
+`Instant` is UTC by definition. `LocalDateTime` has no timezone info and causes bugs.
+
+```kotlin
+// CORRECT — Instant is always UTC
+val now: Instant = Instant.now()
+val expiresAt: Instant = Instant.now().plusSeconds(3600)
+
+// WRONG — LocalDateTime has no timezone, ambiguous
+val now: LocalDateTime = LocalDateTime.now()  // What timezone? Nobody knows.
+```
+
+### `ZonedDateTime` — Only at Computation Boundaries
+
+Never put `ZonedDateTime` in entities, DTOs, or API payloads. It's OK for:
+- Scheduling logic (computing "next 9 AM in user's timezone")
+- DST-aware date arithmetic ("add 1 day" at DST boundary)
+- Generating reports in a specific timezone
+
+Always convert back to `Instant` before passing to other layers.
+
+```kotlin
+// CORRECT — entities and DTOs use Instant
+data class UserEntity(
+  val createdAt: Instant,
+  val lastLoginAt: Instant?,
+  val subscriptionExpiresAt: Instant?
+)
+
+// CORRECT — ZonedDateTime only for scheduling computation
+fun nextNotificationTime(userTimezone: String, localTime: LocalTime): Instant {
+  val zone = ZoneId.of(userTimezone)
+  val nextLocal = ZonedDateTime.now(zone).with(localTime)
+  return nextLocal.toInstant()  // Convert back to Instant
+}
+
+// WRONG — ZonedDateTime in entity
+data class UserEntity(
+  val createdAt: ZonedDateTime  // NO — keep entities in Instant
+)
+```
+
+### Jackson Serialization
+
+Jackson must serialize `Instant` as ISO 8601 with the `Z` suffix:
+
+```kotlin
+objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
+// Output: "2024-01-15T10:30:00Z"
+```
+
+Never output offsets like `+07:00` or timezone names in API responses.
+
+---
+
+## API Contract
+
+### All Datetime Fields Are ISO 8601 UTC
+
+```json
+{
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T14:22:33Z",
+  "expires_at": "2024-02-15T00:00:00Z"
+}
+```
+
+### Request Bodies — Frontend Sends UTC
+
+```json
+{
+  "starts_at": "2024-01-20T09:00:00Z",
+  "ends_at": "2024-01-20T17:00:00Z"
+}
+```
+
+### Query Parameters — Also UTC
+
+```
+GET /events?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z
+```
+
+### No Timezone Fields in Timestamp Payloads
+
+Don't put timezone info alongside timestamps. The exception is user preferences (see below).
+
+```json
+// WRONG — timezone alongside a timestamp
+{ "starts_at": "2024-01-20T09:00:00Z", "timezone": "America/New_York" }
+
+// CORRECT — just UTC
+{ "starts_at": "2024-01-20T09:00:00Z" }
+```
+
+---
+
+## Frontend
+
+### Receive UTC, Convert for Display
+
+```typescript
+// Convert at display time
+function formatDate(utcString: string): string {
+  return new Intl.DateTimeFormat(undefined, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  }).format(new Date(utcString))
+}
+```
+
+### Send UTC to Server
+
+```typescript
+// Convert local input to UTC before API call
+const localDate = new Date(userInput)
+const utcString = localDate.toISOString()  // "2024-01-20T02:00:00.000Z"
+
+await api.post('/events', { startsAt: utcString })
+
+// WRONG — no Z suffix, ambiguous
+await api.post('/events', { startsAt: '2024-01-20T09:00:00' })
+```
+
+### Use Browser Timezone at Render Time
+
+Don't track the user's timezone in frontend state. The browser already knows it.
+
+```typescript
+// CORRECT — use at render time
+const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone
+
+// WRONG — storing timezone in state
+const [timezone, setTimezone] = useState('America/New_York')
+```
+
+---
+
+## When You DO Need Timezone
+
+There are cases where storing a user's IANA timezone is correct. The rule is:
+
+**Past events (created_at, login_at, order_placed_at):** Never store timezone. `TIMESTAMPTZ` (UTC) is enough.
+
+**User preferences (notification time, business hours):** Store the user's IANA timezone as a separate column. Don't mix it with timestamps.
+
+```sql
+-- CORRECT — timezone as a user preference, not part of timestamps
+CREATE TABLE user_preferences (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id UUID NOT NULL,
+  timezone TEXT NOT NULL DEFAULT 'UTC',          -- IANA timezone: 'America/New_York'
+  notification_time TEXT NOT NULL DEFAULT '09:00', -- local time, not a timestamp
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Then compute UTC fire time dynamically in code:
+-- nextFire = ZonedDateTime.of(today, LocalTime.parse("09:00"), ZoneId.of("America/New_York")).toInstant()
+```
+
+**Why dynamic computation?** Because DST shifts change the UTC offset. "9 AM New York" is `14:00 UTC` in winter but `13:00 UTC` in summer. Storing a fixed UTC value would drift by an hour.
+
+**Never use fixed offsets as timezone identifiers.** `+05:30` is an offset, not a timezone. It changes with DST. Use IANA names: `Asia/Kolkata`, `America/New_York`.
+
+---
+
+## Microservices
+
+### Inter-Service Communication
+
+All service-to-service datetime fields use ISO 8601 UTC, same as external APIs.
+
+### Event Streaming (Kafka, RabbitMQ)
+
+- Use epoch-based types: Avro `timestamp-millis`, Protobuf `google.protobuf.Timestamp`
+- These are UTC by definition — no timezone ambiguity
+- Document in your schema that all timestamps are UTC epoch
+
+### Logging
+
+All services must log in UTC. If services in different timezones log in local time, correlating logs across services is a nightmare.
+
+```xml
+<!-- logback.xml — force UTC -->
+<timestamp key="timestamp" datePattern="yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" timeReference="UTC"/>
+```
+
+### Distributed Tracing
+
+OpenTelemetry spans use nanosecond UTC timestamps internally. No action needed — but make sure NTP is configured on all nodes. Clock skew (not timezone) is the bigger concern.
+
+### Cron / Scheduler Jobs
+
+Cron expressions are timezone-sensitive. DST transitions can cause jobs to fire twice, or not at all, in the 1-3 AM window.
+
+```kotlin
+// CORRECT — schedule in UTC to avoid DST issues
+@Scheduled(cron = "0 0 14 * * *", zone = "UTC")  // 2 PM UTC, not "2 PM local"
+fun dailyDigest() { ... }
+
+// If the job MUST fire at local wall-clock time, use IANA timezone explicitly:
+@Scheduled(cron = "0 0 9 * * *", zone = "America/New_York")  // 9 AM New York, DST-aware
+fun morningNotification() { ... }
+```
+
+Avoid scheduling jobs in the 1:00-3:00 AM local time window for any timezone with DST.
+
+### IANA Timezone Database Updates
+
+Governments change DST rules. Your JVM and OS timezone databases need updating. If you run long-lived JVMs, update the JDK or use the TZUpdater tool.
+
+---
+
+## Quick Reference
+
+| Layer | Type | Format | Example |
+|-------|------|--------|---------|
+| Database | Column type | `TIMESTAMPTZ` | `2024-01-15 10:30:00+00` |
+| Backend (Kotlin) | Property type | `Instant` | `Instant.now()` |
+| API JSON | String | ISO 8601 + Z | `"2024-01-15T10:30:00Z"` |
+| Frontend (receive) | Parse | `new Date(utcString)` | `new Date("2024-01-15T10:30:00Z")` |
+| Frontend (display) | Format | `Intl.DateTimeFormat` | `"Jan 15, 2024, 5:30 PM"` |
+| Frontend (send) | Serialize | `toISOString()` | `"2024-01-15T10:30:00.000Z"` |
+| Events (Kafka) | Type | epoch millis | `1705312200000` |
+| Cron jobs | Zone | IANA or UTC | `zone = "UTC"` |
+| User preference | Column | IANA timezone | `America/New_York` |
+
+## What NOT to Do
+
+- Don't use `TIMESTAMP` without timezone — use `TIMESTAMPTZ`
+- Don't use `LocalDateTime` in Kotlin — use `Instant`
+- Don't put `ZonedDateTime` in entities or DTOs
+- Don't use fixed offsets (`+05:30`) as timezone identifiers — use IANA names
+- Don't store timezone alongside timestamps for past events
+- Don't convert to local time on the backend — that's the frontend's job
+- Don't format dates on the server for display — return UTC, let the client format
+- Don't schedule cron jobs in the 1-3 AM DST window
+- Don't assume the host timezone is UTC — set `TZ=UTC` in containers
+- Don't log in local time — all services log UTC

package/rules/database/ORM_AND_REPO.md

@@ -0,0 +1,289 @@
+# Exposed ORM and Repository Patterns
+
+> Full guide: use /database-patterns skill
+
+## Exposed ORM Patterns (CRITICAL)
+
+### Only `id` Uses `.value` — All Other UUID Columns Do NOT
+
+`UUIDTable.id` returns `EntityID<UUID>` which needs `.value` to get the raw `UUID`.
+All other `uuid()` columns return `UUID` directly — using `.value` on them causes compilation errors.
+
+```kotlin
+// CORRECT
+fun toEntity(row: ResultRow) = MyEntity(
+  id = row[MyTable.id].value,          // id -> EntityID<UUID> -> needs .value
+  projectId = row[MyTable.projectId],  // uuid() column -> UUID directly
+  userId = row[MyTable.userId],        // uuid() column -> UUID directly
+  name = row[MyTable.name],            // text() column -> String directly
+)
+
+// WRONG — causes "Unresolved reference 'value'"
+fun toEntity(row: ResultRow) = MyEntity(
+  id = row[MyTable.id].value,
+  projectId = row[MyTable.projectId].value,  // WRONG! uuid() returns UUID, not EntityID
+  userId = row[MyTable.userId].value,        // WRONG!
+)
+```
+
+**Rule**: In `toEntity()` / `convert()` methods, ONLY `row[Table.id].value` gets `.value`. Every other column maps directly without `.value`.
+
+### SoftDeleteTable Base Class
+
+All tables extend `SoftDeleteTable` which gives these columns automatically:
+- `id` (from UUIDTable) — `EntityID<UUID>`
+- `createdAt` — `Instant`
+- `updatedAt` — `Instant?`
+- `deletedAt` — `Instant?`
+
+**Do NOT re-declare these columns in table definitions.**
+
+```kotlin
+// CORRECT
+object MyTable : SoftDeleteTable("my_table") {
+  val projectId = uuid("project_id")
+  val name = text("name")
+  // createdAt, updatedAt, deletedAt are inherited
+}
+
+// WRONG — re-declares inherited columns
+object MyTable : SoftDeleteTable("my_table") {
+  val projectId = uuid("project_id")
+  val name = text("name")
+  val createdAt = timestamp("created_at")  // Already in SoftDeleteTable!
+}
+```
+
+### Entity Must Include All SoftDeleteTable Fields
+
+Entity data classes MUST implement `Entity<Instant>` and include all fields from `SoftDeleteTable`:
+
+```kotlin
+data class MyEntity(
+  override val id: UUID = UUID.randomUUID(),
+  val projectId: UUID,
+  val name: String,
+  // ... domain fields ...
+  override val createdAt: Instant = Instant.now(),
+  override val updatedAt: Instant? = null,
+  override val deletedAt: Instant? = null
+) : Entity<Instant>
+```
+
+### toEntity() Must Map ALL Fields
+
+When writing `toEntity()` / `convert()`, map EVERY column including SoftDeleteTable fields:
+
+```kotlin
+private fun toEntity(row: ResultRow) = MyEntity(
+  id = row[MyTable.id].value,           // .value ONLY for id
+  projectId = row[MyTable.projectId],   // NO .value
+  name = row[MyTable.name],
+  createdAt = row[MyTable.createdAt],
+  updatedAt = row[MyTable.updatedAt],
+  deletedAt = row[MyTable.deletedAt]
+)
+```
+
+### Always Filter by `deletedAt.isNull()` for Soft Delete
+
+Every SELECT query on a SoftDeleteTable MUST filter out soft-deleted records:
+
+```kotlin
+// CORRECT
+fun byId(id: UUID): MyEntity? {
+  return transaction(db.replica) {
+    MyTable.selectAll()
+      .where { MyTable.id eq id and MyTable.deletedAt.isNull() }
+      .singleOrNull()
+      ?.let { toEntity(it) }
+  }
+}
+
+// WRONG — returns soft-deleted records
+fun byId(id: UUID): MyEntity? {
+  return transaction(db.replica) {
+    MyTable.selectAll()
+      .where { MyTable.id eq id }  // Missing deletedAt.isNull()!
+      .singleOrNull()
+      ?.let { toEntity(it) }
+  }
+}
+```
+
+### orderBy Uses `SortOrder.DESC` / `SortOrder.ASC`
+
+```kotlin
+import org.jetbrains.exposed.sql.SortOrder
+
+// CORRECT
+.orderBy(MyTable.createdAt, SortOrder.DESC)
+
+// WRONG — causes compilation error
+.orderBy(MyTable.createdAt to false)
+```
+
+### Chaining WHERE Conditions
+
+Calling `.where {}` twice **replaces** the first condition. Use `.andWhere {}` to add conditions:
+
+```kotlin
+// CORRECT — andWhere adds to existing condition
+MyTable.selectAll()
+  .where { MyTable.deletedAt.isNull() }
+  .andWhere { MyTable.status eq "active" }
+
+// WRONG — second where replaces the deletedAt filter!
+MyTable.selectAll()
+  .where { MyTable.deletedAt.isNull() }
+  .where { MyTable.status eq "active" }  // REPLACES the first where!
+```
+
+### Transaction Usage
+
+- **Reads**: `transaction(db.replica) { ... }`
+- **Writes**: `transaction(db.primary) { ... }`
+
+### insert() Must Include ALL Required Entity Fields
+
+When inserting, map EVERY field from the entity to the table columns, including `deletedAt`:
+
+```kotlin
+fun insert(entity: MyEntity): MyEntity {
+  return transaction(db.primary) {
+    MyTable.insert {
+      it[id] = entity.id
+      it[projectId] = entity.projectId
+      it[name] = entity.name
+      // ... all domain fields ...
+      it[createdAt] = entity.createdAt
+      it[updatedAt] = entity.updatedAt
+      it[deletedAt] = entity.deletedAt
+    }
+    entity
+  }
+}
+```
+
+### Field Names Must Match Entity/Table Exactly
+
+When writing repositories, ALWAYS cross-reference the Table and Entity files:
+- Table file: `module-repository/.../table/MyTable.kt` — defines column names
+- Entity file: `module-repository/.../entity/MyEntity.kt` — defines property names
+
+**Common mistakes to avoid:**
+- Using field names from a different service (e.g., `triggeredBy` when the table uses `deployedBy`)
+- Guessing field names instead of reading the actual Table/Entity definitions
+- Missing fields that exist in the Entity but weren't mapped in insert/toEntity
+
+### Ktlint Rules for DB Code
+
+- **Always use braces for if/else** — Ktlint enforces braces on all `if`/`else` blocks, including single-expression ones:
+
+```kotlin
+// CORRECT
+val result = if (condition) {
+  valueA
+} else {
+  valueB
+}
+
+// WRONG — ktlint error: "Missing { ... }"
+val result = if (condition) {
+  valueA
+} else valueB
+```
+
+- **Data classes must have at least one parameter** — If a request/DTO truly has no fields, use a regular class or add an optional field:
+
+```kotlin
+// CORRECT
+data class StartRequest(
+  val notes: String? = null
+)
+
+// WRONG — compilation error
+data class StartRequest(
+  // empty body
+)
+```
+
+---
+
+## Repository Pattern
+
+### Creating a Repository
+You MUST create a repository for each table with:
+
+1. **Interface Definition**
+   - Define all CRUD operations needed
+   - Use domain-specific method names (e.g., `byEmail`, `byToken`)
+   - Return entities, not raw database rows
+   - Support soft delete operations
+
+2. **Implementation Class**
+   - Name: `Default{TableName}Repository`
+   - Constructor: Accept `DatabaseContext`
+   - Use transactions: `db.primary` for writes, `db.replica` for reads
+   - Use soft delete (update `deletedAt`) not hard delete
+
+3. **Standard Methods**
+   ```kotlin
+   fun insert(entity: Entity): Entity
+   fun update(id: UUID, ...fields): Entity?
+   fun byId(id: UUID): Entity?
+   fun byIds(ids: List<UUID>): List<Entity>
+   fun deleteById(id: UUID): Entity?  // Soft delete
+   fun restoreById(id: UUID): Entity?  // Restore soft deleted
+   ```
+
+4. **Query Patterns**
+   - Always check `deletedAt.isNull()` for active records
+   - Update `updatedAt` on every modification
+   - Use `convert()` method to transform ResultRow to Entity
+   - Handle empty lists gracefully
+
+### Repository File Structure
+```kotlin
+interface {TableName}Repository {
+    // Method declarations
+}
+
+class Default{TableName}Repository(
+    private val db: DatabaseContext
+) : {TableName}Repository {
+
+    // Method implementations
+
+    private fun convert(row: ResultRow): Entity = Entity(
+        // Map all columns to entity properties
+    )
+}
+```
+
+---
+
+## Testing
+
+> Full guide: use `/testing-strategies` skill
+
+**Key rules:**
+- Extend `AbstractRepositoryTest`. Name: `Default{TableName}RepositoryTest`
+- Required coverage: insert, update, byId (exists/not exists/soft deleted), deleteById, restoreById
+- Use `dummyEntity()` helper with defaults. Use AssertJ assertions.
+- Always run `./gradlew :module-repository:test` after modifying repository code
+- Test edge cases: null optionals, empty lists, non-existent IDs, already-deleted entities
+
+---
+
+## Checklist Before Writing Repository Code
+
+- [ ] Read the Table file to know exact column names and types
+- [ ] Read the Entity file to know exact property names and types
+- [ ] Only `.value` on `id` column, never on other uuid columns
+- [ ] Include `deletedAt.isNull()` in ALL select queries
+- [ ] Use `SortOrder.DESC`/`SortOrder.ASC` for orderBy (import `org.jetbrains.exposed.sql.SortOrder`)
+- [ ] Map ALL fields in `insert()` including `createdAt`, `updatedAt`, `deletedAt`
+- [ ] Map ALL fields in `toEntity()` including `createdAt`, `updatedAt`, `deletedAt`
+- [ ] Use `db.primary` for writes, `db.replica` for reads
+- [ ] Always use braces for if/else blocks (ktlint)