azcodr 1.5.0 → 1.5.1

package/docs/rules/database_design.md

@@ -1,125 +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.
+# 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.

package/docs/rules/database_operations.md

@@ -1,69 +1,69 @@
-# Database Operations, Migrations & Performance Engineering
-
-> **Core Mandate:** Enforce zero-downtime expand-contract migrations via declarative tools, systematic N+1 query elimination via DataLoader/batching, composite tenant indexing, connection pooling, and continuous point-in-time recovery (PITR).
-
----
-
-## 1. Zero-Downtime Expand-Contract Migrations
-
-Database schema migrations must never require maintenance windows or downtime. Follow the **3-Phase Expand-Contract Pattern**:
-
-```mermaid
-flowchart LR
-    P1["Phase 1: EXPAND<br/>(Zero-Downtime DDL)<br/>Add new column as NULLABLE/DEFAULT<br/>Zero breaking locks"]
-    P2["Phase 2: DUAL-RUN & BACKFILL<br/>(Application Rolling Update)<br/>Deploy app writing both columns<br/>Backfill historical rows<br/>Read fallback to old column"]
-    P3["Phase 3: CONTRACT<br/>(Cleanup DDL)<br/>Drop old column<br/>after 100% traffic migrates"]
-    P1 --> P2 --> P3
-```
-
-### Invariants:
-1. **Never Rename Columns in a Single Step**: Renaming a column causes running application instances to crash. Always expand with a new column, dual-write, backfill, and drop the old column in a subsequent release.
-2. **Concurrent Index Creation**: In PostgreSQL, never create indexes with standard blocking DDL. Always use `CREATE INDEX CONCURRENTLY` to prevent locking table writes.
-3. **Declarative Migration Tooling**: Standardize on open-source declarative migration tools (e.g. **Atlas**, **Flyway**, or **Liquibase**) that compute deterministic migration plans against production schemas.
-
----
-
-## 2. Performance Engineering & N+1 Query Defense
-
-A catastrophic database performance bottleneck is the **N+1 Query Problem**, where an application executes 1 query for a list and $N$ additional queries for related records in a loop.
-
-### Invariants:
-1. **Mandatory DataLoader / Batch Fetching**: In GraphQL resolvers, ORM mappers, or loop iterations, always batch entity queries via a DataLoader or SQL `IN (...)` batch queries:
-   ```typescript
-   // Correct: Single batched query for all tenant users
-   const users = await userLoader.loadMany(userIds);
-   ```
-2. **Composite Tenant Indexes**: In multi-tenant systems, every primary lookup index must include `tenant_id` as the leading column:
-   ```sql
-   -- Correct: Optimized for tenant-scoped date range filtering
-   CREATE INDEX idx_orders_tenant_created 
-     ON orders (tenant_id, created_at DESC);
-   ```
-3. **Index Hygiene & Covering Indexes**: Use `EXPLAIN (ANALYZE, BUFFERS)` to verify index scans. For high-frequency queries, use covering indexes (`INCLUDE (...)`) to satisfy queries directly from index pages without heap fetches.
-
----
-
-## 3. Connection Pooling & Resource Limits
-
-Database connections are expensive resources requiring thread stacks and memory allocation. An uncapped connection pool will exhaust database memory and crash the server under load spikes.
-
-### Invariants:
-1. **Dedicated Connection Pooling**: In production, deploy a dedicated connection pooler (e.g. **PgBouncer** in transaction pooling mode for PostgreSQL, or **HikariCP** in JVM runtimes).
-2. **Connection Sizing Formula**: Size application pools conservatively using the standard Postgres sizing formula:
-   $$\text{connections} = ((\text{core\_count} \times 2) + \text{effective\_disk\_count})$$
-   Over-allocating connections (e.g., 500 connections on an 8-core server) causes severe CPU thrashing and context-switch latency.
-3. **Connection Lifecycle Limits**: Configure `max_lifetime` (e.g. 30 minutes) and `idle_timeout` (e.g. 10 minutes) to cycle stale connections and prevent socket leaks.
-
----
-
-## 4. Operational Resilience & Backup Baselines
-
-1. **Continuous Point-In-Time Recovery (PITR)**: Production databases must configure continuous WAL (Write-Ahead Log) archiving to object storage (e.g. via `pgBackRest` or `wal-g`), enabling recovery to any arbitrary second within the retention window.
-2. **Autovacuum Tuning (PostgreSQL)**: For high-throughput transactional tables, tune autovacuum parameters to prevent table bloat and transaction ID wraparound:
-   ```sql
-   ALTER TABLE orders SET (
-     autovacuum_vacuum_scale_factor = 0.05,
-     autovacuum_vacuum_cost_limit = 1000
-   );
-   ```
-3. **Database Role Separation**: The application connection user must never connect as `postgres` or `superuser`. Create a dedicated least-privilege `app_user` granted only `DML` (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) on application tables.
+# Database Operations, Migrations & Performance Engineering
+
+> **Core Mandate:** Enforce zero-downtime expand-contract migrations via declarative tools, systematic N+1 query elimination via DataLoader/batching, composite tenant indexing, connection pooling, and continuous point-in-time recovery (PITR).
+
+---
+
+## 1. Zero-Downtime Expand-Contract Migrations
+
+Database schema migrations must never require maintenance windows or downtime. Follow the **3-Phase Expand-Contract Pattern**:
+
+```mermaid
+flowchart LR
+    P1["Phase 1: EXPAND<br/>(Zero-Downtime DDL)<br/>Add new column as NULLABLE/DEFAULT<br/>Zero breaking locks"]
+    P2["Phase 2: DUAL-RUN & BACKFILL<br/>(Application Rolling Update)<br/>Deploy app writing both columns<br/>Backfill historical rows<br/>Read fallback to old column"]
+    P3["Phase 3: CONTRACT<br/>(Cleanup DDL)<br/>Drop old column<br/>after 100% traffic migrates"]
+    P1 --> P2 --> P3
+```
+
+### Invariants:
+1. **Never Rename Columns in a Single Step**: Renaming a column causes running application instances to crash. Always expand with a new column, dual-write, backfill, and drop the old column in a subsequent release.
+2. **Concurrent Index Creation**: In PostgreSQL, never create indexes with standard blocking DDL. Always use `CREATE INDEX CONCURRENTLY` to prevent locking table writes.
+3. **Declarative Migration Tooling**: Standardize on open-source declarative migration tools (e.g. **Atlas**, **Flyway**, or **Liquibase**) that compute deterministic migration plans against production schemas.
+
+---
+
+## 2. Performance Engineering & N+1 Query Defense
+
+A catastrophic database performance bottleneck is the **N+1 Query Problem**, where an application executes 1 query for a list and $N$ additional queries for related records in a loop.
+
+### Invariants:
+1. **Mandatory DataLoader / Batch Fetching**: In GraphQL resolvers, ORM mappers, or loop iterations, always batch entity queries via a DataLoader or SQL `IN (...)` batch queries:
+   ```typescript
+   // Correct: Single batched query for all tenant users
+   const users = await userLoader.loadMany(userIds);
+   ```
+2. **Composite Tenant Indexes**: In multi-tenant systems, every primary lookup index must include `tenant_id` as the leading column:
+   ```sql
+   -- Correct: Optimized for tenant-scoped date range filtering
+   CREATE INDEX idx_orders_tenant_created 
+     ON orders (tenant_id, created_at DESC);
+   ```
+3. **Index Hygiene & Covering Indexes**: Use `EXPLAIN (ANALYZE, BUFFERS)` to verify index scans. For high-frequency queries, use covering indexes (`INCLUDE (...)`) to satisfy queries directly from index pages without heap fetches.
+
+---
+
+## 3. Connection Pooling & Resource Limits
+
+Database connections are expensive resources requiring thread stacks and memory allocation. An uncapped connection pool will exhaust database memory and crash the server under load spikes.
+
+### Invariants:
+1. **Dedicated Connection Pooling**: In production, deploy a dedicated connection pooler (e.g. **PgBouncer** in transaction pooling mode for PostgreSQL, or **HikariCP** in JVM runtimes).
+2. **Connection Sizing Formula**: Size application pools conservatively using the standard Postgres sizing formula:
+   $$\text{connections} = ((\text{core\_count} \times 2) + \text{effective\_disk\_count})$$
+   Over-allocating connections (e.g., 500 connections on an 8-core server) causes severe CPU thrashing and context-switch latency.
+3. **Connection Lifecycle Limits**: Configure `max_lifetime` (e.g. 30 minutes) and `idle_timeout` (e.g. 10 minutes) to cycle stale connections and prevent socket leaks.
+
+---
+
+## 4. Operational Resilience & Backup Baselines
+
+1. **Continuous Point-In-Time Recovery (PITR)**: Production databases must configure continuous WAL (Write-Ahead Log) archiving to object storage (e.g. via `pgBackRest` or `wal-g`), enabling recovery to any arbitrary second within the retention window.
+2. **Autovacuum Tuning (PostgreSQL)**: For high-throughput transactional tables, tune autovacuum parameters to prevent table bloat and transaction ID wraparound:
+   ```sql
+   ALTER TABLE orders SET (
+     autovacuum_vacuum_scale_factor = 0.05,
+     autovacuum_vacuum_cost_limit = 1000
+   );
+   ```
+3. **Database Role Separation**: The application connection user must never connect as `postgres` or `superuser`. Create a dedicated least-privilege `app_user` granted only `DML` (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) on application tables.

