gaia-framework 1.58.0 → 1.58.2

package/_gaia/dev/knowledge/go/gin-fiber-patterns.md

@@ -0,0 +1,40 @@
+# Gin & Fiber Web Framework Patterns
+
+<!-- SECTION: gin -->
+## Gin Patterns
+
+- Router groups for versioned APIs: `v1 := r.Group("/api/v1")`
+- Middleware: `r.Use(middleware)` — logging, auth, CORS, recovery
+- Context: `c.JSON()`, `c.ShouldBindJSON()`, `c.Param()`, `c.Query()`
+- Validation with binding tags: `binding:"required,min=1"`
+- Error handling: custom error response struct with status codes
+- Graceful shutdown with `signal.Notify` + `server.Shutdown`
+
+<!-- SECTION: fiber -->
+## Fiber Patterns
+
+- Express-inspired API: `app.Get("/path", handler)`
+- Middleware: `app.Use(middleware)` — similar to Express
+- Context: `c.JSON()`, `c.BodyParser()`, `c.Params()`, `c.Query()`
+- High performance via fasthttp (not net/http)
+- Prefork for multi-core utilization
+
+<!-- SECTION: grpc -->
+## gRPC Patterns
+
+- Protocol Buffers for service definition (`.proto` files)
+- `protoc` compiler generates Go code
+- Unary, server-streaming, client-streaming, bidirectional
+- Interceptors for middleware (logging, auth, tracing)
+- Health checks: `grpc_health_v1`
+- Reflection for debugging: `reflection.Register(server)`
+
+<!-- SECTION: database -->
+## Database Patterns
+
+- `database/sql` for raw SQL with connection pooling
+- GORM for ORM: models with struct tags, migrations, associations
+- sqlx for enhanced `database/sql` with named params and struct scanning
+- Connection pool: `SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxLifetime`
+- Transactions: `tx, err := db.Begin()` / `tx.Commit()` / `tx.Rollback()`
+- Migrations: golang-migrate or GORM AutoMigrate

package/_gaia/dev/knowledge/go/go-conventions.md

