azcodr 1.3.0 → 1.4.0

package/docs/rules/api_architecture.md

@@ -0,0 +1,179 @@
+# API Architecture, Protocols & Communication Standards
+
+> **Core Mandate:** Enforce standard HTTP semantics, synchronous vs. asynchronous processing (`202 Accepted`), capability metadata (`_actions`), safe mutations via idempotency keys, keyset cursor pagination, optimistic concurrency control (OCC), and RFC 8594 lifecycle versioning.
+
+---
+
+## 1. Standard HTTP Semantics & Status Codes
+
+APIs must adhere strictly to standard HTTP semantics. Never return `200 OK` for error envelopes:
+
+| Status Code | Semantic Purpose | When to Return |
+|---|---|---|
+| **`200 OK`** | Successful read or synchronous update | Standard `GET`, `PATCH`, `PUT` queries that return payloads. |
+| **`201 Created`** | Successful resource creation | Synchronous `POST` with `Location: /api/v1/resources/:id` header. |
+| **`202 Accepted`** | Asynchronous task accepted | Tasks exceeding latency budgets (> 1.5s) delegated to background queues. |
+| **`204 No Content`** | Successful action with zero payload | Standard `DELETE` or empty mutation responses. |
+| **`400 Bad Request`** | Malformed syntax or protocol violation | Unparseable JSON, invalid query parameters. |
+| **`401 Unauthorized`** | Missing or invalid authentication | Missing, expired, or tampered JWT / API token. |
+| **`403 Forbidden`** | Authenticated but insufficient permission | Role, tenant boundary, or policy guard denial. |
+| **`404 Not Found`** | Resource does not exist | Unknown entity identifier (or masked tenant resource). |
+| **`409 Conflict`** | State conflict or race condition | Concurrency mismatch (`If-Match`), unique constraint, or in-flight idempotency. |
+| **`422 Unprocessable`** | Semantic validation failure | Schema constraint violation (RFC 7807 problem details). |
+| **`500 Internal Error`** | Unhandled server exception | Unexpected server failure; never leak internal stack traces. |
+
+### Subresource URL Conventions
+- Express relational hierarchy cleanly: `/api/v1/organizations/:orgId/projects/:projectId/members`.
+- Limit URL nesting to a maximum of 2 subresource levels; for deeper resources, access directly via canonical ID (`/api/v1/tasks/:taskId`).
+
+### Enumeration Masking
+- Authentication and recovery endpoints must never reveal user existence (e.g. return `"If an account exists, a recovery link has been sent"` with identical timing).
+
+---
+
+## 2. Synchronous vs. Asynchronous Processing (`202 Accepted`)
+
+Operations with unpredictable or long execution durations (> 1.5 seconds, such as video rendering, large PDF exports, batch imports, or complex report generation) must never block synchronous HTTP request threads:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client
+    participant Gateway as API Gateway
+    participant Queue as Task Queue / Worker
+    
+    Client->>Gateway: POST /reports/export (Long-running > 1.5s)
+    Gateway->>Queue: Dispatch background job
+    Gateway-->>Client: 202 Accepted (Location: /api/v1/tasks/tsk_123)
+    Note over Client,Gateway: Client polls GET /api/v1/tasks/tsk_123 until complete
+```
+
+### Protocol Standards:
+1. Dispatch the payload to a persistent worker queue (e.g., BullMQ, Temporal, Celery).
+2. Respond immediately with **`202 Accepted`** containing:
+   - Header: `Location: /api/v1/tasks/:taskId`
+   - Envelope:
+     ```json
+     {
+       "taskId": "tsk_123",
+       "status": "QUEUED",
+       "pollIntervalMs": 2000,
+       "_links": {
+         "status": { "href": "/api/v1/tasks/tsk_123", "method": "GET" },
+         "cancel": { "href": "/api/v1/tasks/tsk_123", "method": "DELETE" }
+       }
+     }
+     ```
+3. Polling endpoint (`GET /api/v1/tasks/:taskId`) returns:
+   - In-progress: `200 OK` with status `PROCESSING` and progress percentage.
+   - Finished: `303 See Other` with `Location: /api/v1/reports/rep_789` or `200 OK` with `status: "COMPLETED"` and the final artifact URI.
+
+---
+
+## 3. Allowed Actions & Capability Metadata (`_actions` Envelope)
+
+Clients must not duplicate complex server-side business and authorization rules to decide whether UI actions (edit, delete, approve, cancel, refund) are permitted. **The server is the authoritative source of truth.**
+
+### Pattern: `_actions` and `_links` Envelope
+Every resource response must embed an `_actions` boolean map and optional `_links` hypermedia block indicating what the requesting caller is permitted to do based on their role, tenant boundaries, and the entity's current lifecycle state:
+
+```json
+{
+  "id": "ord_9876",
+  "status": "SHIPPED",
+  "totalAmount": 149.99,
+  "currency": "USD",
+  "_actions": {
+    "canEdit": false,
+    "canCancel": false,
+    "canTrack": true,
+    "canRequestRefund": true
+  },
+  "_links": {
+    "self": { "href": "/api/v1/orders/ord_9876", "method": "GET" },
+    "track": { "href": "/api/v1/orders/ord_9876/tracking", "method": "GET" },
+    "refund": { "href": "/api/v1/orders/ord_9876/refunds", "method": "POST" }
+  }
+}
+```
+
+### Frontend Binding:
+- UI action buttons directly bind visibility or disabled state to `resource._actions.canCancel`.
+- When business logic evolves (e.g. orders over $1,000 require manager approval), only backend policy changes—zero frontend redeployment required.
+
+---
+
+## 4. Safe Mutations via Idempotency Keys (IETF Draft)
+
+To prevent duplicate execution (double charging, duplicate orders) caused by network retries or transient connection drops:
+
+### Protocol Standards:
+- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
+- **Server Execution Lifecycle**:
+  1. Check distributed idempotency cache for key `idemp:<tenantId>:<idempotencyKey>`.
+  2. If found with status `IN_FLIGHT`: return **`409 Conflict`** (`IDEMPOTENT_OPERATION_IN_PROGRESS`).
+  3. If found with status `COMPLETED`: return the cached HTTP status code, headers, and response payload without re-executing.
+  4. If not found: Acquire distributed lock, execute mutation within an atomic database transaction, cache the response envelope with a 24-hour TTL, and release the lock.
+
+---
+
+## 5. High-Scale Keyset / Cursor-Based Pagination
+
+Never use offset pagination (`OFFSET 10000 LIMIT 20`) on large tables. Offsets degrade linearly ($O(N)$) and suffer from page-drift anomalies as rows are inserted or deleted.
+
+### Specification & Envelope:
+- Query Parameters: `?cursor=<opaque_base64>&limit=20` (default limit 20, max 100).
+- Response Envelope:
+  ```json
+  {
+    "data": [...],
+    "pagination": {
+      "nextCursor": "ZXlKaWRI...==",
+      "hasMore": true,
+      "limit": 20
+    }
+  }
+  ```
+- **Agnostic Keyset Query Pattern**:
+  ```sql
+  SELECT * FROM orders
+  WHERE tenant_id = :tenantId
+    AND (created_at, id) < (:cursorCreatedAt, :cursorId)
+  ORDER BY created_at DESC, id DESC
+  LIMIT :limit + 1;
+  ```
+  If `results.length > limit`, slice the extra item and encode its composite values (`created_at`, `id`) into the base64 `nextCursor`.
+
+---
+
+## 6. Optimistic Concurrency Control (OCC)
+
+Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
+
+### Protocol Standards:
+- Every mutable entity contains an incrementing integer `version` column.
+- The server returns the current entity version in the `ETag` response header: `ETag: W/"v4"`.
+- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
+- **Atomic Concurrency Handling**:
+  ```sql
+  UPDATE orders 
+  SET status = :status, version = version + 1 
+  WHERE id = :id AND version = :expectedVersion;
+  ```
+  - If `rows_affected == 0`: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
+
+---
+
+## 7. API Versioning & RFC 8594 Lifecycle Deprecation
+
+### URI Versioning Standard
+- Standardize on explicit path versioning: `/v1/`, `/v2/`.
+- Never introduce breaking changes within an active major version:
+  - *Non-Breaking (Permitted in `/v1/`):* Adding optional fields, adding new endpoints, adding new enum variants.
+  - *Breaking (Demands `/v2/`):* Renaming/removing fields, changing validation constraints, altering status codes.
+
+### RFC 8594 Sunset & Deprecation Headers
+When deprecating an endpoint, provide clients with a minimum 90-day grace period:
+- `Deprecation: @<unix-timestamp>`: Date when the endpoint was deprecated.
+- `Sunset: <HTTP-date>`: Absolute date when the endpoint will return `410 Gone`.
+- `Link: </api/v2/docs>; rel="sunset"`: Link to migration documentation.

package/docs/rules/caching.md

@@ -4,20 +4,37 @@
 
 ---
 
-## 1. Abstract Cache Port & Cache-Aside Pattern
+## 1. The YAGNI Gate: Database First, Caching Second
 
-Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+Caching introduces state duplication, cache invalidation race conditions, and memory overhead. **Caching is never a substitute for missing database indexes or poorly structured SQL queries.**
 
+```mermaid
+flowchart TD
+    subgraph CachingGate["Caching YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Relational queries with composite indexes<br/>• Request-scoped in-memory DataLoader batching to eliminate N+1<br/>• Zero distributed cache infrastructure (no Redis / Memcached)"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Queries that are slow due to missing indexes or sequential scans<br/>• High-write / high-churn entities (write-heavy mutation streams)<br/>• Low-traffic administrative or internal operational queries"]
+        B3["3. The Tipping Point (Graduation)<br/>• Query has been optimized with EXPLAIN ANALYZE, but p99 latency still exceeds SLA (> 100ms)<br/>• Read-to-write asymmetry on the entity exceeds 20:1<br/>• Downstream external API rate limits or third-party egress costs demand response caching"]
+        B1 -->|Forbidden if missing indexes| B2
+        B1 -->|Triggered by high read/write ratio| B3
+    end
 ```
-┌────────────────────────────────────────────────────────┐
-│ Cache Port Interface (Agnostic Contract)               │
-├────────────────────────────────────────────────────────┤
-│ get(key): Optional<String>                             │
-│ set(key, value, ttlSeconds): void                      │
-│ delete(key): void                                      │
-│ deletePattern(pattern): void                           │
-│ acquireLock(lockKey, ttlMs): boolean                   │
-└────────────────────────────────────────────────────────┘
+
+---
+
+## 2. Abstract Cache Port & Cache-Aside Pattern
+
+Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+
+```mermaid
+classDiagram
+    class CachePort {
+        <<interface>>
+        +get(key: string) Optional~string~
+        +set(key: string, value: string, ttlSeconds: number) void
+        +delete(key: string) void
+        +deletePattern(pattern: string) void
+        +acquireLock(lockKey: string, ttlMs: number) boolean
+    }
 ```
 
 ### Cache-Aside Implementation & Stampede Defense
@@ -38,7 +55,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 2. Key Namespacing & Event-Driven Invalidation
+## 3. Key Namespacing & Event-Driven Invalidation
 
 - **Universal Key Hierarchy**: Structure all keys hierarchically:
   `tenant:{tenantId}:{entity}:{entityId}` (e.g. `tenant:123:order:987`)
@@ -46,7 +63,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 3. HTTP Conditional Caching (ETags)
+## 4. HTTP Conditional Caching (ETags)
 
 - Generate strong cryptographic `ETag` hashes (e.g. SHA-256 of representation or resource version) for cacheable `GET` endpoints.
 - Return **`304 Not Modified`** with zero payload body when inbound requests present matching `If-None-Match` headers, preserving bandwidth and client CPU.

package/docs/rules/cloud_native.md

@@ -28,16 +28,14 @@ All application processes and containers must handle graceful termination:
 - Drain active, in-flight connections within a bounded timeout window (e.g. 10 seconds).
 - Gracefully flush telemetry buffers, terminate background workers, and close database/cache connection pools cleanly before exiting with code 0:
 
-```
-┌────────────────────────────────────────────────────────┐
-│ Graceful Shutdown Flow (Universal / Agnostic)          │
-├────────────────────────────────────────────────────────┤
-│ onSignal(SIGTERM | SIGINT):                            │
-│   1. Set health check probe to UNHEALTHY (drain LB)    │
-│   2. Stop server listening for new connections         │
-│   3. Wait for in-flight requests (timeout: 10s)        │
-│   4. Close database and cache connection pools         │
-│   5. Flush OpenTelemetry trace & log buffers           │
-│   6. Terminate process with exit code 0                │
-└────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    subgraph GracefulShutdown["Graceful Shutdown Flow (Universal / Agnostic)"]
+        Sig["onSignal (SIGTERM | SIGINT)"] --> S1["1. Set health check probe to UNHEALTHY (drain LB)"]
+        S1 --> S2["2. Stop server listening for new connections"]
+        S2 --> S3["3. Wait for in-flight requests (timeout: 10s)"]
+        S3 --> S4["4. Close database and cache connection pools"]
+        S4 --> S5["5. Flush OpenTelemetry trace & log buffers"]
+        S5 --> S6["6. Terminate process with exit code 0"]
+    end
 ```

package/docs/rules/cqrs.md

@@ -0,0 +1,203 @@
+# CQRS (Command Query Responsibility Segregation) & YAGNI Defense
+
+> **Core Mandate:** Enforce evolutionary graduation across the CQRS spectrum, protect against premature abstraction (YAGNI), bound CQRS strictly to high-contention subdomains, decouple write aggregates from read projections, and prevent eventual consistency hazards.
+
+---
+
+## 1. The YAGNI Defense: Default Architecture vs. CQRS
+
+CQRS separates the data model used for state mutations (**Commands**) from the data model used for read operations (**Queries**). While powerful, **CQRS is one of the most frequently over-engineered patterns in modern software**. 
+
+```mermaid
+flowchart LR
+    subgraph DefaultModel["Default Single-Model (CRUD) - Start Here"]
+        D1["• 1 Unified Data Schema (ACID)<br/>• Immediate Strong Consistency<br/>• Zero Projection Infrastructure<br/>• Minimal Mental Overhead"]
+    end
+
+    subgraph DistributedCQRS["Distributed CQRS (Level 3) - Graduate on Proof"]
+        C1["• Dual Schemas & Dual Databases<br/>• Eventual Consistency & Lag<br/>• Outbox, Message Bus, CDC Workers<br/>• Projection Versioning & Replays"]
+    end
+
+    DefaultModel -.->|Graduate ONLY on high read-write asymmetry or SLA breaches| DistributedCQRS
+```
+
+### The YAGNI Rule for CQRS
+1. **Default to Single Model / Single Database**: Start every application, microservice, or bounded context with a standard single data model (Hexagonal/DDD) where repositories handle both reads and writes.
+2. **Never Use CQRS as Top-Level System Architecture**: CQRS must never be applied globally across an entire system. It is strictly a bounded-context tactical pattern. Generic subdomains (Auth, Settings, Billing, Organizations) must remain simple transactional CRUD.
+3. **Explicit Graduation Tipping Points**: Do not introduce segregated read databases or asynchronous projections until empirical metrics prove that a unified relational model cannot meet operational constraints:
+   - **Read/Write Asymmetry**: Read volume exceeds writes by > 50:1, and heavy read queries cause lock contention that starves transactional write operations.
+   - **Impedance Mismatch**: Constructing UI views requires joining 10+ relational tables across multiple consistency boundaries, causing query latency to violate SLAs (> 500ms).
+   - **Polyglot Query Topology**: Complex full-text search, spatial filtering, or columnar aggregation fundamentally requires specialized search engines (Elasticsearch, Meilisearch, ClickHouse) that cannot act as the primary write store.
+
+---
+
+## 2. The 4-Tier Evolutionary CQRS Spectrum
+
+Rather than treating CQRS as a binary switch, systems must graduate incrementally across four explicit architectural tiers:
+
+```mermaid
+flowchart TD
+    L0["Level 0: Method CQS (Bertrand Meyer)<br/>Functions either mutate state or return data; zero architectural overhead. Always mandatory."]
+    L1["Level 1: Segregated Handlers in Code (Single DB, Single Schema)<br/>Command Handlers load Aggregates; Query Handlers bypass domain model for flat DTOs."]
+    L2["Level 2: Segregated Read Models / Materialized Views (Single DB)<br/>Read queries query indexed SQL views or JSON cache tables populated synchronously via ACID transactions."]
+    L3["Level 3: Polyglot Persistence & Asynchronous Projections (Multi-Store)<br/>Write DB (Postgres) + Read DB (Elastic/Redis). Synchronized asynchronously via Transactional Outbox + CDC."]
+
+    L0 --> L1 --> L2 --> L3
+```
+
+### Level 0: Method-Level CQS (Command-Query Separation)
+- Mandatory across all codebases (see [`docs/rules/clean_code.md`](./clean_code.md)).
+- Any function that modifies state must return `void` or a `Result<void, DomainError>`. It must never return the mutated entity.
+- Any function that queries state must be pure and cause zero observable side-effects.
+
+### Level 1: Segregated Handlers in Code (Single DB, Single Schema)
+- When domain aggregates become rich with business logic, hydrating deep aggregate graphs (with children, value objects, and invariant checks) simply to render a flat summary list is wasteful.
+- **Commands**: Flow through `CommandHandler` ➔ loads `AggregateRoot` from `Repository` ➔ executes domain methods ➔ commits transaction.
+- **Queries**: Flow through `QueryHandler` ➔ bypasses domain repositories ➔ issues direct projection queries (SQL `SELECT` or ORM raw select) ➔ returns read-only `DTO`.
+- *Zero distributed complexity; 100% ACID consistency.*
+
+### Level 2: Segregated Read Models (Single DB, Synchronous)
+- When read queries require expensive aggregations or multi-table joins, create dedicated read tables, database views, or PostgreSQL JSONB projection columns in the same database.
+- Projections are updated **synchronously within the same database transaction** as the command mutation (or via database triggers).
+- *Guarantees immediate read-your-own-writes consistency without distributed outbox pipelines.*
+
+### Level 3: Polyglot Persistence & Asynchronous Projections
+- Writes commit to the transactional primary database (e.g. PostgreSQL).
+- Events are emitted via the Transactional Outbox pattern and streamed to secondary read stores (e.g. Elasticsearch for search, Redis for caches, ClickHouse for telemetry).
+- *Requires strict handling of eventual consistency, projection replay, and outbox delivery.*
+
+---
+
+## 3. Tactical Implementation Patterns (TypeScript)
+
+### 1. Command Side: Enforcing Invariants via Aggregates
+Commands express user intent, encapsulate validation, and mutate state through the Aggregate Root:
+
+```typescript
+// commands/create_order.command.ts
+export interface CreateOrderCommand {
+  readonly orderId: string;
+  readonly customerId: string;
+  readonly items: ReadonlyArray<{ productId: string; quantity: number; unitPriceCents: number }>;
+}
+
+// handlers/create_order.handler.ts
+export class CreateOrderCommandHandler {
+  constructor(
+    private readonly orderRepo: OrderRepositoryPort,
+    private readonly outbox: TransactionalOutboxPort
+  ) {}
+
+  async execute(command: CreateOrderCommand): Promise<Result<void, OrderDomainError>> {
+    // 1. Load or instantiate Aggregate Root
+    const orderResult = OrderAggregate.create({
+      id: command.orderId,
+      customerId: command.customerId,
+      items: command.items
+    });
+
+    if (orderResult.isFailure) {
+      return Result.fail(orderResult.error);
+    }
+
+    const order = orderResult.value;
+
+    // 2. Commit aggregate mutation and outbox event atomically in 1 transaction
+    await this.orderRepo.transaction(async (tx) => {
+      await this.orderRepo.save(order, tx);
+      for (const event of order.pullDomainEvents()) {
+        await this.outbox.stageEvent(event, tx);
+      }
+    });
+
+    return Result.ok();
+  }
+}
+```
+
+### 2. Query Side: Fast Direct Projection DTOs
+Queries bypass domain entities and ORM aggregate hydration entirely, executing direct, index-optimized reads:
+
+```typescript
+// queries/get_customer_orders.query.ts
+export interface GetCustomerOrdersQuery {
+  readonly customerId: string;
+  readonly limit: number;
+  readonly cursor?: string;
+}
+
+export interface CustomerOrderSummaryDTO {
+  readonly orderId: string;
+  readonly totalCents: number;
+  readonly status: string;
+  readonly itemCount: number;
+  readonly createdAt: string;
+}
+
+// handlers/get_customer_orders.handler.ts
+export class GetCustomerOrdersQueryHandler {
+  constructor(private readonly db: ReadDatabaseClient) {}
+
+  async execute(query: GetCustomerOrdersQuery): Promise<CustomerOrderSummaryDTO[]> {
+    // Direct SQL projection - zero domain aggregate hydration overhead
+    return await this.db.query<CustomerOrderSummaryDTO>(
+      `SELECT order_id as "orderId", total_cents as "totalCents", 
+              status, item_count as "itemCount", created_at as "createdAt"
+       FROM order_summaries_view
+       WHERE customer_id = $1
+       ORDER BY created_at DESC
+       LIMIT $2`,
+      [query.customerId, query.limit]
+    );
+  }
+}
+```
+
+---
+
+## 4. Asynchronous Projection Invariants (Level 3 CQRS)
+
+When graduating to Level 3 (asynchronous read stores), you must prevent data corruption, drift, and race conditions:
+
+### 1. Zero Dual-Writes (Strict Outbox Mandate)
+Never write to the command database and then publish to a message broker (RabbitMQ/Kafka) in two independent operations. Network failure between the two operations corrupts read models. Always use the **Transactional Outbox Pattern** (see [`docs/rules/database_design.md`](./database_design.md)).
+
+### 2. Monotonic Sequence & Idempotent Projectors
+Every domain event must carry an aggregate version number. Read projectors must discard duplicate or out-of-order events:
+```typescript
+export async function projectOrderUpdated(event: OrderUpdatedEvent, db: ReadDb): Promise<void> {
+  // Idempotent upsert guarded by monotonic version sequence
+  await db.query(
+    `UPDATE order_read_models 
+     SET status = $1, version = $2, updated_at = $3
+     WHERE order_id = $4 AND version < $2`,
+    [event.newStatus, event.version, event.occurredAt, event.orderId]
+  );
+}
+```
+
+---
+
+## 5. Defending Read-Your-Own-Writes Consistency
+
+The biggest hazard of asynchronous CQRS is **eventual consistency lag**: a user submits a mutation (e.g. updating their display name), receives an HTTP `200 OK`, gets redirected to their profile, but still sees their old name because the background projection worker is lagging.
+
+### Strategies to Eliminate User-Perceived Lag
+1. **Optimistic UI Updates**: The frontend immediately updates the client cache with the submitted values upon HTTP 200 response, without refetching from the query API.
+2. **Monotonic Version Headers**:
+   - The command response returns the new entity version: `ETag: "v14"`.
+   - Subsequent query requests include `If-None-Match: "v14"` or `X-Min-Version: 14`.
+   - If the read projection has not caught up to `v14`, the query service waits (up to 500ms) or falls back to querying the primary write database.
+3. **Session Read-Model Pinning**: Direct read requests from the mutating user's session to the primary database for 5 seconds after a command execution, while general traffic continues reading from the read replica.
+
+---
+
+## 6. Gotchas & Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Mandated Correction |
+|---|---|---|
+| **CQRS as Default Architecture** | Multiplies boilerplate, schemas, and cognitive load 3x on simple applications (YAGNI violation). | Default to Single Model / Single Database. Graduate only on measured bottlenecks. |
+| **Conflating CQRS with Event Sourcing** | Event Sourcing stores all state as event streams; CQRS only separates read and write pathways. ES adds severe schema migration complexity. | Implement CQRS with standard relational state. Only add Event Sourcing if the business requires legal/temporal audit ledgers. |
+| **Leaking Entities into Queries** | Hydrating full Domain Aggregates inside Query Handlers causes severe N+1 query cascades and memory bloat. | Query Handlers must bypass entities and return flat, serializable DTOs directly from the database. |
+| **Dual-Write Projections** | Emitting HTTP calls or message queue pushes directly inside mutation services causes silent sync failures. | Write events to a local `outbox` table in the same DB transaction as the aggregate state change. |
+| **CRUD Queries via Aggregate Roots** | Loading an entire Aggregate Root just to read 2 fields creates unnecessary lock contention and memory footprint. | Use direct projection queries (Level 1 CQRS) for read-only flows. |

package/docs/rules/database_design.md

@@ -0,0 +1,125 @@
+# Database Design, Relational Integrity & Transactions
+
+> **Core Mandate:** Enforce relational constraints at the database engine level (FKs, CHECKs, EXCLUDEs), the Canonical 6 Total Audit Fields, partial soft-delete indexes, ACID transactional boundaries, and the Transactional Outbox pattern.
+
+---
+
+## 1. Relational Integrity & Engine-Level Constraints
+
+Data integrity must be enforced by the relational database engine, not delegated exclusively to application code:
+
+```mermaid
+flowchart TD
+    App["Application Layer<br/>Validates DTOs (Zod / Pydantic / Bean Validation)"] --> DB["Database Engine (Final Arbiter of Truth)"]
+    subgraph EngineRules["Engine Constraints"]
+        DB --> FK["FOREIGN KEY<br/>Referential Integrity"]
+        DB --> CHECK["CHECK<br/>Domain Invariants & Ranges"]
+        DB --> EXCLUDE["EXCLUDE USING gist<br/>Temporal Non-Overlaps"]
+        DB --> PARTIAL["Partial Unique Indexes<br/>UNIQUE ... WHERE deleted_at IS NULL"]
+    end
+```
+
+### Invariants:
+1. **Mandatory Foreign Keys**: Every relational association must define an explicit foreign key constraint with explicit `ON DELETE` semantics (`ON DELETE RESTRICT` or `ON DELETE CASCADE`).
+2. **Domain `CHECK` Constraints**: Enforce domain value ranges at the schema level:
+   ```sql
+   ALTER TABLE orders ADD CONSTRAINT check_positive_amount CHECK (total_amount >= 0);
+   ALTER TABLE users ADD CONSTRAINT check_valid_role CHECK (role IN ('ADMIN', 'OPERATOR', 'MEMBER'));
+   ```
+3. **Temporal Non-Overlap (`EXCLUDE`)**: Scheduling, booking, or reservation systems must prevent double-booking using PostgreSQL range exclusion constraints:
+   ```sql
+   ALTER TABLE bookings ADD CONSTRAINT no_overlapping_reservations
+     EXCLUDE USING gist (room_id WITH =, reservation_period WITH &&);
+   ```
+
+---
+
+## 2. The Canonical 6 Total Audit Fields
+
+Every mutable stateful entity in the database must implement the **Canonical 6 Total Audit Fields** to guarantee complete traceability for compliance and security audits:
+
+```sql
+CREATE TABLE resources (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id UUID NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  
+  -- The Canonical 6 Total Audit Fields
+  created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  created_by UUID NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  updated_by UUID NOT NULL,
+  deleted_at TIMESTAMPTZ,
+  deleted_by UUID
+);
+```
+
+### Rules & Append-Only Exception:
+- **Mutable Tables:** All 6 fields are mandatory. Application repositories must automatically populate `createdBy`/`updatedBy` from the ambient authenticated user context.
+- **Append-Only Event / Ledger Tables:** Immutable financial ledgers, audit logs, and domain events omit `updated_at`, `updated_by`, `deleted_at`, and `deleted_by` (immutable rows are never updated or deleted).
+
+---
+
+## 3. Soft-Delete Invariants & Partial Unique Indexes
+
+When implementing soft-delete (`deleted_at IS NOT NULL`):
+1. **Never Use Unfiltered Unique Constraints**: A standard `UNIQUE(slug)` constraint prevents creating a new record with the same slug after deleting an old record.
+2. **Mandatory Partial Unique Index**:
+   ```sql
+   -- Correct: Allows reusing slug after soft-deletion
+   CREATE UNIQUE INDEX idx_resources_tenant_slug_active 
+     ON resources (tenant_id, slug) 
+     WHERE deleted_at IS NULL;
+   ```
+3. **Soft-Delete Query Filtering**: All read queries must filter `WHERE deleted_at IS NULL` unless explicitly requesting archived records.
+
+---
+
+## 4. ACID Transactions & Isolation Levels
+
+Every operation mutating multiple database rows or coordinating interrelated aggregates must execute within an explicit **ACID Transaction**:
+
+### Transaction Guidelines:
+- **Single Aggregate Transactions**: Strive to keep transactions bounded to a single aggregate root.
+- **Isolation Level Selection**:
+  - `READ COMMITTED` (Default): Acceptable for standard CRUD operations.
+  - `REPEATABLE READ` / `SERIALIZABLE`: Mandatory for financial ledger balances, inventory decrements, and ticket allocations where phantom reads cause double-spending.
+- **Defensive Timeouts**: Transactions must never run indefinitely. Always set a defensive statement and transaction timeout:
+  ```sql
+  SET LOCAL statement_timeout = '5s';
+  SET LOCAL idle_in_transaction_session_timeout = '10s';
+  ```
+
+---
+
+## 5. The Transactional Outbox Pattern (Dual-Write Defense)
+
+Never execute a database write and a message broker publish sequentially in application code. If the network fails between the two operations, the system enters an inconsistent, corrupted state (**The Dual-Write Anti-Pattern**).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Caller
+    participant App as Application Service
+    participant DB as PostgreSQL Database
+    participant Relay as CDC Relay / Worker
+    participant Broker as Message Broker (Kafka/SQS)
+
+    Caller->>App: Execute Command
+    activate App
+    Note over App,DB: Atomic ACID Transaction
+    App->>DB: 1. Mutate Domain State (UPDATE accounts...)
+    App->>DB: 2. Insert Outbox Event (INSERT INTO outbox_events...)
+    App->>DB: COMMIT
+    App-->>Caller: Success Response
+    deactivate App
+
+    Note over Relay,Broker: Asynchronous Processing
+    Relay->>DB: 3. Read unpublished outbox_events (CDC / Polling)
+    Relay->>Broker: 4. Publish Event to Broker
+    Relay->>DB: 5. Mark Event Published / Purge
+```
+
+### Outbox Invariants:
+1. **Atomic Ingestion**: Domain entity mutation and event insertion must share the identical database transaction.
+2. **Guaranteed At-Least-Once Delivery**: The outbox relay guarantees delivery to consumers; consumers must implement idempotency.