package/docs/rules/design_patterns.md

@@ -1,98 +1,98 @@
-# Modern Design Patterns & Result Pattern
-
-> **Core Mandate:** Enforce composition over inheritance, wrap third-party boundaries in project-owned adapters, and model domain errors with explicit Result types instead of untyped exceptions.
-
----
-
-## 1. Structural & Creational Patterns
-
-- **Adapter Pattern (Hexagonal Boundary)**: Wrap all external libraries, database drivers, cloud SDKs, and third-party APIs in project-owned adapter interfaces. *Rule: Only mock types you own.*
-- **Factory Method**: Encapsulate complex collaborator instantiation (e.g. tenant-specific payment gateways or notification dispatchers) behind factory functions.
-- **Facade Pattern**: Expose a unified, simplified interface to complex underlying multi-service subsystems.
-- **Decorator / Middleware**: Compose cross-cutting concerns (observability, authentication, tenant context resolution, rate limiting) via middleware pipelines.
-- **Dependency Injection & Composition Hygiene**: Application factories (`createApp(deps)`) must accept an explicit composite container (`AppDependencies`). Never provide silent default fallback instances inside factories that instantiate disconnected repositories or services when partial dependencies are passed (the Split-Brain Anti-Pattern). Assemble the full dependency graph explicitly at the composition root.
-
----
-
-## 2. Behavioral Patterns & Explicit Result Types
-
-- **Strategy Pattern**: Swap algorithms or execution behavior at runtime without code changes (e.g. tenant-specific pricing algorithms, shipping calculation strategies).
-- **Result / Either Pattern**: Model anticipated domain errors as explicit return values (`Result<T, E>`) rather than throwing untyped exceptions across architectural boundaries:
-
-```mermaid
-classDiagram
-    class Result~T_E~ {
-        <<Universal Semantics>>
-        +isOk() boolean
-        +isErr() boolean
-        +unwrap() T
-        +unwrapErr() E
-    }
-    class Ok~T~ {
-        +value: T
-    }
-    class Err~E~ {
-        +error: E
-    }
-    Result <|-- Ok
-    Result <|-- Err
-    note for Result "Rust: Result~T, DomainError~<br/>Go: (T, error)<br/>TypeScript: type Result~T, E~ = Ok~T~ | Err~E~<br/>Python: Union[Success[T], Failure[E]]"
-```
-
-Domain services must return explicit Result types, compelling callers to handle failure branches deterministically.
-
----
-
-## 3. Gang of Four (GoF) 23 Patterns Master Catalog
-
-### A. Creational Patterns (5 Patterns)
-1. **Factory Method**: Define an interface for creating an object, but let subclasses or factory functions decide which class to instantiate.
-   - *Use Case:* Tenant-specific payment gateway instantiation (`StripeAdapter` vs `PayPalAdapter`).
-2. **Abstract Factory**: Provide an interface for creating families of related or dependent objects without specifying concrete classes.
-   - *Use Case:* Multi-cloud storage factories creating matching `FileUploader`, `FileDownloader`, and `PresignedUrlGenerator` for S3, GCS, or MinIO.
-3. **Builder**: Separate the construction of a complex object from its representation, allowing the same construction process to create different representations.
-   - *Use Case:* Fluent query builders, complex report generators, or test data builders (`OrderBuilder.withItems(...).build()`).
-4. **Prototype**: Specify the kinds of objects to create using a prototypical instance, creating new objects by cloning this prototype.
-   - *Use Case:* Fast cloning of default tenant configuration templates without querying storage.
-5. **Singleton (DI-Scoped)**: Ensure a class has only one instance and provide a global point of access.
-   - *Rule:* Avoid global static singletons (causes test coupling). Enforce singleton lifecycle strictly through Dependency Injection (DI) containers.
-
-### B. Structural Patterns (7 Patterns)
-6. **Adapter (Mandatory)**: Convert the interface of a class into another interface clients expect.
-   - *Use Case:* Wrapping 3rd-party SDKs, storage drivers, and external network clients in application-owned interfaces. *Rule: Only mock types you own.*
-7. **Bridge**: Decouple an abstraction from its implementation so the two can vary independently.
-   - *Use Case:* Decoupling notification abstractions (`UrgentNotification`, `BatchNotification`) from delivery channels (`EmailChannel`, `SlackChannel`).
-8. **Composite**: Compose objects into tree structures to represent part-whole hierarchies.
-   - *Use Case:* Nested RBAC permission trees or hierarchical menu navigation systems.
-9. **Decorator**: Attach additional responsibilities to an object dynamically as a flexible alternative to subclassing.
-   - *Use Case:* Wrapping repository methods with distributed caching, OpenTelemetry tracing, or metrics logging.
-10. **Facade**: Provide a unified, high-level interface to a complex set of interfaces in a subsystem.
-    - *Use Case:* Checkout facade orchestrating inventory verification, payment processing, invoice generation, and email notification.
-11. **Flyweight**: Use sharing to support large numbers of fine-grained objects efficiently.
-    - *Use Case:* In-memory sharing of immutable tenant metadata and shared system role permission definitions.
-12. **Proxy**: Provide a surrogate or placeholder for another object to control access to it.
-    - *Use Case:* Lazy-loading database relations, virtual proxies for large assets, or tenant-scoped connection proxies.
-
-### C. Behavioral Patterns (11 Patterns)
-13. **Chain of Responsibility**: Pass requests along a chain of handlers until a handler processes it or the chain ends.
-    - *Use Case:* Inbound gateway middleware pipelines (Authentication ➔ TenantResolution ➔ RateLimiting ➔ Controller).
-14. **Command**: Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undo.
-    - *Use Case:* Asynchronous job queues, transactional audit commands, CQRS command handlers.
-15. **Interpreter**: Given a language, define a representation for its grammar along with an interpreter that uses the representation to interpret sentences.
-    - *Use Case:* Custom search filter parsers (`status:active AND tier:pro`) or rule engine expression evaluation.
-16. **Iterator**: Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.
-    - *Use Case:* Async iterators streaming large database cursor result sets or reading multi-part upload chunks.
-17. **Mediator**: Define an object that encapsulates how a set of objects interact, preventing direct coupling between them.
-    - *Use Case:* In-memory event dispatcher mediating communication between decoupled domain services.
-18. **Memento**: Without violating encapsulation, capture and externalize an object's internal state so the object can be restored to this state later.
-    - *Use Case:* Audit trail snapshots recording `before` and `after` states for rollback capabilities.
-19. **Observer**: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.
-    - *Use Case:* Domain Event buses (`UserRegisteredEvent`, `PaymentFailedEvent`) invoking multiple listeners.
-20. **State**: Allow an object to alter its behavior when its internal state changes, appearing as if it changed its class.
-    - *Use Case:* Subscription lifecycles (`TrialState` ➔ `ActiveState` ➔ `PastDueState` ➔ `CanceledState`) where allowed actions change dynamically.
-21. **Strategy**: Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
-    - *Use Case:* Dynamic fee calculation, tenant-specific password complexity policies, or feature flag evaluation providers.
-22. **Template Method**: Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
-    - *Use Case:* Base ETL or data import pipelines with fixed steps (Extract ➔ Validate ➔ Transform ➔ Persist) where subclasses define validation.
-23. **Visitor**: Represent an operation to be performed on the elements of an object structure, defining a new operation without changing the classes of the elements.
-    - *Use Case:* Document export engines traversing an AST of content blocks to generate HTML, Markdown, or PDF.
+# Modern Design Patterns & Result Pattern
+
+> **Core Mandate:** Enforce composition over inheritance, wrap third-party boundaries in project-owned adapters, and model domain errors with explicit Result types instead of untyped exceptions.
+
+---
+
+## 1. Structural & Creational Patterns
+
+- **Adapter Pattern (Hexagonal Boundary)**: Wrap all external libraries, database drivers, cloud SDKs, and third-party APIs in project-owned adapter interfaces. *Rule: Only mock types you own.*
+- **Factory Method**: Encapsulate complex collaborator instantiation (e.g. tenant-specific payment gateways or notification dispatchers) behind factory functions.
+- **Facade Pattern**: Expose a unified, simplified interface to complex underlying multi-service subsystems.
+- **Decorator / Middleware**: Compose cross-cutting concerns (observability, authentication, tenant context resolution, rate limiting) via middleware pipelines.
+- **Dependency Injection & Composition Hygiene**: Application factories (`createApp(deps)`) must accept an explicit composite container (`AppDependencies`). Never provide silent default fallback instances inside factories that instantiate disconnected repositories or services when partial dependencies are passed (the Split-Brain Anti-Pattern). Assemble the full dependency graph explicitly at the composition root.
+
+---
+
+## 2. Behavioral Patterns & Explicit Result Types
+
+- **Strategy Pattern**: Swap algorithms or execution behavior at runtime without code changes (e.g. tenant-specific pricing algorithms, shipping calculation strategies).
+- **Result / Either Pattern**: Model anticipated domain errors as explicit return values (`Result<T, E>`) rather than throwing untyped exceptions across architectural boundaries:
+
+```mermaid
+classDiagram
+    class Result~T_E~ {
+        <<Universal Semantics>>
+        +isOk() boolean
+        +isErr() boolean
+        +unwrap() T
+        +unwrapErr() E
+    }
+    class Ok~T~ {
+        +value: T
+    }
+    class Err~E~ {
+        +error: E
+    }
+    Result <|-- Ok
+    Result <|-- Err
+    note for Result "Rust: Result~T, DomainError~<br/>Go: (T, error)<br/>TypeScript: type Result~T, E~ = Ok~T~ | Err~E~<br/>Python: Union[Success[T], Failure[E]]"
+```
+
+Domain services must return explicit Result types, compelling callers to handle failure branches deterministically.
+
+---
+
+## 3. Gang of Four (GoF) 23 Patterns Master Catalog
+
+### A. Creational Patterns (5 Patterns)
+1. **Factory Method**: Define an interface for creating an object, but let subclasses or factory functions decide which class to instantiate.
+   - *Use Case:* Tenant-specific payment gateway instantiation (`StripeAdapter` vs `PayPalAdapter`).
+2. **Abstract Factory**: Provide an interface for creating families of related or dependent objects without specifying concrete classes.
+   - *Use Case:* Multi-cloud storage factories creating matching `FileUploader`, `FileDownloader`, and `PresignedUrlGenerator` for S3, GCS, or MinIO.
+3. **Builder**: Separate the construction of a complex object from its representation, allowing the same construction process to create different representations.
+   - *Use Case:* Fluent query builders, complex report generators, or test data builders (`OrderBuilder.withItems(...).build()`).
+4. **Prototype**: Specify the kinds of objects to create using a prototypical instance, creating new objects by cloning this prototype.
+   - *Use Case:* Fast cloning of default tenant configuration templates without querying storage.
+5. **Singleton (DI-Scoped)**: Ensure a class has only one instance and provide a global point of access.
+   - *Rule:* Avoid global static singletons (causes test coupling). Enforce singleton lifecycle strictly through Dependency Injection (DI) containers.
+
+### B. Structural Patterns (7 Patterns)
+6. **Adapter (Mandatory)**: Convert the interface of a class into another interface clients expect.
+   - *Use Case:* Wrapping 3rd-party SDKs, storage drivers, and external network clients in application-owned interfaces. *Rule: Only mock types you own.*
+7. **Bridge**: Decouple an abstraction from its implementation so the two can vary independently.
+   - *Use Case:* Decoupling notification abstractions (`UrgentNotification`, `BatchNotification`) from delivery channels (`EmailChannel`, `SlackChannel`).
+8. **Composite**: Compose objects into tree structures to represent part-whole hierarchies.
+   - *Use Case:* Nested RBAC permission trees or hierarchical menu navigation systems.
+9. **Decorator**: Attach additional responsibilities to an object dynamically as a flexible alternative to subclassing.
+   - *Use Case:* Wrapping repository methods with distributed caching, OpenTelemetry tracing, or metrics logging.
+10. **Facade**: Provide a unified, high-level interface to a complex set of interfaces in a subsystem.
+    - *Use Case:* Checkout facade orchestrating inventory verification, payment processing, invoice generation, and email notification.
+11. **Flyweight**: Use sharing to support large numbers of fine-grained objects efficiently.
+    - *Use Case:* In-memory sharing of immutable tenant metadata and shared system role permission definitions.
+12. **Proxy**: Provide a surrogate or placeholder for another object to control access to it.
+    - *Use Case:* Lazy-loading database relations, virtual proxies for large assets, or tenant-scoped connection proxies.
+
+### C. Behavioral Patterns (11 Patterns)
+13. **Chain of Responsibility**: Pass requests along a chain of handlers until a handler processes it or the chain ends.
+    - *Use Case:* Inbound gateway middleware pipelines (Authentication ➔ TenantResolution ➔ RateLimiting ➔ Controller).
+14. **Command**: Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undo.
+    - *Use Case:* Asynchronous job queues, transactional audit commands, CQRS command handlers.
+15. **Interpreter**: Given a language, define a representation for its grammar along with an interpreter that uses the representation to interpret sentences.
+    - *Use Case:* Custom search filter parsers (`status:active AND tier:pro`) or rule engine expression evaluation.
+16. **Iterator**: Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.
+    - *Use Case:* Async iterators streaming large database cursor result sets or reading multi-part upload chunks.
+17. **Mediator**: Define an object that encapsulates how a set of objects interact, preventing direct coupling between them.
+    - *Use Case:* In-memory event dispatcher mediating communication between decoupled domain services.
+18. **Memento**: Without violating encapsulation, capture and externalize an object's internal state so the object can be restored to this state later.
+    - *Use Case:* Audit trail snapshots recording `before` and `after` states for rollback capabilities.
+19. **Observer**: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified automatically.
+    - *Use Case:* Domain Event buses (`UserRegisteredEvent`, `PaymentFailedEvent`) invoking multiple listeners.
+20. **State**: Allow an object to alter its behavior when its internal state changes, appearing as if it changed its class.
+    - *Use Case:* Subscription lifecycles (`TrialState` ➔ `ActiveState` ➔ `PastDueState` ➔ `CanceledState`) where allowed actions change dynamically.
+21. **Strategy**: Define a family of algorithms, encapsulate each one, and make them interchangeable at runtime.
+    - *Use Case:* Dynamic fee calculation, tenant-specific password complexity policies, or feature flag evaluation providers.
+22. **Template Method**: Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
+    - *Use Case:* Base ETL or data import pipelines with fixed steps (Extract ➔ Validate ➔ Transform ➔ Persist) where subclasses define validation.
+23. **Visitor**: Represent an operation to be performed on the elements of an object structure, defining a new operation without changing the classes of the elements.
+    - *Use Case:* Document export engines traversing an AST of content blocks to generate HTML, Markdown, or PDF.