@@ -0,0 +1,54 @@
+# Go Conventions & Project Structure
+
+<!-- SECTION: project-layout -->
+## Project Layout
+
+```
+project/
+├── cmd/           # Entry points (main packages)
+│   └── server/
+│       └── main.go
+├── internal/      # Private packages (not importable externally)
+│   ├── handler/   # HTTP/gRPC handlers
+│   ├── service/   # Business logic
+│   ├── repository/# Data access
+│   └── model/     # Domain models
+├── pkg/           # Public reusable packages
+├── api/           # API definitions (proto, OpenAPI)
+├── config/        # Configuration
+├── migrations/    # Database migrations
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+<!-- SECTION: naming -->
+## Naming Conventions
+
+- Packages: short, lowercase, single word (`http`, `user`, `auth`)
+- Exported: `PascalCase` — visible outside package
+- Unexported: `camelCase` — private to package
+- Interfaces: `-er` suffix for single-method (`Reader`, `Writer`, `Stringer`)
+- Getters: no `Get` prefix — `user.Name()` not `user.GetName()`
+- Acronyms: all caps (`HTTPHandler`, `URLParser`, `ID`)
+- Test files: `xxx_test.go` alongside source
+
+<!-- SECTION: code-style -->
+## Code Style
+
+- `gofmt` / `goimports` — non-negotiable formatting
+- `golangci-lint` for comprehensive linting
+- Short variable names in small scopes: `i`, `r`, `w`, `ctx`
+- Descriptive names for exported APIs
+- Group imports: stdlib, blank line, third-party, blank line, internal
+- No unused imports or variables (compiler enforced)
+
+<!-- SECTION: patterns -->
+## Common Patterns
+
+- Functional options: `func WithTimeout(d time.Duration) Option`
+- Constructor: `func NewService(opts ...Option) *Service`
+- Repository pattern: interface for data access, struct implements
+- Middleware chain: compose handlers via wrapping
+- Config from environment: `os.Getenv` or `viper` for complex config
+- Graceful shutdown: `signal.NotifyContext` + `errgroup`

package/_gaia/dev/knowledge/go/go-stdlib-patterns.md

@@ -0,0 +1,39 @@
+# Go Standard Library Patterns
+
+<!-- SECTION: http-server -->
+## HTTP Server Patterns
+
+- Use `http.ServeMux` for simple routing, Gin/Fiber for complex APIs
+- `http.Handler` interface: implement `ServeHTTP(w http.ResponseWriter, r *http.Request)`
+- Middleware pattern: `func(next http.Handler) http.Handler`
+- Context propagation: always pass `context.Context` through request chain
+- Graceful shutdown: `server.Shutdown(ctx)` with signal handling
+
+<!-- SECTION: concurrency -->
+## Concurrency Patterns
+
+- Goroutines for concurrent work, channels for communication
+- `sync.WaitGroup` for waiting on multiple goroutines
+- `sync.Mutex` / `sync.RWMutex` for shared state protection
+- `context.Context` for cancellation and timeouts
+- Worker pool pattern: buffered channel + N goroutines
+- Fan-out/fan-in for parallel processing pipelines
+- Never start a goroutine without knowing how it will stop
+
+<!-- SECTION: error-handling -->
+## Error Handling
+
+- Errors are values — wrap with `fmt.Errorf("context: %w", err)`
+- Custom error types implement `error` interface
+- Use `errors.Is()` and `errors.As()` for error inspection
+- Sentinel errors for expected conditions: `var ErrNotFound = errors.New("not found")`
+- Never ignore errors — handle or propagate explicitly
+
+<!-- SECTION: io -->
+## I/O Patterns
+
+- `io.Reader` / `io.Writer` interfaces for streaming
+- `bufio` for buffered I/O
+- `os.OpenFile` with explicit permissions
+- `defer file.Close()` immediately after open
+- `encoding/json` for JSON marshal/unmarshal with struct tags

package/_gaia/dev/knowledge/go/go-testing-patterns.md

@@ -0,0 +1,39 @@
+# Go Testing Patterns
+
+<!-- SECTION: unit-tests -->
+## Unit Testing
+
+- Test files: `*_test.go` in same package
+- Test functions: `func TestXxx(t *testing.T)`
+- Table-driven tests: slice of test cases with name, input, expected
+- `t.Run(name, func(t *testing.T) { ... })` for subtests
+- `t.Parallel()` for concurrent test execution
+- `t.Helper()` in helper functions for correct line reporting
+- `t.Cleanup(func())` for teardown
+
+<!-- SECTION: mocking -->
+## Mocking & Interfaces
+
+- Define interfaces at the consumer, not the provider
+- Mock by implementing the interface in test file
+- `gomock` / `mockgen` for generated mocks
+- `testify/mock` for assertion-style mocking
+- Dependency injection via constructor: `func NewService(repo Repository) *Service`
+
+<!-- SECTION: integration -->
+## Integration Testing
+
+- Build tags: `//go:build integration` to separate from unit tests
+- `testcontainers-go` for database/service containers
+- `httptest.NewServer` for HTTP integration tests
+- `httptest.NewRecorder` for handler testing without server
+- Setup/teardown with `TestMain(m *testing.M)`
+
+<!-- SECTION: benchmarks -->
+## Benchmarks & Fuzzing
+
+- Benchmark functions: `func BenchmarkXxx(b *testing.B)` with `b.N` loop
+- `b.ReportAllocs()` for allocation tracking
+- Fuzz testing: `func FuzzXxx(f *testing.F)` with `f.Add()` seeds
+- `go test -bench=. -benchmem` for memory profiling
+- `go test -race` for race condition detection

package/_gaia/dev/knowledge/java/jpa-patterns.md

