Common connection pool management utilities.

Common database operations - main coordination module.

This namespace serves as the main coordinator for common database
functionality, bringing together specialized modules for different
aspects of database operations that work across all adapter types.

The common functionality has been refactored into specialized namespaces:
- common.connection: Connection pool management with HikariCP
- common.execution: Query execution with logging and error handling
- common.schema: Schema introspection and DDL execution
- common.utils: Database information and convenience functions
- common.core: Main coordination module (this namespace)

Pure query building functions are now in wagoe.platform.core.database.query

This modular structure provides:
- Better organization with focused responsibilities
- Easier maintenance and testing
- Consistent patterns across all database adapters
- Clear separation of concerns

Query execution with I/O, logging, and error handling.

This is part of the imperative shell - it performs database I/O,
manages transactions, and handles side effects like logging.

Common query building and formatting utilities.

Common schema management and DDL utilities.

Common database utilities and information functions.

Configuration-driven database adapter management.

This namespace provides functionality to read database configuration from
config.edn and only load adapters that are marked as :active. This allows
for optimized deployments where only required database drivers are loaded.

Key Features:
- Configuration-driven adapter loading
- Environment-specific database configs
- Graceful handling of inactive adapters
- JDBC driver optimization (only load needed drivers)

Usage:
  (require '[wagoe.platform.shell.adapters.database.config :as db-config])
  
  (db-config/get-active-adapters "dev")     ; Get active adapters for dev env
  (db-config/adapter-active? :postgresql)    ; Check if adapter is active

Configuration-driven database adapter factory.

This namespace provides factory functions that only load database adapters
that are marked as :active in the configuration files. This enables optimized
deployments where only necessary JDBC drivers are loaded and initialized.

Key Features:
- Only loads adapters marked as :active in config.edn
- Graceful error handling for inactive adapters
- Environment-aware adapter loading
- Automatic configuration validation
- JDBC driver optimization

Usage:
  (require '[wagoe.platform.shell.adapters.database.config-factory :as cf])
  
  ;; Load only active adapters for current environment
  (cf/create-active-contexts)
  
  ;; Create specific adapter context from config
  (cf/create-config-context "dev" :wagoe/sqlite)

Factory functions for database adapter creation and configuration.

This namespace provides convenient factory functions for creating database
adapters, data sources, and database contexts. It supports multiple database
types (SQLite, PostgreSQL, MySQL, H2) through a unified configuration interface.

Key Features:
- Database adapter creation from configuration
- Connection pool and datasource management
- Database context creation with adapter + datasource
- Resource management with automatic cleanup
- Configuration validation and error handling

Usage:
  (require '[wagoe.platform.shell.adapters.database.factory :as dbf])
  
  (def ctx (dbf/db-context {:adapter :sqlite :database-path "./app.db"}))
  (db/execute-query! ctx {:select [:*] :from [:users]})

H2 connection management utilities.

H2 database adapter - main entry point implementing the DBAdapter protocol.

This namespace serves as the main entry point for H2 database
functionality, implementing the DBAdapter protocol and coordinating
specialized modules for different aspects of H2 operations.

The adapter has been refactored into 5 specialized namespaces:
- h2.connection: Connection management and H2-specific settings
- h2.query: H2-specific query building and boolean handling
- h2.metadata: Table introspection and schema information
- h2.utils: Utility functions and DDL helpers
- h2.core: Main adapter implementation and coordination (this namespace)

Key Features:
- PostgreSQL compatibility mode for easier migration
- In-memory databases for fast testing
- File-based databases for development
- Standard SQL features with good performance
- Native boolean support (no conversion needed)

H2-Specific Optimizations:
- PostgreSQL compatibility mode by default
- Proper timezone handling
- Case-insensitive identifiers for compatibility
- Optimized connection pool settings for embedded usage

H2 metadata and table introspection utilities.

H2 query building utilities.

H2 utility functions and DDL helpers.

Example integration showing how to use the multi-database adapter system.

This namespace demonstrates how to:
- Load environment-specific configurations
- Initialize database adapters based on active configurations
- Use the initialized adapters for database operations
- Handle multiple active databases simultaneously

MySQL connection management utilities.

MySQL database adapter implementing the DBAdapter protocol.

This namespace provides MySQL-specific functionality for production
database deployments. MySQL is a widely-used, reliable relational
database system with good performance and broad compatibility.

Key Features:
- LIKE-based string matching (case-insensitive by default)
- Boolean values stored as TINYINT(1)
- Robust connection handling with proper SSL configuration
- Timezone and SQL mode configuration for consistency
- Connection pool tuning for server workloads

The adapter delegates to specialized modules for:
- Connection management (mysql.connection)
- Query building (mysql.query)
- Metadata operations (mysql.metadata)
- Utility functions (mysql.utils)

MySQL metadata and table introspection utilities.

MySQL query building utilities.

MySQL utility functions and DDL helpers.

PostgreSQL connection management utilities.

PostgreSQL database adapter implementing the DBAdapter protocol.

This namespace provides PostgreSQL-specific functionality for production
database deployments. PostgreSQL is a powerful, open-source relational
database system with advanced features and excellent performance.

Key Features:
- Case-insensitive string matching with ILIKE
- Native boolean support
- Advanced SQL features and data types
- Robust transaction support
- Excellent performance and scalability

The adapter delegates to specialized modules for:
- Connection management (postgresql.connection)
- Query building (postgresql.query)
- Metadata operations (postgresql.metadata)
- Utility functions (postgresql.utils)

PostgreSQL metadata and table introspection utilities.

PostgreSQL query building utilities.

PostgreSQL utility functions and DDL helpers.

Protocol defining the common interface for database adapters.

This protocol abstracts database-specific behavior while allowing 
common database operations to be implemented in a shared core namespace.
Each database type (SQLite, PostgreSQL, MySQL, H2) implements this 
protocol to provide database-specific functionality.

Design Philosophy:
- Keep protocol narrow - prefer common behavior in core
- Only include methods that differ between databases
- Database-agnostic operations belong in core namespace
- Type conversions use shared utilities where possible

SQLite connection management utilities.

SQLite database adapter - main entry point implementing the DBAdapter protocol.

This namespace serves as the main entry point for SQLite database
functionality, implementing the DBAdapter protocol and coordinating
specialized modules for different aspects of SQLite operations.

The adapter has been refactored into 5 specialized namespaces:
- sqlite.connection: Connection management and PRAGMA settings
- sqlite.query: SQLite-specific query building and boolean conversion
- sqlite.metadata: Table introspection and schema information
- sqlite.utils: Utility functions and DDL helpers
- sqlite.core: Main adapter implementation and coordination (this namespace)

Key Features:
- SQLite-optimized connection management with PRAGMAs
- Database-specific query building (LIKE for strings, boolean->int)
- Schema introspection via sqlite_master and PRAGMA table_info
- Integration with shared type conversion utilities

SQLite-Specific Optimizations:
- Text-based UUID and timestamp storage
- Boolean as integer (0/1) representation
- WAL mode, synchronous settings, and other PRAGMAs
- Connection pool tuning for embedded usage

This namespace maintains backward compatibility by serving as the main
entry point that other code can require directly.

SQLite metadata and table introspection utilities.

SQLite query building utilities.

SQLite utility functions and DDL helpers.

Dynamic JDBC driver loading based on active database configurations.

This namespace provides configuration-driven driver loading that eliminates
the need to coordinate between configuration files and command-line aliases.
Drivers are loaded dynamically based on which databases are marked as :active
in the configuration files.

Key Features:
- Single source of truth: configuration files control everything
- Clear error messages when drivers are missing
- Automatic driver detection from active databases
- No command-line alias coordination required

Usage:
  (require '[wagoe.platform.shell.adapters.database.utils.driver-loader :as dl])

  ;; Load drivers for active databases in current environment
  (dl/load-required-drivers!)

  ;; Load drivers for specific environment
  (dl/load-drivers-for-environment! "dev")

Schema-to-DDL generation utilities for database adapters.

This namespace provides utilities for generating database DDL statements
from Malli schema definitions. It handles:
- Column type mapping based on database dialect
- Table creation with constraints
- Index generation from schema analysis
- Cross-database compatibility

Key Features:
- Uses Malli schemas as canonical source of truth
- Database-specific column type mapping
- Foreign key and unique constraint generation
- Automatic index creation based on field patterns

Usage:
  (require '[wagoe.platform.shell.adapters.database.utils.schema :as schema])

  (schema/generate-table-ddl ctx "users" some-malli-schema)
  (schema/initialize-tables-from-schemas! ctx schema-map)

File system adapter implementation for local filesystem operations.

Provides concrete implementation of IFileSystemAdapter protocol
using Java I/O for local filesystem access.

Protocol defining the common interface for filesystem adapters.

This protocol abstracts filesystem operations to enable testing
with in-memory implementations and support different storage
backends (local FS, cloud storage, etc.).

Design Philosophy:
- Protocol defines generic file operations
- Implementations handle specific storage backends
- Enables testing without actual filesystem I/O
- Supports multiple storage strategies (local, cloud, in-memory)

CLI commands for database migration management.

Usage:
  clojure -M -m wagoe.platform.shell.database.cli-migrations [command] [options]

Commands:
  migrate         - Run all pending migrations
  rollback        - Roll back the last migration
  status          - Show migration status
  create <name>   - Create a new migration file
  reset           - Reset database (rollback all and reapply)
  init            - Initialize migration system

CLI entry point for database seeding.

Usage:
  clojure -M -m wagoe.platform.shell.database.cli-seed [path]

Defaults to resources/seeds/dev.edn. Invoked by `bb db:seed`, which cannot
open a JDBC connection itself (libs/tools is pure Babashka), so it shells out
here — the same arrangement `bb migrate` uses for cli-migrations.

Database migration management using Migratus.

This namespace provides functions to manage database schema migrations:
- Run pending migrations (up)
- Rollback migrations (down)
- Check migration status
- Create new migrations

Migrations are discovered from the application's `migrations/` directory and
from any library manifests published on the classpath.

Loads a seed file into the active database.

The pure parts — validation, kebab->snake conversion, plan building — live in
`wagoe.platform.core.database.seed`. This namespace owns the I/O: reading the
file, acquiring the datasource, and executing the inserts.

Validation functions for database contexts and configurations.

Context validation functions check data structure conformity including
protocol satisfaction, which requires access to the DBAdapter protocol
from the shell adapters layer.

HTTP interceptor pipeline for Ring request/response processing.

This namespace provides an HTTP-specific interceptor chain that runs over Ring handlers,
giving Pedestal-like enter/leave/error semantics while maintaining Ring compatibility.

Key Benefits:
- Consistent cross-layer observability (HTTP → service → persistence)
- Declarative per-route policies (auth, rate-limit, auditing)
- Clean separation of concerns (routing vs cross-cutting logic)
- Reusable interceptor components across routes

HTTP Context Model:
{:request       Ring request map
 :response      Ring response map (built up through pipeline)
 :route         Route metadata from Reitit match
 :path-params   Extracted path parameters
 :query-params  Extracted query parameters
 :system        Observability services {:logger :metrics-emitter :error-reporter}
 :attrs         Additional attributes set by interceptors
 :correlation-id Unique request ID
 :started-at    Request start timestamp}

Interceptor Shape:
{:name   :my-interceptor
 :enter  (fn [context] ...) ; Process request, modify context
 :leave  (fn [context] ...) ; Process response, modify context
 :error  (fn [context] ...)} ; Handle exceptions, produce safe response

Usage:
;; As Ring middleware (global)
(def handler
  (-> app-handler
      (wrap-http-interceptors [logging metrics error-reporting])))

;; Per-route via Reitit :middleware
{:get {:handler my-handler
       :middleware [(interceptor-middleware [auth rate-limit])]}}

Integration with Normalized Routes:
- Normalized routes can specify :interceptors vector
- Reitit adapter translates :interceptors → :middleware with this runner

Reitit router adapter - converts normalized route specs to Reitit routing.

This adapter implements the IRouter protocol to translate framework-agnostic
normalized route specifications into Reitit-specific route definitions.

Ring+Jetty server adapter - manages HTTP server lifecycle using Ring and Jetty.

This adapter implements the IHttpServer protocol to start and stop Jetty-based
HTTP servers with Ring handlers.

HTTP API versioning support - wraps routes with version prefixes and headers.

SIDE EFFECTS:
- Route transformation
- Response header modification
- Logging

Provides URL-based versioning (/api/v1/users, /api/v2/users) with:
- Automatic version prefix wrapping
- Version header injection (X-API-Version, X-API-Latest, X-API-Deprecated)
- Backward compatibility (/api/users → /api/v1/users redirect)
- Multiple version support concurrently

Universal interceptors for cross-cutting concerns.

These interceptors handle common infrastructure concerns like logging,
metrics, error handling, and context management across all modules.

CLI middleware for command execution with enhanced error context (imperative shell).

This namespace provides reusable CLI middleware that can be used across
different modules and applications for consistent observability and
error handling in command-line interfaces.

Middleware functions handle CLI boundaries: command execution interception,
context generation, logging, and exception handling with enhanced context
preservation for debugging.

Features:
- Command correlation ID generation
- Tenant and user context extraction from config/environment
- Structured command execution logging with observability context
- Command timing and error reporting with enhanced context
- Error reporting breadcrumb integration

Common HTTP utilities and RFC 7807 Problem Details support.

This namespace provides common HTTP functionality including standardized
error responses following RFC 7807 Problem Details specification and
other utility functions used across HTTP interfaces.

Pure problem details transformations are now in wagoe.platform.core.http.problem-details

HTTP middleware for web applications (imperative shell).

This namespace provides reusable HTTP middleware that can be used across
different modules and applications. It follows RFC standards and best
practices for web API development.

Middleware functions handle I/O boundaries: request/response interception,
logging, and exception handling.

Features:
- Request correlation ID management
- Tenant and user context extraction
- Multi-tenant request processing with schema switching
- Structured request/response logging with observability context
- RFC 7807 Problem Details for error responses (via core)
- Generic exception handling middleware
- Error reporting breadcrumb integration

Multi-Tenant Middleware:
See wagoe.tenant.shell.tenant-middleware for:
- Tenant resolution (subdomain, JWT, headers)
- PostgreSQL schema switching per request
- Tenant caching with configurable TTL
- Combined middleware for simplified integration

Common HTTP routing infrastructure and standard endpoints.

This namespace provides the foundational routing structure for the application,
including standard endpoints like health checks and API documentation, along
with infrastructure for injecting module-specific routes.

Features:
- Health check endpoints
- OpenAPI/Swagger documentation routes
- Module route injection system
- Common route middleware configuration
- Standardized route structure

Module registry and composition helpers for the Wagoe shell.

This namespace provides utilities to:
- Determine which modules are enabled based on configuration.
- Compose route definitions from multiple modules.
- Dispatch CLI commands to module-specific runners.

For now, only the `:user` module is supported.

Shell layer cursor encoding/decoding for cursor-based pagination.

SIDE EFFECTS:
- JSON encoding/decoding
- Base64 encoding/decoding
- Exception throwing on invalid cursors

Cursors are opaque tokens that encode:
- Item ID (for stable ordering)
- Sort field value (for comparison)
- Sort direction (asc/desc)
- Optional timestamp (for expiry)

Format: Base64(JSON({:id ... :sort-value ... :sort-field ... :sort-direction ...}))

Shell layer RFC 5988 Link header generation for pagination.

RFC 5988: Web Linking
https://datatracker.ietf.org/doc/html/rfc5988

SIDE EFFECTS:
- String building and URL encoding
- Logging

Link headers provide hypermedia controls for pagination navigation.
They allow clients to discover next, prev, first, and last pages without
parsing response bodies.

Format:
Link: </api/v1/users?limit=20&offset=20>; rel="next",
      </api/v1/users?limit=20&offset=0>; rel="first",
      </api/v1/users?limit=20&offset=980>; rel="last"

Supported Relations:
- first: First page of results
- last: Last page of results (offset pagination only)
- prev: Previous page
- next: Next page
- self: Current page

Persistence-level interceptors for database operations.

This namespace provides interceptor pipelines specifically designed for persistence layer operations,
eliminating manual observability calls and providing consistent error handling, logging, and 
error reporting across all database operations.

Key Benefits:
- Eliminates 40+ manual observability calls from persistence methods
- Provides consistent database error handling patterns
- Automatic timing and logging for all database operations
- Single point of control for persistence-level cross-cutting concerns

Usage:
  (execute-persistence-operation 
    :find-user-by-id 
    {:user-id user-id}
    db-impl-fn
    {:system system})

Architecture:
- Persistence interceptors wrap database operations
- Context carries operation metadata and database context
- Interceptors handle all database-related cross-cutting concerns automatically

Circuit-breaker state, kept where every replica can see it.

A breaker in one JVM's atom protects that JVM. With N replicas a failing
service gets N breakers, each of which has to trip on its own, so it still
takes N times the load — and when the window elapses, all N probe at once,
which is the stampede the breaker was meant to prevent. Keeping the state in
the cache port makes it one breaker.

The cache adapter decides how far that goes: Redis shares it across
replicas, the in-memory one does not. That is the same trade the rate
limiter makes, and it is a property of the adapter rather than of this
namespace.

Generic remote-port adapter: implement any module protocol over HTTP.

Cross-module calls go through a protocol, so slicing a module into its own
process needs one thing the codebase did not have — an implementation of
that protocol that makes a network call. This builds one for an arbitrary
protocol, so the caller keeps calling `(ports/create-checkout-session svc …)`
and does not learn that the answer now comes over a socket (BOU-90).

Modelled on libs/external's outbound adapters: clj-http, `:throw-exceptions
false`, errors as data rather than exceptions.

FC/IS: shell. The wire contract is pure and lives in
`wagoe.platform.core.rpc`.

Expose a module's protocol over HTTP, so another process can call it.

The counterpart to `…rpc.client`: that turns protocol calls into requests,
this turns requests back into protocol calls against the local
implementation. Together they are what lets a module run as its own service
without its callers changing (BOU-90).

FC/IS: shell. The envelope contract is pure and lives in
`wagoe.platform.core.rpc`.

Service-level interceptors for business logic operations.

This namespace provides interceptor pipelines specifically designed for service layer operations,
eliminating manual observability calls and providing consistent error handling, logging, metrics,
and error reporting across all service methods.

Key Benefits:
- Eliminates 50+ manual observability calls from service methods
- Provides consistent error handling and reporting patterns
- Automatic timing, logging, and metrics collection
- Single point of control for service-level cross-cutting concerns

Usage:
  (execute-service-operation 
    :register-user 
    {:user-data user-data :tenant-id tenant-id}
    service-impl-fn
    {:system system})

Architecture:
- Service interceptors wrap pure business logic functions
- Context carries operation metadata and observability services
- Interceptors handle all cross-cutting concerns automatically

Integrant system lifecycle management for Wagoe application.

This namespace defines init-key and halt-key! multimethods for all
system components, providing proper lifecycle management and dependency
injection for the entire application.

Components:
- :wagoe/db-context - Database connection pool and adapter
- :wagoe/user-repository - User data persistence
- :wagoe/session-repository - Session data persistence
- :wagoe/user-service - User business logic orchestration
- :wagoe/logging - Structured logging and audit trails
- :wagoe/metrics - Application and business metrics collection
- :wagoe/error-reporting - Error tracking and alerting
- :wagoe/http-handler - HTTP request routing and handling
- :wagoe/http-server - Jetty HTTP server

Usage:
  (require '[wagoe.config :as config])
  (require '[integrant.core :as ig])
  (def cfg (config/ig-config (config/load-config)))
  (def system (ig/init cfg))
  (ig/halt! system)

Error handling utilities for enhanced context preservation and structured error responses.

This namespace provides middleware and utilities for capturing rich error context
across HTTP and CLI interfaces, enabling better debugging and observability.

Port management utilities for development environment.

Provides port conflict resolution, environment detection,
and intelligent port allocation for different development scenarios.

Stateful in-process registry of validation rules.

Holds mutable process state (the rule registry and execution-tracking atoms),
so it lives in the shell — the functional core
(wagoe.core.validation.registry) keeps only the pure rule-shape and
conflict helpers. Provides registration, lookup, and coverage tracking for
validation rules across modules.

Rule format: see wagoe.core.validation.registry.

Shared helpers for table sorting, pagination, and basic search filters across web UIs.

This namespace centralizes parsing of table-related query parameters so that
all modules use the same semantics for sorting and paging. It also provides
small helpers for generic search/filter parameters that feature modules can
interpret according to their own needs.

TableQuery shape:
{:sort      :name        ; keyword column identifier (or default)
 :dir       :asc         ; :asc or :desc
 :page      1            ; 1-based page index
 :page-size 20           ; items per page
 :offset    0            ; derived from page/page-size
 :limit     20}         ; derived from page-size