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)

`:wagoe/permission-registry`: the registry `core.authorization` builds,
behind `IPermissionRegistry`, the scope check of a route (ADR-041 §4) and
the authorization interceptor that runs both (§5).
Read it at the REPL with

  (ports/permissions (get (wagoe.platform.shell.system.wiring/system)
                          :wagoe/permission-registry))

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.

`circuit` names what is being protected: the RPC client passes `rpc:` plus
the service URL, the external adapters their kind and host.

Reading feature flags from the process environment.

`wagoe.core.config.feature-flags` decides what a flag means, given an
environment map. This namespace is the one line that fetches the map, and it
lives in a shell because reading `System/getenv` is I/O — ambient input that
changes the answer without changing the arguments.

Both halves used to be in the core namespace, whose docstring promised no
side effects while five of its functions called `(System/getenv)` in a
convenience arity (BOU-302).

Ring flash in a cookie, not the Ring session: `:session` is the user
module's database session. Unsigned, since only toast text is read back.

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])]}}

Route data may also carry an :interceptors vector; when the routes are
compiled, it becomes :middleware running through this same runner.

Asks the request's router which pages are mounted.

Compiles the application's route data into a Ring handler.

Modules emit Reitit route data and this namespace hands it to Reitit
(ADR-037), so what is left here is behaviour rather than translation:
exception handling, the coercion error shape, the OpenAPI routes, gzip, and
the interceptor stack each route is decorated with.

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: error responses in the one error shape
(`wagoe.platform.core.http.errors`) and health checks.

The pure transformations are in wagoe.platform.core.http.problem-details.

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

Data export and retention over what modules contribute: `:data-export`
exporters and `:retention` policies (`wagoe.platform.ports.privacy`).

Retention is off until `:wagoe/privacy :retention` names a policy, and then
runs as the recurring job `retention-job-type` on `:wagoe/jobs`:

  :wagoe/privacy {:retention          {:user/audit-log {:retain "P2Y"}}
                  :retention-schedule {:cron "0 3 * * *" :zone "UTC"}}

The throwables already sent to the error tracker, so a 5xx that crosses a
service and then the HTTP layer is reported once (BOU-714). Keys are weak:
remembering a throwable does not keep it alive.

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

`authz-report`: the route table as `:wagoe/authorization :enforce` would
judge it, printed without serving. Builds `:wagoe/http-handler` and what it
depends on, never `:wagoe/http-server`, so it binds no port; the database
and the modules still start, as the routes need them, and so do the
migrations a config runs at start.

Assemble an Integrant system from a loaded configuration map.

This is the half of `wagoe.system-config` that is the same in every
application: the components every Wagoe app has (database, HTTP, router,
observability, i18n), the framework modules its config switches on, and the
modules `bb scaffold generate` produced. What is left for the application is
what only it knows — see the generated `config.clj`.

Before BOU-326 this lived in the generated file, 404 lines of it, and a
second copy lived in this repository's own `src/wagoe/system_config.clj`.
Neither copy wired `:wagoe/workflow-db-schema`, so `wagoe add workflow`
produced a module whose tables were never created.

Usage:
  (system-config (config/load-config) {:base-ns "shop"})

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 '[wagoe.system-config :as sys-config])   ; your application's
  (require '[integrant.core :as ig])
  (def cfg (sys-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.

The clock, read once per library rather than once per namespace.

`current-timestamp` was defined identically in `utils.error-handling` and
`interfaces.http.middleware` (BOU-302).

A shell namespace, because reading a clock is the shell's job: core
functions take the instant as an argument.

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