@@ -0,0 +1,136 @@
+---
+name: JPA Entity and Repository Patterns
+stack: java
+version: "1.0"
+focus: [jpa]
+---
+
+# JPA Entity and Repository Patterns
+
+## Principle
+
+Map entities to the database with explicit fetch strategies and avoid the N+1 query problem. Use Spring Data JPA repositories for standard CRUD, custom queries for complex operations, and projections for read-only data. Always define fetch types explicitly and prefer `FetchType.LAZY` as the default.
+
+## Rationale
+
+JPA's default fetch strategy for `@ManyToOne` is `EAGER`, which loads related entities immediately and causes cascading queries. The N+1 problem occurs when iterating a collection triggers one query per element. Explicit `LAZY` fetching, combined with `JOIN FETCH` in queries where related data is needed, gives precise control over SQL execution. Projections (interfaces or DTOs) avoid loading full entity graphs for read-only use cases.
+
+## Pattern Examples
+
+### Pattern 1: Entity with Explicit Fetch Strategies
+
+```java
+@Entity
+@Table(name = "orders")
+public class Order {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private LocalDateTime createdAt;
+
+    @Enumerated(EnumType.STRING)
+    private OrderStatus status;
+
+    // Explicit LAZY — loaded only when accessed or JOIN FETCHed
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "customer_id", nullable = false)
+    private Customer customer;
+
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderItem> items = new ArrayList<>();
+
+    // Helper method maintains bidirectional consistency
+    public void addItem(OrderItem item) {
+        items.add(item);
+        item.setOrder(this);
+    }
+
+    public void removeItem(OrderItem item) {
+        items.remove(item);
+        item.setOrder(null);
+    }
+}
+```
+
+### Pattern 2: Solving N+1 with JOIN FETCH
+
+```java
+public interface OrderRepository extends JpaRepository<Order, Long> {
+
+    // BAD: triggers N+1 when accessing order.customer for each order
+    // List<Order> findByStatus(OrderStatus status);
+
+    // GOOD: JOIN FETCH loads customers in one query
+    @Query("""
+        SELECT o FROM Order o
+        JOIN FETCH o.customer
+        WHERE o.status = :status
+        """)
+    List<Order> findByStatusWithCustomer(@Param("status") OrderStatus status);
+
+    // Pagination with JOIN FETCH requires a count query
+    @Query(value = """
+        SELECT o FROM Order o
+        JOIN FETCH o.customer
+        WHERE o.status = :status
+        """,
+        countQuery = "SELECT COUNT(o) FROM Order o WHERE o.status = :status")
+    Page<Order> findByStatusWithCustomerPaged(
+        @Param("status") OrderStatus status, Pageable pageable);
+}
+```
+
+### Pattern 3: DTO Projections for Read-Only Queries
+
+```java
+// Interface-based projection — JPA generates implementation
+public interface OrderSummary {
+    Long getId();
+    LocalDateTime getCreatedAt();
+    OrderStatus getStatus();
+    String getCustomerName();  // derived from JOIN
+}
+
+public interface OrderRepository extends JpaRepository<Order, Long> {
+
+    // Returns lightweight projections, not full entities
+    @Query("""
+        SELECT o.id AS id,
+               o.createdAt AS createdAt,
+               o.status AS status,
+               c.name AS customerName
+        FROM Order o JOIN o.customer c
+        WHERE o.createdAt >= :since
+        """)
+    List<OrderSummary> findRecentOrderSummaries(
+        @Param("since") LocalDateTime since);
+}
+
+// Record-based DTO projection (alternative)
+public record OrderDto(Long id, String customerName, BigDecimal total) {}
+
+@Query("""
+    SELECT new com.example.dto.OrderDto(o.id, c.name, o.total)
+    FROM Order o JOIN o.customer c
+    WHERE o.status = :status
+    """)
+List<OrderDto> findOrderDtos(@Param("status") OrderStatus status);
+```
+
+## Anti-Patterns
+
+- **Implicit EAGER fetching**: `@ManyToOne` defaults to `EAGER`. Always set `fetch = FetchType.LAZY`.
+- **SELECT in a loop**: Iterating a list and calling `repository.findById()` per item. Use `findAllById()` or a batch query.
+- **Returning entities from REST controllers**: Exposes internal structure, causes serialization issues with lazy proxies. Map to DTOs.
+- **Missing `orphanRemoval`**: Without `orphanRemoval = true` on `@OneToMany`, removed children stay in the database.
+- **`CascadeType.ALL` on `@ManyToOne`**: Cascading from child to parent can delete the parent when a child is removed.
+
+## Integration Points
+
+- **Spring Boot**: JPA auto-configuration sets up `EntityManager` and transaction management; see `spring-boot-patterns.md`.
+- **Microservices**: Each service owns its database and entities; see `microservices.md` for bounded context.
+- **Build Tools**: JPA metamodel generation requires annotation processing in Maven/Gradle; see `maven-gradle.md`.
+- **Testing**: Use `@DataJpaTest` for repository tests with an in-memory database.

package/_gaia/dev/knowledge/java/maven-gradle.md

@@ -0,0 +1,189 @@
+---
+name: Maven and Gradle Build Patterns
+stack: java
+version: "1.0"
+focus: [build-tools]
+---
+
+# Maven and Gradle Build Patterns
+
+## Principle
+
+Use multi-module builds to organize large projects with shared dependencies managed through a BOM (Bill of Materials) or parent POM. Keep build scripts declarative, version-lock all dependencies, and use plugins for code generation, testing, and packaging. Choose Maven for convention-heavy projects and Gradle for performance-critical or highly customized builds.
+
+## Rationale
+
+Build tool consistency prevents "works on my machine" issues. A parent POM or BOM centralizes dependency versions so all modules use the same library versions, eliminating conflicts. Multi-module builds enable code reuse (shared DTOs, utilities) while maintaining independent compilation. Plugin management ensures consistent code quality (Checkstyle, SpotBugs) and packaging (Spring Boot fat JARs, Docker images).
+
+## Pattern Examples
+
+### Pattern 1: Maven Multi-Module with BOM
+
+```xml
+<!-- parent pom.xml -->
+<project>
+    <groupId>com.example</groupId>
+    <artifactId>platform-parent</artifactId>
+    <version>1.0.0</version>
+    <packaging>pom</packaging>
+
+    <modules>
+        <module>common</module>
+        <module>user-service</module>
+        <module>order-service</module>
+    </modules>
+
+    <properties>
+        <java.version>21</java.version>
+        <spring-boot.version>3.3.0</spring-boot.version>
+        <mapstruct.version>1.5.5.Final</mapstruct.version>
+    </properties>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring-boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+            <dependency>
+                <groupId>com.example</groupId>
+                <artifactId>common</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+</project>
+
+<!-- user-service/pom.xml -->
+<project>
+    <parent>
+        <groupId>com.example</groupId>
+        <artifactId>platform-parent</artifactId>
+        <version>1.0.0</version>
+    </parent>
+    <artifactId>user-service</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.example</groupId>
+            <artifactId>common</artifactId>
+            <!-- version inherited from parent -->
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+### Pattern 2: Gradle Kotlin DSL with Version Catalog
+
+```kotlin
+// gradle/libs.versions.toml — centralized version catalog
+// [versions]
+// spring-boot = "3.3.0"
+// mapstruct = "1.5.5.Final"
+// [libraries]
+// spring-boot-web = { module = "org.springframework.boot:spring-boot-starter-web" }
+// spring-boot-test = { module = "org.springframework.boot:spring-boot-starter-test" }
+// mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" }
+
+// build.gradle.kts (root)
+plugins {
+    java
+    id("org.springframework.boot") version libs.versions.spring.boot apply false
+}
+
+subprojects {
+    apply(plugin = "java")
+
+    java {
+        sourceCompatibility = JavaVersion.VERSION_21
+    }
+
+    repositories {
+        mavenCentral()
+    }
+
+    tasks.withType<Test> {
+        useJUnitPlatform()
+    }
+}
+
+// user-service/build.gradle.kts
+plugins {
+    id("org.springframework.boot")
+}
+
+dependencies {
+    implementation(project(":common"))
+    implementation(libs.spring.boot.web)
+    implementation(libs.mapstruct)
+    testImplementation(libs.spring.boot.test)
+}
+```
+
+### Pattern 3: Plugin Configuration for Quality
+
+```xml
+<!-- Maven plugin management in parent POM -->
+<build>
+    <pluginManagement>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.12.1</version>
+                <configuration>
+                    <release>${java.version}</release>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.mapstruct</groupId>
+                            <artifactId>mapstruct-processor</artifactId>
+                            <version>${mapstruct.version}</version>
+                        </path>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                            <version>${lombok.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.jacoco</groupId>
+                <artifactId>jacoco-maven-plugin</artifactId>
+                <version>0.8.11</version>
+                <executions>
+                    <execution>
+                        <goals><goal>prepare-agent</goal></goals>
+                    </execution>
+                    <execution>
+                        <id>report</id>
+                        <phase>verify</phase>
+                        <goals><goal>report</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </pluginManagement>
+</build>
+```
+
+## Anti-Patterns
+
+- **Unmanaged dependency versions**: Declaring versions in each module instead of the parent/BOM. Leads to version conflicts.
+- **Fat parent POM with all dependencies**: Declaring dependencies (not just `dependencyManagement`) in the parent forces all modules to inherit them.
+- **Skipping tests in CI**: `mvn install -DskipTests` hides regressions. Only skip in local exploratory builds.
+- **Build logic in scripts outside the build tool**: Wrapping Maven/Gradle in shell scripts that duplicate what plugins provide.
+
+## Integration Points
+
+- **Spring Boot**: Spring Boot Maven/Gradle plugin handles fat JAR packaging and dev-tools; see `spring-boot-patterns.md`.
+- **JPA**: Annotation processing (Hibernate metamodel, MapStruct) configured in compiler plugin; see `jpa-patterns.md`.
+- **Microservices**: Multi-module layout maps to service boundaries; see `microservices.md`.
+- **CI/CD**: Build tool commands (`mvn verify`, `gradle build`) are the CI pipeline entry point.

package/_gaia/dev/knowledge/java/microservices.md

@@ -0,0 +1,159 @@
+---
+name: Microservices Patterns
+stack: java
+version: "1.0"
+focus: [microservices]
+---
+
+# Microservices Patterns
+
+## Principle
+
+Decompose systems along bounded context boundaries. Each service owns its data, communicates via well-defined APIs (sync) or events (async), and is independently deployable. Use circuit breakers for resilience, saga pattern for distributed transactions, and service discovery for dynamic routing.
+
+## Rationale
+
+Microservices enable independent scaling, deployment, and technology choices per bounded context. However, distributed systems introduce network failures, data consistency challenges, and operational complexity. Circuit breakers prevent cascading failures by failing fast when a downstream service is unhealthy. The saga pattern replaces distributed transactions with a sequence of local transactions and compensating actions. Service discovery eliminates hard-coded URLs.
+
+## Pattern Examples
+
+### Pattern 1: Circuit Breaker with Resilience4j
+
+```java
+@Service
+@RequiredArgsConstructor
+public class PaymentService {
+
+    private final PaymentClient paymentClient;
+
+    @CircuitBreaker(name = "payment", fallbackMethod = "paymentFallback")
+    @TimeLimiter(name = "payment")
+    @Retry(name = "payment")
+    public CompletableFuture<PaymentResult> processPayment(PaymentRequest request) {
+        return CompletableFuture.supplyAsync(
+            () -> paymentClient.charge(request)
+        );
+    }
+
+    private CompletableFuture<PaymentResult> paymentFallback(
+            PaymentRequest request, Throwable ex) {
+        log.warn("Payment service unavailable, queuing: {}", ex.getMessage());
+        return CompletableFuture.completedFuture(
+            PaymentResult.queued(request.orderId())
+        );
+    }
+}
+
+// application.yml
+// resilience4j:
+//   circuitbreaker:
+//     instances:
+//       payment:
+//         sliding-window-size: 10
+//         failure-rate-threshold: 50
+//         wait-duration-in-open-state: 30s
+//   retry:
+//     instances:
+//       payment:
+//         max-attempts: 3
+//         wait-duration: 500ms
+```
+
+### Pattern 2: Saga Pattern (Orchestration)
+
+```java
+// Saga orchestrator — coordinates local transactions across services
+@Service
+@RequiredArgsConstructor
+public class OrderSagaOrchestrator {
+
+    private final OrderService orderService;
+    private final InventoryClient inventoryClient;
+    private final PaymentClient paymentClient;
+
+    @Transactional
+    public OrderResult createOrder(CreateOrderCommand cmd) {
+        // Step 1: Create order (local transaction)
+        var order = orderService.create(cmd);
+
+        try {
+            // Step 2: Reserve inventory (remote call)
+            inventoryClient.reserve(order.getId(), cmd.items());
+
+            try {
+                // Step 3: Process payment (remote call)
+                paymentClient.charge(order.getId(), cmd.total());
+                orderService.confirm(order.getId());
+                return OrderResult.success(order);
+
+            } catch (PaymentException e) {
+                // Compensate Step 2
+                inventoryClient.release(order.getId());
+                orderService.cancel(order.getId(), "Payment failed");
+                return OrderResult.failed(order, e.getMessage());
+            }
+        } catch (InventoryException e) {
+            // Compensate Step 1
+            orderService.cancel(order.getId(), "Insufficient inventory");
+            return OrderResult.failed(order, e.getMessage());
+        }
+    }
+}
+```
+
+### Pattern 3: Event-Driven Communication
+
+```java
+// Publishing domain events
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+
+    private final OrderRepository orderRepository;
+    private final ApplicationEventPublisher eventPublisher;
+
+    @Transactional
+    public Order confirm(Long orderId) {
+        var order = orderRepository.findById(orderId)
+            .orElseThrow(() -> new OrderNotFoundException(orderId));
+        order.setStatus(OrderStatus.CONFIRMED);
+        var saved = orderRepository.save(order);
+
+        // Publish event — listeners can be in-process or forward to Kafka
+        eventPublisher.publishEvent(new OrderConfirmedEvent(
+            saved.getId(), saved.getCustomerId(), saved.getTotal()
+        ));
+        return saved;
+    }
+}
+
+// Event listener — async processing
+@Component
+@RequiredArgsConstructor
+public class NotificationListener {
+
+    private final NotificationService notificationService;
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    @Async
+    public void onOrderConfirmed(OrderConfirmedEvent event) {
+        notificationService.sendOrderConfirmation(
+            event.customerId(), event.orderId()
+        );
+    }
+}
+```
+
+## Anti-Patterns
+
+- **Distributed monolith**: Splitting a monolith into services that still share a database or require synchronous calls for every operation.
+- **Two-phase commit across services**: Distributed transactions do not scale. Use sagas with compensating actions instead.
+- **Chatty inter-service calls**: Multiple fine-grained synchronous calls per request. Batch calls or use async events.
+- **Shared domain models**: Services sharing entity JARs creates tight coupling. Each service defines its own models.
+
+## Integration Points
+
+- **Spring Boot**: Each microservice is a Spring Boot application; see `spring-boot-patterns.md`.
+- **JPA**: Each service owns its database schema; see `jpa-patterns.md` for per-service data modeling.
+- **Build Tools**: Multi-module Maven/Gradle builds manage microservice projects; see `maven-gradle.md`.
+- **Docker**: Services are containerized for deployment; integrate with Docker Compose or Kubernetes.