fix(auth): standard OIDC RP behavior — auto-redirect and drop prompt=login

When OIDC is the primary auth method, the login page now auto-redirects
to the OIDC provider's authorization endpoint instead of showing an
intermediate "Sign in with SSO" button. The `prompt=login` parameter
that forced re-authentication is removed — the provider manages its own
session state. If the user already has a session (e.g. from the SaaS
platform sharing the same Logto instance), the provider issues a code
without showing a login form, enabling seamless SSO.

Admin recovery via ?local is unchanged.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/rules/app-classes.md

@@ -5,7 +5,7 @@ paths:
 
 # App Module Key Classes
 
-`cameleer-server-app/src/main/java/com/cameleer/server/app/`
+`cameleer-server-app/src/main/java/io/cameleer/server/app/`
 
 ## URL taxonomy
 
@@ -27,6 +27,7 @@ These paths intentionally stay flat (no `/environments/{envSlug}` prefix). Every
 | `/api/v1/catalog`, `/api/v1/catalog/{applicationId}` | Cross-env discovery is the purpose. Env is an optional filter via `?environment=`. |
 | `/api/v1/executions/{execId}`, `/processors/**` | Exchange IDs are globally unique; permalinks. |
 | `/api/v1/diagrams/{contentHash}/render`, `POST /api/v1/diagrams/render` | Content-addressed or stateless. |
+| `/api/v1/artifacts/{appVersionId}` | Init-container artifact pull. HMAC-signed URL is the auth — no JWT context. |
 | `/api/v1/alerts/notifications/{id}/retry` | Notification IDs are globally unique; no env routing needed. |
 | `/api/v1/auth/**` | Pre-auth; no env context exists. |
 | `/api/v1/health`, `/prometheus`, `/api-docs/**`, `/swagger-ui/**` | Server metadata. |
@@ -53,18 +54,18 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 
 ### Env-scoped (user-facing data & config)
 
-- `AppController` — `/api/v1/environments/{envSlug}/apps`. GET list / POST create / GET `{appSlug}` / DELETE `{appSlug}` / GET `{appSlug}/versions` / POST `{appSlug}/versions` (JAR upload) / PUT `{appSlug}/container-config`. App slug uniqueness is per-env (`(env, app_slug)` is the natural key). `CreateAppRequest` body has no env (path), validates slug regex.
+- `AppController` — `/api/v1/environments/{envSlug}/apps`. GET list / POST create / GET `{appSlug}` / DELETE `{appSlug}` / GET `{appSlug}/versions` / POST `{appSlug}/versions` (JAR upload) / PUT `{appSlug}/container-config` / GET `{appSlug}/dirty-state` (returns `DirtyStateResponse{dirty, lastSuccessfulDeploymentId, differences}` — compares current JAR+config against last RUNNING deployment snapshot; dirty=true when no snapshot exists). App slug uniqueness is per-env (`(env, app_slug)` is the natural key). `CreateAppRequest` body has no env (path), validates slug regex. Injects `DirtyStateCalculator` bean (registered in `RuntimeBeanConfig`, requires `ObjectMapper` with `JavaTimeModule`).
-- `DeploymentController` — `/api/v1/environments/{envSlug}/apps/{appSlug}/deployments`. GET list / POST create (body `{ appVersionId }`) / POST `{id}/stop` / POST `{id}/promote` (body `{ targetEnvironment: slug }` — target app slug must exist in target env) / GET `{id}/logs`.
+- `DeploymentController` — `/api/v1/environments/{envSlug}/apps/{appSlug}/deployments`. GET list / POST create (body `{ appVersionId }`) / POST `{id}/stop` / POST `{id}/promote` (body `{ targetEnvironment: slug }` — target app slug must exist in target env) / GET `{id}/logs`. All lifecycle ops (`POST /` deploy, `POST /{id}/stop`, `POST /{id}/promote`) audited under `AuditCategory.DEPLOYMENT`. Action codes: `deploy_app`, `stop_deployment`, `promote_deployment`. Acting user resolved via the `user:` prefix-strip convention; both SUCCESS and FAILURE branches write audit rows. `created_by` (TEXT, nullable) populated from `SecurityContextHolder` and surfaced on the `Deployment` DTO.
-- `ApplicationConfigController` — `/api/v1/environments/{envSlug}`. GET `/config` (list), GET/PUT `/apps/{appSlug}/config`, GET `/apps/{appSlug}/processor-routes`, POST `/apps/{appSlug}/config/test-expression`. PUT also pushes `CONFIG_UPDATE` to LIVE agents in this env.
+- `ApplicationConfigController` — `/api/v1/environments/{envSlug}`. GET `/config` (list), GET/PUT `/apps/{appSlug}/config`, GET `/apps/{appSlug}/processor-routes`, POST `/apps/{appSlug}/config/test-expression`. PUT accepts `?apply=staged|live` (default `live`). `live` saves to DB and pushes `CONFIG_UPDATE` SSE to live agents in this env (existing behavior); `staged` saves to DB only, skipping the SSE push — used by the unified app deployment page. Audit action is `stage_app_config` for staged writes, `update_app_config` for live. Invalid `apply` values return 400.
 - `AppSettingsController` — `/api/v1/environments/{envSlug}`. GET `/app-settings` (list), GET/PUT/DELETE `/apps/{appSlug}/settings`. ADMIN/OPERATOR only.
-- `SearchController` — `/api/v1/environments/{envSlug}`. GET `/executions`, POST `/executions/search`, GET `/stats`, `/stats/timeseries`, `/stats/timeseries/by-app`, `/stats/timeseries/by-route`, `/stats/punchcard`, `/attributes/keys`, `/errors/top`.
+- `SearchController` — `/api/v1/environments/{envSlug}`. GET `/executions`, POST `/executions/search`, GET `/stats`, `/stats/timeseries`, `/stats/timeseries/by-app`, `/stats/timeseries/by-route`, `/stats/punchcard`, `/attributes/keys`, `/errors/top`. GET `/executions` accepts repeat `attr` query params: `attr=order` (key-exists), `attr=order:47` (exact), `attr=order:4*` (wildcard — `*` maps to SQL LIKE `%`). First `:` splits key/value; later colons stay in the value. Invalid keys → 400. POST `/executions/search` accepts the same filters via `SearchRequest.attributeFilters` in the body.
-- `LogQueryController` — GET `/api/v1/environments/{envSlug}/logs` (filters: source (multi, comma-split, OR-joined), level (multi, comma-split, OR-joined), application, agentId, exchangeId, logger, q, time range; sort asc/desc). Cursor-paginated, returns `{ data, nextCursor, hasMore, levelCounts }`; cursor is base64url of `"{timestampIso}|{insert_id_uuid}"` — same-millisecond tiebreak via the `insert_id` UUID column on `logs`.
+- `LogQueryController` — GET `/api/v1/environments/{envSlug}/logs` (filters: source (multi, comma-split, OR-joined), level (multi, comma-split, OR-joined), application, agentId, exchangeId, logger, q, time range, instanceIds (multi, comma-split, AND-joined as WHERE instance_id IN (...) — used by the Checkpoint detail drawer to scope logs to a deployment's replicas); sort asc/desc). Cursor-paginated, returns `{ data, nextCursor, hasMore, levelCounts }`; cursor is base64url of `"{timestampIso}|{insert_id_uuid}"` — same-millisecond tiebreak via the `insert_id` UUID column on `logs`.
 - `RouteCatalogController` — GET `/api/v1/environments/{envSlug}/routes` (merged route catalog from registry + ClickHouse; env filter unconditional).
 - `RouteMetricsController` — GET `/api/v1/environments/{envSlug}/routes/metrics`, GET `/api/v1/environments/{envSlug}/routes/metrics/processors`.
 - `AgentListController` — GET `/api/v1/environments/{envSlug}/agents` (registered agents with runtime metrics, filtered to env).
 - `AgentEventsController` — GET `/api/v1/environments/{envSlug}/agents/events` (lifecycle events; cursor-paginated, returns `{ data, nextCursor, hasMore }`; order `(timestamp DESC, insert_id DESC)`; cursor is base64url of `"{timestampIso}|{insert_id_uuid}"` — `insert_id` is a stable UUID column used as a same-millisecond tiebreak).
 - `AgentMetricsController` — GET `/api/v1/environments/{envSlug}/agents/{agentId}/metrics` (JVM/Camel metrics). Rejects cross-env agents (404) as defence-in-depth.
-- `DiagramRenderController` — GET `/api/v1/environments/{envSlug}/apps/{appSlug}/routes/{routeId}/diagram` (env-scoped lookup). Also GET `/api/v1/diagrams/{contentHash}/render` (flat — content hashes are globally unique).
+- `DiagramRenderController` — GET `/api/v1/environments/{envSlug}/apps/{appSlug}/routes/{routeId}/diagram` returns the most recent diagram for (app, env, route) via `DiagramStore.findLatestContentHashForAppRoute`. Registry-independent — routes whose publishing agents were removed still resolve. Also GET `/api/v1/diagrams/{contentHash}/render` (flat — content hashes are globally unique), the point-in-time path consumed by the exchange viewer via `ExecutionDetail.diagramContentHash`.
 - `AlertRuleController` — `/api/v1/environments/{envSlug}/alerts/rules`. GET list / POST create / GET `{id}` / PUT `{id}` / DELETE `{id}` / POST `{id}/enable` / POST `{id}/disable` / POST `{id}/render-preview` / POST `{id}/test-evaluate`. OPERATOR+ for mutations, VIEWER+ for reads. CRITICAL: attribute keys in `ExchangeMatchCondition.filter.attributes` are validated at rule-save time against `^[a-zA-Z0-9._-]+$` — they are later inlined into ClickHouse SQL. `AgentLifecycleCondition` is allowlist-only — the `AgentLifecycleEventType` enum (REGISTERED / RE_REGISTERED / DEREGISTERED / WENT_STALE / WENT_DEAD / RECOVERED) plus the record compact ctor (non-empty `eventTypes`, `withinSeconds ≥ 1`) do the validation; custom agent-emitted event types are tracked in backlog issue #145. Webhook validation: verifies `outboundConnectionId` exists and `isAllowedInEnvironment`. Null notification templates default to `""` (NOT NULL constraint). Audit: `ALERT_RULE_CHANGE`.
 - `AlertController` — `/api/v1/environments/{envSlug}/alerts`. GET list (inbox filtered by userId/groupIds/roleNames via `InAppInboxQuery`; optional multi-value `state`, `severity`, tri-state `acked`, tri-state `read` query params; soft-deleted rows always excluded) / GET `/unread-count` / GET `{id}` / POST `{id}/ack` / POST `{id}/read` / POST `/bulk-read` / POST `/bulk-ack` (VIEWER+) / DELETE `{id}` (OPERATOR+, soft-delete) / POST `/bulk-delete` (OPERATOR+) / POST `{id}/restore` (OPERATOR+, clears `deleted_at`). `requireLiveInstance` helper returns 404 on soft-deleted rows; `restore` explicitly fetches regardless of `deleted_at`. `BulkIdsRequest` is the shared body for bulk-read/ack/delete (`{ instanceIds }`). `AlertDto` includes `readAt`; `deletedAt` is intentionally NOT on the wire. Inbox SQL: `? = ANY(target_user_ids) OR target_group_ids && ? OR target_role_names && ?` — requires at least one matching target (no broadcast concept).
 - `AlertSilenceController` — `/api/v1/environments/{envSlug}/alerts/silences`. GET list / POST create / DELETE `{id}`. 422 if `endsAt <= startsAt`. OPERATOR+ for mutations, VIEWER+ for list. Audit: `ALERT_SILENCE_CHANGE`.
@@ -72,7 +73,7 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 
 ### Env admin (env-slug-parameterized, not env-scoped data)
 
-- `EnvironmentAdminController` — `/api/v1/admin/environments`. GET list / POST create / GET `{envSlug}` / PUT `{envSlug}` / DELETE `{envSlug}` / PUT `{envSlug}/default-container-config` / PUT `{envSlug}/jar-retention`. Slug immutable — PUT body has no slug field; any slug supplied is dropped by Jackson. Slug validated on POST.
+- `EnvironmentAdminController` — `/api/v1/admin/environments`. GET list / POST create / GET `{envSlug}` / PUT `{envSlug}` / DELETE `{envSlug}` / PUT `{envSlug}/default-container-config` / PUT `{envSlug}/jar-retention`. Slug immutable — PUT body has no slug field; any slug supplied is dropped by Jackson. Slug validated on POST. `UpdateEnvironmentRequest` carries `color` (nullable); unknown values rejected with 400 via `EnvironmentColor.isValid`. Null/absent color preserves the existing value.
 
 ### Agent-only (JWT-authoritative, intentionally flat)
 
@@ -102,26 +103,35 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 - `OutboundConnectionAdminController` — `/api/v1/admin/outbound-connections`. GET list / POST create / GET `{id}` / PUT `{id}` / DELETE `{id}` / POST `{id}/test` / GET `{id}/usage`. RBAC: list/get/usage ADMIN|OPERATOR; mutations + test ADMIN.
 - `SensitiveKeysAdminController` — GET/PUT `/api/v1/admin/sensitive-keys`. GET returns 200 or 204 if not configured. PUT accepts `{ keys: [...] }` with optional `?pushToAgents=true`. Fan-out iterates every distinct `(application, environment)` slice — intentional global baseline + per-env overrides.
 - `ClaimMappingAdminController` — CRUD `/api/v1/admin/claim-mappings`, POST `/test`.
-- `LicenseAdminController` — GET/POST `/api/v1/admin/license`.
+- `LicenseAdminController` — GET/POST `/api/v1/admin/license`. ADMIN only. GET returns `{state, invalidReason, envelope, lastValidatedAt?}` — the raw token is deliberately omitted; only the parsed `LicenseInfo` envelope is exposed. POST delegates to `LicenseService.install(token, userId, "api")` (acting userId resolved via the `user:` prefix-strip convention) — install/replace/reject all flow through `LicenseService` so audit, persistence, and `LicenseChangedEvent` publishing are uniform.
+- `LicenseUsageController` — GET `/api/v1/admin/license/usage`. Returns license `state`, `expiresAt`/`daysRemaining`/`gracePeriodDays`/`tenantId`/`label`/`lastValidatedAt`, the `LicenseMessageRenderer.forState(...)` message, and a `limits[]` array (`{key, current, cap, source}`) covering every effective-limits key. `source` is `"license"` when the cap came from the license override map, `"default"` otherwise. `max_agents` reads from `AgentRegistryService.liveCount()`; all other counts come from `LicenseUsageReader.snapshot()`.
 - `ThresholdAdminController` — CRUD `/api/v1/admin/thresholds`.
 - `AuditLogController` — GET `/api/v1/admin/audit`.
 - `RbacStatsController` — GET `/api/v1/admin/rbac/stats`.
 - `UsageAnalyticsController` — GET `/api/v1/admin/usage` (ClickHouse `usage_events`).
 - `ClickHouseAdminController` — GET `/api/v1/admin/clickhouse/**` (conditional on `infrastructureendpoints` flag).
 - `DatabaseAdminController` — GET `/api/v1/admin/database/**` (conditional on `infrastructureendpoints` flag).
+- `ServerMetricsAdminController` — `/api/v1/admin/server-metrics/**`. GET `/catalog`, GET `/instances`, POST `/query`. Generic read API over the `server_metrics` ClickHouse table so SaaS dashboards don't need direct CH access. Delegates to `ServerMetricsQueryStore` (impl `ClickHouseServerMetricsQueryStore`). Visibility matches ClickHouse/Database admin: `@ConditionalOnProperty(infrastructureendpoints, matchIfMissing=true)` + class-level `@PreAuthorize("hasRole('ADMIN')")`. Validation: metric/tag regex `^[a-zA-Z0-9._]+$`, statistic regex `^[a-z_]+$`, `to - from ≤ 31 days`, stepSeconds ∈ [10, 3600], response capped at 500 series. `IllegalArgumentException` → 400. `/query` supports `raw` + `delta` modes (delta does per-`server_instance_id` positive-clipped differences, then aggregates across instances). Derived `statistic=mean` for timers computes `sum(total|total_time)/sum(count)` per bucket.
+
+### Auth (flat)
+
+- `UiAuthController` — `/api/v1/auth` (login, refresh, me, logout). Local username/password against env-var admin or DB BCrypt hash. Lockout after 5 failed attempts. `POST /logout` is permitAll — controller resolves the user from the access token if present, bumps `users.token_revoked_before = now().plusMillis(1)` to invalidate all outstanding refresh + access tokens (enforced by `JwtAuthenticationFilter`), audits `AuditCategory.AUTH / logout`, returns 204. Best-effort: 204 also when called without a token so the SPA's logout never fails on already-expired sessions. The +1ms guards against same-millisecond races (JWT `iat` is ms-quantised, filter check is strict `isBefore`).
+- `OidcAuthController` — `/api/v1/auth/oidc` (config, callback). Code → token exchange. Roles via custom JWT claim, claim mapping rules, or default roles.
+- `AuthCapabilitiesController` — `GET /api/v1/auth/capabilities` (unauthenticated). Reports `{oidc:{enabled, providerName, primary}, localAccounts:{enabled, adminRecoveryOnly}}` so the SPA renders the login page deterministically. `oidc.primary == oidc.enabled`; `localAccounts.adminRecoveryOnly == oidc.primary`. `providerName` is best-effort label via `OidcProviderNameDeriver` (Logto / Keycloak / Auth0 / Okta / Single Sign-On). The SPA hides the local form behind `?local` when `adminRecoveryOnly` is true.
 
 ### Other (flat)
 
 - `DetailController` — GET `/api/v1/executions/{executionId}` + processor snapshot endpoints.
 - `MetricsController` — exposes `/api/v1/metrics` and `/api/v1/prometheus` (server-side Prometheus scrape endpoint).
+- `ArtifactDownloadController` — GET `/api/v1/artifacts/{appVersionId}?exp&sig`. HMAC-signed URL is the auth (permitAll'd in `SecurityConfig`); validates via `ArtifactDownloadTokenSigner`. Streams the artifact via `ArtifactStore.get(coords)` with content type `application/java-archive`. Hit by the `cameleer-runtime-loader` init container at deploy time. 401 on bad sig, 404 on missing version, 200 on success.
 
 ## runtime/ — Docker orchestration
 
-- `DockerRuntimeOrchestrator` — implements RuntimeOrchestrator; Docker Java client (zerodep transport), container lifecycle
+- `DockerRuntimeOrchestrator` — implements RuntimeOrchestrator; Docker Java client (zerodep transport), container lifecycle. **`startContainer` is a 2-phase op**: per-replica named volume → `cameleer-runtime-loader` init container fetches the JAR via signed URL → main container starts with the volume mounted RO at `/app/jars`. Both containers get `cap_drop ALL`, `no-new-privileges`, `apparmor=docker-default`, readonly rootfs, pids=512, `/tmp` tmpfs (no `noexec`), and `userns_mode=host:1000:65536`. Volume cleanup deterministic via `removeContainer` deriving the volume name from the inspected container.
-- `DeploymentExecutor` — @Async staged deploy: PRE_FLIGHT -> PULL_IMAGE -> CREATE_NETWORK -> START_REPLICAS -> HEALTH_CHECK -> SWAP_TRAFFIC -> COMPLETE. Container names are `{tenantId}-{envSlug}-{appSlug}-{replicaIndex}` (globally unique on Docker daemon). Sets per-replica `CAMELEER_AGENT_INSTANCEID` env var to `{envSlug}-{appSlug}-{replicaIndex}`.
+- `DeploymentExecutor` — @Async staged deploy: PRE_FLIGHT -> PULL_IMAGE -> CREATE_NETWORK -> START_REPLICAS -> HEALTH_CHECK -> SWAP_TRAFFIC -> COMPLETE. Pulls both `baseImage` and `loaderImage` at PULL_IMAGE. Generates per-deploy signed download URLs via `ArtifactDownloadTokenSigner.sign(appVersionId, ttl)` — passes URL + appVersionId + jarSizeBytes + loaderImage into `ContainerRequest`. The host filesystem is no longer involved at deploy time. Container names are `{tenantId}-{envSlug}-{appSlug}-{replicaIndex}-{generation}`, where `generation` is the first 8 chars of the deployment UUID — old and new replicas coexist during a blue/green swap. Per-replica `CAMELEER_AGENT_INSTANCEID` env var is `{envSlug}-{appSlug}-{replicaIndex}-{generation}`. Branches on `DeploymentStrategy.fromWire(config.deploymentStrategy())`: **blue-green** (default) starts all N → waits for all healthy → stops old (partial health = FAILED, preserves old untouched); **rolling** replaces replicas one at a time with rollback only for in-flight new containers (already-replaced old stay stopped; un-replaced old keep serving). DEGRADED is now only set by `DockerEventMonitor` post-deploy, never by the executor. **License compute caps**: at PRE_FLIGHT (after `ConfigMerger.resolve`, before image pull / container creation) the executor consults `LicenseUsageReader.computeUsage()` (PG aggregate over non-stopped deployments) and runs three `LicenseEnforcer.assertWithinCap(...)` checks for `max_total_cpu_millis`, `max_total_memory_mb`, and `max_total_replicas`. A `LicenseCapExceededException` propagates to the surrounding `try/catch` which marks the deployment FAILED with the cap message in `deployments.error_message`.
 - `DockerNetworkManager` — ensures bridge networks (cameleer-traefik, cameleer-env-{slug}), connects containers
 - `DockerEventMonitor` — persistent Docker event stream listener (die, oom, start, stop), updates deployment status
-- `TraefikLabelBuilder` — generates Traefik Docker labels for path-based or subdomain routing. Also emits `cameleer.replica` and `cameleer.instance-id` labels per container for labels-first identity.
+- `TraefikLabelBuilder` — generates Traefik Docker labels for path-based or subdomain routing. Per-container identity labels: `cameleer.replica` (index), `cameleer.generation` (deployment-scoped 8-char id — for Prometheus/Grafana deploy-boundary annotations), `cameleer.instance-id` (`{envSlug}-{appSlug}-{replicaIndex}-{generation}`). Router/service label keys are generation-agnostic so load balancing spans old + new replicas during a blue/green overlap.
 - `PrometheusLabelBuilder` — generates Prometheus Docker labels (`prometheus.scrape/path/port`) per runtime type for `docker_sd_configs` auto-discovery
 - `ContainerLogForwarder` — streams Docker container stdout/stderr to ClickHouse with `source='container'`. One follow-stream thread per container, batches lines every 2s/50 lines via `ClickHouseLogStore.insertBufferedBatch()`. 60-second max capture timeout.
 - `DisabledRuntimeOrchestrator` — no-op when runtime not enabled
@@ -129,15 +139,22 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 ## metrics/ — Prometheus observability
 
 - `ServerMetrics` — centralized business metrics: gauges (agents by state, SSE connections, buffer depths), counters (ingestion drops, agent transitions, deployment outcomes, auth failures), timers (flush duration, deployment duration). Exposed via `/api/v1/prometheus`.
+- `ServerInstanceIdConfig` — `@Configuration`, exposes `@Bean("serverInstanceId") String`. Resolution precedence: `cameleer.server.instance-id` property → `HOSTNAME` env → `InetAddress.getLocalHost()` → random UUID. Fixed at boot; rotates across restarts so counters restart cleanly.
+- `ServerMetricsSnapshotScheduler` — `@Scheduled(fixedDelayString = "${cameleer.server.self-metrics.interval-ms:60000}")`. Walks `MeterRegistry.getMeters()` each tick, emits one `ServerMetricSample` per `Measurement` (Timer/DistributionSummary produce multiple rows per meter — one per Micrometer `Statistic`). Skips non-finite values; logs and swallows store failures. Disabled via `cameleer.server.self-metrics.enabled=false` (`@ConditionalOnProperty`). Write-only — no query endpoint yet; inspect via `/api/v1/admin/clickhouse/query`.
 
 ## storage/ — PostgreSQL repositories (JdbcTemplate)
 
 - `PostgresAppRepository`, `PostgresAppVersionRepository`, `PostgresEnvironmentRepository`
-- `PostgresDeploymentRepository` — includes JSONB replica_states, deploy_stage, findByContainerId
+- `PostgresDeploymentRepository` — includes JSONB replica_states, deploy_stage, findByContainerId. Also carries `deployed_config_snapshot` JSONB (Flyway V3) populated by `DeploymentExecutor` via `saveDeployedConfigSnapshot(UUID, DeploymentConfigSnapshot)` on successful RUNNING transition. Consumed by `DirtyStateCalculator` for the `/apps/{slug}/dirty-state` endpoint and by the UI for checkpoint restore.
 - `PostgresUserRepository`, `PostgresRoleRepository`, `PostgresGroupRepository`
 - `PostgresAuditRepository`, `PostgresOidcConfigRepository`, `PostgresClaimMappingRepository`, `PostgresSensitiveKeysRepository`
 - `PostgresAppSettingsRepository`, `PostgresApplicationConfigRepository`, `PostgresThresholdRepository`. Both `app_settings` and `application_config` are env-scoped (PK `(app_id, environment)` / `(application, environment)`); finders take `(app, env)` — no env-agnostic variants.
 
+## storage/ — Artifact storage (concrete impls)
+
+- `FilesystemArtifactStore` — implements `ArtifactStore` interface from `cameleer-server-core`. Persists JAR bytes under `{cameleer.server.runtime.jarstoragepath}/{appId}/v{version}/app.jar` (preserves the legacy layout — historical `app_versions.jar_path` rows resolve identically). `put` writes via `<target>.tmp` + `Files.move(ATOMIC_MOVE)` so concurrent readers never see a torn file. `delete` sweeps empty parent dirs and tolerates `DirectoryNotEmptyException` from concurrent sibling-version uploads. `size(coords)` returns the actual on-disk byte count — used by `ArtifactDownloadController` for authoritative `Content-Length` instead of trusting `AppVersion.jarSizeBytes`.
+- `ArtifactDownloadTokenSigner` — HMAC-SHA256 URL signer/verifier. Key derived deterministically from JWT secret via HMAC(secret, "cameleer-artifact-token-v1"). Sign produces `{exp, sig}` tuple where `sig = base64url-no-pad(HMAC-SHA256(key, "{uuid}:{exp}"))`. `verify` is constant-time via `MessageDigest.isEqual`. Used by `DeploymentExecutor` to mint download URLs and by `ArtifactDownloadController` to verify them. Rejects null/blank secret at construction.
+
 ## storage/ — ClickHouse stores
 
 - `ClickHouseExecutionStore`, `ClickHouseMetricsStore`, `ClickHouseMetricsQueryStore`
@@ -145,6 +162,8 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 - `ClickHouseDiagramStore`, `ClickHouseAgentEventRepository`
 - `ClickHouseUsageTracker` — usage_events for billing
 - `ClickHouseRouteCatalogStore` — persistent route catalog with first_seen cache, warm-loaded on startup
+- `ClickHouseServerMetricsStore` — periodic dumps of the server's own Micrometer registry into the `server_metrics` table. Tenant-stamped (bound at the scheduler, not the bean); no `environment` column (server straddles envs). Batch-insert via `JdbcTemplate.batchUpdate` with `Map(String, String)` tag binding. Written by `ServerMetricsSnapshotScheduler`.
+- `ClickHouseServerMetricsQueryStore` — read side of `server_metrics` for dashboards. Implements `ServerMetricsQueryStore`. `catalog(from,to)` returns name+type+statistics+tagKeys, `listInstances(from,to)` returns server_instance_ids with first/last seen, `query(request)` builds bucketed time-series with `raw` or `delta` mode and supports a derived `mean` statistic for timers. All identifier inputs regex-validated; tenant_id always bound; max range 31 days; series count capped at 500. Exposed via `ServerMetricsAdminController`.
 
 ## search/ — ClickHouse search and log stores
 
@@ -154,9 +173,10 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 ## security/ — Spring Security
 
 - `SecurityConfig` — WebSecurityFilterChain, JWT filter, CORS, OIDC conditional. `/api/v1/admin/outbound-connections/**` GETs permit OPERATOR in addition to ADMIN (defense-in-depth at controller level); mutations remain ADMIN-only. Alerting matchers: GET `/environments/*/alerts/**` VIEWER+; POST/PUT/DELETE rules and silences OPERATOR+; ack/read/bulk-read VIEWER+; POST `/alerts/notifications/*/retry` OPERATOR+.
-- `JwtAuthenticationFilter` — OncePerRequestFilter, validates Bearer tokens
+- `JwtAuthenticationFilter` — OncePerRequestFilter, validates Bearer tokens. Tries internal HMAC first; on failure (and when `oidcDecoder != null`) falls back to external-IdP validation. Resource-server path delegates to `OidcAccountSyncService.ensureProvisioned(jwt)` to upsert the user into `users` on first contact — without it, every later FK-to-`users(user_id)` insert (`deployments.created_by`, `alert_rules.created_by`, …) would 500 with a foreign-key violation. Sets `principal.name` to the bare `oidc:<sub>` so the env-scoped strip-`"user:"` convention is a no-op (still produces the correct FK value).
+- `OidcAccountSyncService` — provisions OIDC users into `users` from the `JwtAuthenticationFilter` resource-server path. `ensureProvisioned(Jwt)` short-circuits when the user exists; otherwise reads `OidcConfigRepository` (defaults `autoSignup=true` when no row — i.e., OIDC configured purely via env var), enforces the `max_users` cap via `LicenseEnforcer`, then upserts `UserInfo(userId="oidc:<sub>", provider="oidc:<issuer-host>", email, displayName, createdAt)`. Returns `Optional.empty()` on refusal so the filter falls through to anonymous (Spring → 401), never throws.
 - `JwtServiceImpl` — HMAC-SHA256 JWT (Nimbus JOSE)
-- `UiAuthController` — `/api/v1/auth` (login, refresh, me). Upserts `users.user_id = request.username()` (bare); signs JWTs with `subject = "user:" + userId`. `refresh`/`me` strip the `"user:"` prefix from incoming subjects via `stripSubjectPrefix()` before any DB/RBAC lookup.
+- `UiAuthController` — `/api/v1/auth` (login, refresh, me, logout). Upserts `users.user_id = request.username()` (bare); signs JWTs with `subject = "user:" + userId`. `refresh`/`me`/`logout` strip the `"user:"` prefix from incoming subjects via `stripSubjectPrefix()` before any DB/RBAC lookup. `logout` revokes outstanding tokens by writing `users.token_revoked_before` and audits under `AuditCategory.AUTH / logout`.
 - `OidcAuthController` — `/api/v1/auth/oidc` (login-uri, token-exchange, logout). Upserts `users.user_id = "oidc:" + oidcUser.subject()` (no `user:` prefix); signs JWTs with `subject = "user:oidc:" + oidcUser.subject()`. `applyClaimMappings` + `getSystemRoleNames` calls all use the bare `oidc:<sub>` form.
 - `OidcTokenExchanger` — code -> tokens, role extraction from access_token then id_token
 - `OidcProviderHelper` — OIDC discovery, JWK source cache
@@ -171,6 +191,14 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 
 - `JarRetentionJob` — @Scheduled 03:00 daily, per-environment retention, skips deployed versions
 
+## alerting/eval/ — Rule evaluation
+
+- `AlertEvaluatorJob` — @Scheduled tick driver; per-rule claim/release via `AlertRuleRepository`, dispatches to per-kind `ConditionEvaluator`, persists advanced cursor on release via `AlertRule.withEvalState`.
+- `BatchResultApplier` — `@Component` that wraps a single rule's tick outcome (`EvalResult.Batch` = `firings` + `nextEvalState`) in one `@Transactional` boundary: instance upserts + notification enqueues + cursor advance commit atomically or roll back together. This is the exactly-once-per-exchange guarantee for `PER_EXCHANGE` fire mode.
+- `ConditionEvaluator` — interface; per-kind implementations: `ExchangeMatchEvaluator`, `AgentLifecycleEvaluator`, `AgentStateEvaluator`, `DeploymentStateEvaluator`, `JvmMetricEvaluator`, `LogPatternEvaluator`, `RouteMetricEvaluator`.
+- `AlertStateTransitions` — PER_EXCHANGE vs rule-level FSM helpers (fire/resolve/ack).
+- `PerKindCircuitBreaker` — trips noisy per-kind evaluators; `TickCache` — per-tick shared lookups (apps, envs, silences).
+
 ## http/ — Outbound HTTP client implementation
 
 - `SslContextBuilder` — composes SSL context from `OutboundHttpProperties` + `OutboundHttpRequestContext`. Supports SYSTEM_DEFAULT (JDK roots + configured CA extras), TRUST_ALL (short-circuit no-op TrustManager), TRUST_PATHS (JDK roots + system extras + per-request extras). Throws `IllegalArgumentException("CA file not found: ...")` on missing PEM.
@@ -188,10 +216,27 @@ Env-scoped read-path controllers (`AlertController`, `AlertRuleController`, `Ale
 - `dto/OutboundConnectionTestResult` — result of POST `/{id}/test`: status, latencyMs, responseSnippet (first 512 chars), tlsProtocol/cipherSuite/peerCertSubject (protocol is "TLS" stub; enriched in Plan 02 follow-up), error (nullable).
 - `config/OutboundBeanConfig` — registers `OutboundConnectionRepository`, `SecretCipher`, `OutboundConnectionService` beans.
 
+## license/ — License enforcement & lifecycle
+
+- `LicenseService` — install / replace / revalidate mediator. `install(token, installedBy, source)` validates via `LicenseValidator`, on failure marks the gate INVALID + audits `reject_license` + publishes `LicenseChangedEvent` and rethrows; on success persists via `LicenseRepository.upsert(...)`, mutates `LicenseGate`, audits `install_license` or `replace_license` (detects existing row), and publishes `LicenseChangedEvent`. `loadInitial(envToken, fileToken)` boot precedence env > file > DB; ABSENT publishes a `LicenseChangedEvent(ABSENT, null)`. `revalidate()` re-runs validation against the persisted token, on success bumps `last_validated_at`; on failure marks INVALID and audits `revalidate_license` FAILURE. `getTenantId()` exposes the tenant for downstream lookups.
+- `LicenseRepository` — interface in `app/license`. `Optional<LicenseRecord> findByTenantId(String)`, `void upsert(LicenseRecord)`, `int touchValidated(String tenantId, Instant)`, `int delete(String)`.
+- `LicenseRecord` — record persisted in PG `license` table: `(String tenantId, String token, UUID licenseId, Instant installedAt, String installedBy, Instant expiresAt, Instant lastValidatedAt)`.
+- `PostgresLicenseRepository` — JdbcTemplate impl of `LicenseRepository`. Targets PG `license` table (V5). Upsert via `INSERT ... ON CONFLICT (tenant_id) DO UPDATE`.
+- `LicenseChangedEvent` — Spring application event: `(LicenseState state, LicenseInfo current)`. Published on every install / replace / revalidate / boot-time ABSENT path so downstream listeners (retention policy, metrics, etc.) react uniformly.
+- `LicenseEnforcer` — `@Component`. `assertWithinCap(String limitKey, long currentUsage, long requestedDelta)` consults `LicenseGate.getEffectiveLimits()`. On overflow increments `cameleer_license_cap_rejections_total{limit=...}`, emits an `AuditCategory.LICENSE / cap_exceeded` audit row when `AuditService` is wired (try/catch + log.warn so audit-write failures don't suppress the 403), and throws `LicenseCapExceededException`. Unknown limit keys propagate `IllegalArgumentException` from `LicenseLimits.get(...)` (programmer error, not a 403).
+- `LicenseUsageReader` — `@Component` over PG. `snapshot()` returns a `Map<String,Long>` of (max_environments, max_apps, max_users, max_outbound_connections, max_alert_rules, max_total_cpu_millis, max_total_memory_mb, max_total_replicas) from PG row counts and a SUM over non-stopped deployments' `deployed_config_snapshot.containerConfig` (replicas × cpuLimit / memoryLimitMb). `computeUsage()` returns the typed `ComputeUsage(cpuMillis, memoryMb, replicas)` tuple consumed by `DeploymentExecutor` PRE_FLIGHT cap checks. `agentCount(int)` echoes a registry-supplied live count (registry is in-memory; not stored in PG).
+- `LicenseCapExceededException` — typed `RuntimeException(limitKey, current, cap)` with accessors. Mapped to HTTP 403 by `LicenseExceptionAdvice`.
+- `LicenseExceptionAdvice` — `@ControllerAdvice` mapping `LicenseCapExceededException` → 403 with body `{error:"license cap reached", limit, current, cap, state, message}` where `message` is `LicenseMessageRenderer.forCap(state, info, limit, current, cap, invalidReason)`.
+- `LicenseMessageRenderer` — pure formatter (utility class, no DI). `forCap(state, info, limit, current, cap[, invalidReason])` per-state human messages for cap-rejection responses; `forState(state, info[, invalidReason])` shorter state-only messages for the `/usage` endpoint and metrics surfaces.
+- `RetentionPolicyApplier` — `@EventListener(LicenseChangedEvent.class) @Async`. For each environment × table in the static `SPECS` list (`executions`, `processor_executions`, `logs`, `agent_metrics`, `agent_events`) computes `effective = min(licenseCap, env.configuredRetentionDays)` and emits `ALTER TABLE <t> MODIFY TTL toDateTime(<col>) + INTERVAL <n> DAY DELETE WHERE environment = '<slug>'`. ClickHouse failures are logged and swallowed (best-effort; never propagates to the originating license install/revalidate). `route_diagrams` (no TTL clause) and `server_metrics` (no environment column) are intentionally excluded.
+- `LicenseRevalidationJob` — `@Component`. `@Scheduled(cron = "0 0 3 * * *")` daily revalidation; `@EventListener(ApplicationReadyEvent.class) @Async` 60-second post-startup tick to catch ABSENT→ACTIVE when a license was inserted between server starts. Both paths call `LicenseService.revalidate()` and swallow scheduler-thread crashes.
+- `LicenseMetrics` — `@Component`. Registers Micrometer gauges: `cameleer_license_state{state=...}` (one-hot per `LicenseState`), `cameleer_license_days_remaining` (negative when ABSENT/INVALID), `cameleer_license_last_validated_age_seconds` (0 when no DB row). Refreshed eagerly on `LicenseChangedEvent` via `@EventListener` and lazily every 60s via `@Scheduled(fixedDelay = 60_000)`.
+
 ## config/ — Spring beans
 
 - `RuntimeOrchestratorAutoConfig` — conditional Docker/Disabled orchestrator + NetworkManager + EventMonitor
-- `RuntimeBeanConfig` — DeploymentExecutor, AppService, EnvironmentService
+- `RuntimeBeanConfig` — DeploymentExecutor, AppService, EnvironmentService. Wires `CreateGuard` instances per service from `LicenseEnforcer.assertWithinCap(...)` so creation paths (Environment, App, Agent) consult license caps without core depending on the app module.
 - `SecurityBeanConfig` — JwtService, Ed25519, BootstrapTokenValidator
 - `StorageBeanConfig` — all repositories
 - `ClickHouseConfig` — ClickHouse JdbcTemplate, schema initializer
+- `LicenseBeanConfig` — license bean topology in dependency order: `LicenseGate` → `LicenseValidator` (when `cameleer.server.license.publickey` is unset, an always-failing override is returned so any loaded token still routes through `install()` and is audited as INVALID, never silently dropped) → `LicenseService` → `LicenseBootLoader` (`@PostConstruct` drives `loadInitial(envToken, fileToken)` once the context is ready; resolution order env var > license file > persisted DB row).

.claude/rules/cicd.md

@@ -8,11 +8,15 @@ paths:
 
 # CI/CD & Deployment
 
-- CI workflow: `.gitea/workflows/ci.yml` — build -> docker -> deploy on push to main or feature branches
+- CI workflow: `.gitea/workflows/ci.yml` — build -> docker -> deploy on push to main or feature branches. `paths-ignore` skips the whole pipeline for docs-only / `.planning/` / `.claude/` / `*.md` changes (push and PR triggers).
 - Build step skips integration tests (`-DskipITs`) — Testcontainers needs Docker daemon
+- Build caches (parallel `actions/cache@v4` steps in the `build` job): `~/.m2/repository` (key on all `pom.xml`), `~/.npm` (key on `ui/package-lock.json`), `ui/node_modules/.vite` (key on `ui/package-lock.json` + `ui/vite.config.ts`). UI install uses `npm ci --prefer-offline --no-audit --fund=false` so the npm cache is the primary source.
+- Maven build performance (set in `pom.xml` and `cameleer-server-app/pom.xml`): `useIncrementalCompilation=true` on the compiler plugin; Surefire uses `forkCount=1C` + `reuseForks=true` (one JVM per CPU core, reused across test classes); Failsafe keeps `forkCount=1` + `reuseForks=true`. Unit tests must not rely on per-class JVM isolation.
+- UI build script (`ui/package.json`): `build` is `vite build` only — the type-check pass was split out into `npm run typecheck` (run separately when you want a full `tsc --noEmit` sweep).
 - Docker: multi-stage build (`Dockerfile`), `$BUILDPLATFORM` for native Maven on ARM64 runner, amd64 runtime. `docker-entrypoint.sh` imports `/certs/ca.pem` into JVM truststore before starting the app (supports custom CAs for OIDC discovery without `CAMELEER_SERVER_SECURITY_OIDCTLSSKIPVERIFY`).
 - `REGISTRY_TOKEN` build arg required for `cameleer-common` dependency resolution
-- Registry: `gitea.siegeln.net/cameleer/cameleer-server` (container images)
+- Registry: `gitea.siegeln.net/cameleer/cameleer-server` (container images — CI push target, internal hostname). The same registry is reachable as `registry.cameleer.io/cameleer/cameleer-server` for customer pulls; the server's compiled-in image defaults target the public alias. See `CLAUDE.md` § Registry naming.
+- `cameleer-runtime-loader` image (init container that fetches the deployable JAR before the runtime container starts) is built and pushed by **cameleer-saas** CI (`docker/runtime-loader/` in that repo) — it lives alongside the other sidecar/infra images (runtime-base, postgres, clickhouse, traefik, logto). cameleer-server **consumes** the image via `DockerRuntimeOrchestrator` but does not build it. Cross-repo contract is regression-tested by `LoaderHardeningIT` here, which pulls the published `:latest` and asserts exit 0 under the orchestrator's hardening contract.
 - K8s manifests in `deploy/` — Kustomize base + overlays (main/feature), shared infra (PostgreSQL, ClickHouse, Logto) as top-level manifests
 - Deployment target: k3s at 192.168.50.86, namespace `cameleer` (main), `cam-<slug>` (feature branches)
 - Feature branches: isolated namespace, PG schema; Traefik Ingress at `<slug>-api.cameleer.siegeln.net`

.claude/rules/core-classes.md

@@ -5,7 +5,7 @@ paths:
 
 # Core Module Key Classes
 
-`cameleer-server-core/src/main/java/com/cameleer/server/core/`
+`cameleer-server-core/src/main/java/io/cameleer/server/core/`
 
 ## agent/ — Agent lifecycle and commands
 
@@ -26,33 +26,52 @@ paths:
 
 - `App` — record: id, environmentId, slug, displayName, containerConfig (JSONB)
 - `AppVersion` — record: id, appId, version, jarPath, detectedRuntimeType, detectedMainClass
-- `Environment` — record: id, slug, jarRetentionCount
+- `Environment` — record: id, slug, displayName, production, enabled, defaultContainerConfig, jarRetentionCount, color, createdAt, executionRetentionDays, logRetentionDays, metricRetentionDays. `color` is one of the 8 preset palette values validated by `EnvironmentColor.VALUES` and CHECK-constrained in PostgreSQL (V2 migration). The 3 retention day fields (V5) are `int`-typed (not nullable, since unlimited has no use-case), default to 1 day per the V5 `NOT NULL DEFAULT 1`, validated >= 1 in the canonical constructor.
-- `Deployment` — record: id, appId, appVersionId, environmentId, status, targetState, deploymentStrategy, replicaStates (JSONB), deployStage, containerId, containerName
+- `EnvironmentColor` — constants: `DEFAULT = "slate"`, `VALUES = {slate,red,amber,green,teal,blue,purple,pink}`, `isValid(String)`.
-- `DeploymentStatus` — enum: STOPPED, STARTING, RUNNING, DEGRADED, STOPPING, FAILED
+- `Deployment` — record: id, appId, appVersionId, environmentId, status, targetState, deploymentStrategy, replicaStates (JSONB), deployStage, containerId, containerName, createdBy (String, user_id reference; nullable for pre-V4 historical rows)
+- `DeploymentStatus` — enum: STOPPED, STARTING, RUNNING, DEGRADED, STOPPING, FAILED. `DEGRADED` is reserved for post-deploy drift (a replica died after RUNNING); `DeploymentExecutor` now marks partial-healthy deploys FAILED, not DEGRADED.
 - `DeployStage` — enum: PRE_FLIGHT, PULL_IMAGE, CREATE_NETWORK, START_REPLICAS, HEALTH_CHECK, SWAP_TRAFFIC, COMPLETE
-- `DeploymentService` — createDeployment (deletes terminal deployments first), markRunning, markFailed, markStopped
+- `DeploymentStrategy` — enum: BLUE_GREEN, ROLLING. Stored on `ResolvedContainerConfig.deploymentStrategy` as kebab-case string (`"blue-green"` / `"rolling"`). `fromWire(String)` is the only conversion entry point; unknown/null inputs fall back to BLUE_GREEN so the executor dispatch site never null-checks or throws.
+- `DeploymentService` — createDeployment (calls `deleteFailedByAppAndEnvironment` first so FAILED rows don't pile up; STOPPED rows are preserved as restorable checkpoints), markRunning, markFailed, markStopped
 - `RuntimeType` — enum: AUTO, SPRING_BOOT, QUARKUS, PLAIN_JAVA, NATIVE
 - `RuntimeDetector` — probes JAR files at upload time: detects runtime from manifest Main-Class (Spring Boot loader, Quarkus entry point, plain Java) or native binary (non-ZIP magic bytes)
-- `ContainerRequest` — record: 20 fields for Docker container creation (includes runtimeType, customArgs, mainClass)
+- `ContainerRequest` — record: 21 fields for Docker container creation. Replaces the legacy `jarPath`/`jarVolumeName`/`jarVolumeMountPath` triple with `appVersionId` (UUID), `artifactDownloadUrl` (signed), `artifactExpectedSize` (bytes), and `loaderImage`. The orchestrator's loader init-container fetches the JAR from the URL into a per-replica named volume; the main container reads it from `/app/jars/app.jar`.
 - `ContainerStatus` — record: state, running, exitCode, error
-- `ResolvedContainerConfig` — record: typed config with memoryLimitMb, memoryReserveMb, cpuRequest, cpuLimit, appPort, exposedPorts, customEnvVars, stripPathPrefix, sslOffloading, routingMode, routingDomain, serverUrl, replicas, deploymentStrategy, routeControlEnabled, replayEnabled, runtimeType, customArgs, extraNetworks
+- `ResolvedContainerConfig` — record: typed config with memoryLimitMb, memoryReserveMb, cpuRequest, cpuLimit, appPort, exposedPorts, customEnvVars, stripPathPrefix, sslOffloading, routingMode, routingDomain, serverUrl, replicas, deploymentStrategy, routeControlEnabled, replayEnabled, runtimeType, customArgs, extraNetworks, externalRouting (default `true`; when `false`, `TraefikLabelBuilder` strips all `traefik.*` labels so the container is not publicly routed), certResolver (server-wide, sourced from `CAMELEER_SERVER_RUNTIME_CERTRESOLVER`; when blank the `tls.certresolver` label is omitted — use for dev installs with a static TLS store)
 - `RoutingMode` — enum for routing strategies
 - `ConfigMerger` — pure function: resolve(globalDefaults, envConfig, appConfig) -> ResolvedContainerConfig
 - `RuntimeOrchestrator` — interface: startContainer, stopContainer, getContainerStatus, getLogs, startLogCapture, stopLogCapture
 - `AppRepository`, `AppVersionRepository`, `EnvironmentRepository`, `DeploymentRepository` — repository interfaces
 - `AppService`, `EnvironmentService` — domain services
+- `CreateGuard` — `@FunctionalInterface`. `void check(long current)` — implementations throw to abort creation. `NOOP` constant is the default. Consulted by `EnvironmentService.create`, `AppService.createApp`, and `AgentRegistryService.register` so license caps can be enforced from the app module without leaking Spring or app-only types into core. Wired in `LicenseBeanConfig` to a `LicenseEnforcer.assertWithinCap(...)` call per limit key.
+
+## license/ — License domain (signed-token tier system)
+
+The pure license **contract types** live in the separate `cameleer-license-api` module under package `io.cameleer.license` (no Spring, no server-runtime deps) so consumers like `cameleer-license-minter` and `cameleer-saas` can use them without inheriting server internals. Server-core only contains the runtime state holder (`LicenseGate`).
+
+Contract types in `cameleer-license-api` (package `io.cameleer.license`):
+- `LicenseInfo` — record: `(UUID licenseId, String tenantId, String label, Map<String,Integer> limits, Instant issuedAt, Instant expiresAt, int gracePeriodDays)`. `isExpired()` true once `now > expiresAt + gracePeriodDays`; `isAfterRawExpiry()` true once `now > expiresAt`. Constructed via `LicenseValidator`; canonical ctor null-checks all required fields and rejects blank tenantId / negative grace.
+- `LicenseLimits` — typed limits container backed by `Map<String,Integer>`. `defaultsOnly()` returns the `DefaultTierLimits.DEFAULTS` view; `mergeOverDefaults(overrides)` produces the license-overrides UNION default tier. `get(String key)` returns the cap; throws `IllegalArgumentException` for unknown keys (programmer error). `isDefaultSourced(key, license)` reports whether a key fell through to the default tier.
+- `DefaultTierLimits` — immutable `LinkedHashMap` of constants for the no-license fallback tier: `max_environments=1, max_apps=3, max_agents=5, max_users=3, max_outbound_connections=1, max_alert_rules=2, max_total_cpu_millis=2000, max_total_memory_mb=2048, max_total_replicas=5, max_execution_retention_days=1, max_log_retention_days=1, max_metric_retention_days=1, max_jar_retention_count=3`.
+- `LicenseValidator` — verifies signed token. Constructor `(String publicKeyBase64, String expectedTenantId)` decodes an X.509 Ed25519 public key. `validate(String token)` splits `payload.signature`, verifies the Ed25519 signature, parses the JSON payload, enforces `tenantId == expectedTenantId`, and returns `LicenseInfo`. Throws `SecurityException` on signature mismatch / `IllegalArgumentException` on parse failure / expired payload.
+- `LicenseStateMachine` — pure classifier. `classify(LicenseInfo, String invalidReason)` returns `INVALID` if a reason is set, `ABSENT` if no license, `ACTIVE` if `now <= expiresAt`, `GRACE` if expired but within grace window, `EXPIRED` otherwise.
+- `LicenseState` — enum: `ABSENT, ACTIVE, GRACE, EXPIRED, INVALID`.
+
+Runtime state holder in server-core (package `io.cameleer.server.core.license`):
+- `LicenseGate` — runtime state holder (thread-safe via `AtomicReference<Snapshot>`). `getCurrent()` returns the current `LicenseInfo` (null when ABSENT/INVALID); `getState()` delegates to `LicenseStateMachine.classify(...)`; `getEffectiveLimits()` returns license-overrides UNION defaults in `ACTIVE`/`GRACE`, defaults-only otherwise. `getInvalidReason()`, `load(LicenseInfo)`, `markInvalid(String reason)`, `clear()` are the mutators. `getLimit(key, defaultValue)` shorthand swallows unknown-key errors.
 
 ## search/ — Execution search and stats
 
 - `SearchService` — search, count, stats, statsForApp, statsForRoute, timeseries, timeseriesForApp, timeseriesForRoute, timeseriesGroupedByApp, timeseriesGroupedByRoute, slaCompliance, slaCountsByApp, slaCountsByRoute, topErrors, activeErrorTypes, punchcard, distinctAttributeKeys. `statsForRoute`/`timeseriesForRoute` take `(routeId, applicationId)` — app filter is applied to `stats_1m_route`.
-- `SearchRequest` / `SearchResult` — search DTOs
+- `SearchRequest` / `SearchResult` — search DTOs. `SearchRequest.attributeFilters: List<AttributeFilter>` carries structured facet filters for execution attributes — key-only (exists), exact (key=value), or wildcard (`*` in value). The 21-arg legacy ctor is preserved for call-site churn; the compact ctor normalises null → `List.of()`.
+- `AttributeFilter(key, value)` — record with key regex `^[a-zA-Z0-9._-]+$` (inlined into SQL, same constraint as alerting), `value == null` means key-exists, `value` containing `*` becomes a SQL LIKE pattern via `toLikePattern()`.
 - `ExecutionStats`, `ExecutionSummary` — stats aggregation records
 - `StatsTimeseries`, `TopError` — timeseries and error DTOs
 - `LogSearchRequest` / `LogSearchResponse` — log search DTOs. `LogSearchRequest.sources` / `levels` are `List<String>` (null-normalized, multi-value OR); `cursor` + `limit` + `sort` drive keyset pagination. Response carries `nextCursor` + `hasMore` + per-level `levelCounts`.
 
 ## storage/ — Storage abstractions
 
-- `ExecutionStore`, `MetricsStore`, `MetricsQueryStore`, `StatsStore`, `DiagramStore`, `RouteCatalogStore`, `SearchIndex`, `LogIndex` — interfaces
+- `ExecutionStore`, `MetricsStore`, `MetricsQueryStore`, `StatsStore`, `DiagramStore`, `RouteCatalogStore`, `SearchIndex`, `LogIndex` — interfaces. `DiagramStore.findLatestContentHashForAppRoute(appId, routeId, env)` resolves the latest diagram by (app, env, route) without consulting the agent registry, so routes whose publishing agents were removed between app versions still resolve. `findContentHashForRoute(route, instance)` is retained for the ingestion path that stamps a per-execution `diagramContentHash` at ingest time (point-in-time link from `ExecutionDetail`/`ExecutionSummary`).
 - `RouteCatalogEntry` — record: applicationId, routeId, environment, firstSeen, lastSeen
 - `LogEntryResult` — log query result record
 - `model/` — `ExecutionDocument`, `MetricTimeSeries`, `MetricsSnapshot`
@@ -78,7 +97,7 @@ paths:
 - `AppSettings`, `AppSettingsRepository` — per-app-per-env settings config and persistence. Record carries `(applicationId, environment, …)`; repository methods are `findByApplicationAndEnvironment`, `findByEnvironment`, `save`, `delete(appId, env)`. `AppSettings.defaults(appId, env)` produces a default instance scoped to an environment.
 - `ThresholdConfig`, `ThresholdRepository` — alerting threshold config and persistence
 - `AuditService` — audit logging facade
-- `AuditRecord`, `AuditResult`, `AuditCategory` (enum: `INFRA, AUTH, USER_MGMT, CONFIG, RBAC, AGENT, OUTBOUND_CONNECTION_CHANGE, OUTBOUND_HTTP_TRUST_CHANGE`), `AuditRepository` — audit trail records and persistence
+- `AuditRecord`, `AuditResult`, `AuditCategory` (enum: `INFRA, AUTH, USER_MGMT, CONFIG, RBAC, AGENT, OUTBOUND_CONNECTION_CHANGE, OUTBOUND_HTTP_TRUST_CHANGE, ALERT_RULE_CHANGE, ALERT_SILENCE_CHANGE, DEPLOYMENT, LICENSE`), `AuditRepository` — audit trail records and persistence
 
 ## http/ — Outbound HTTP primitives (cross-cutting)
 

.claude/rules/docker-orchestration.md

@@ -13,19 +13,63 @@ paths:
 When deployed via the cameleer-saas platform, this server orchestrates customer app containers using Docker. Key components:
 
 - **ConfigMerger** (`core/runtime/ConfigMerger.java`) — pure function: resolve(globalDefaults, envConfig, appConfig) -> ResolvedContainerConfig. Three-layer merge: global (application.yml) -> environment (defaultContainerConfig JSONB) -> app (containerConfig JSONB). Includes `runtimeType` (default `"auto"`) and `customArgs` (default `""`).
-- **TraefikLabelBuilder** (`app/runtime/TraefikLabelBuilder.java`) — generates Traefik Docker labels for path-based (`/{envSlug}/{appSlug}/`) or subdomain-based (`{appSlug}-{envSlug}.{domain}`) routing. Supports strip-prefix and SSL offloading toggles. Also sets per-replica identity labels: `cameleer.replica` (index) and `cameleer.instance-id` (`{envSlug}-{appSlug}-{replicaIndex}`). Internal processing uses labels (not container name parsing) for extensibility.
+- **TraefikLabelBuilder** (`app/runtime/TraefikLabelBuilder.java`) — generates Traefik Docker labels for path-based (`/{envSlug}/{appSlug}/`) or subdomain-based (`{appSlug}-{envSlug}.{domain}`) routing. Supports strip-prefix and SSL offloading toggles. Per-replica identity labels: `cameleer.replica` (index), `cameleer.generation` (8-char deployment UUID prefix — pin Prometheus/Grafana deploy boundaries with this), `cameleer.instance-id` (`{envSlug}-{appSlug}-{replicaIndex}-{generation}`). Traefik router/service keys deliberately omit the generation so load balancing spans old + new replicas during a blue/green overlap. When `ResolvedContainerConfig.externalRouting()` is `false` (UI: Resources → External Routing, default `true`), the builder emits ONLY the identity labels (`managed-by`, `cameleer.*`) and skips every `traefik.*` label — the container stays on `cameleer-traefik` and the per-env network (so sibling containers can still reach it via Docker DNS) but is invisible to Traefik. The `tls.certresolver` label is emitted only when `CAMELEER_SERVER_RUNTIME_CERTRESOLVER` is set to a non-blank resolver name (matching a resolver configured in the Traefik static config). When unset (dev installs backed by a static TLS store) only `tls=true` is emitted and Traefik serves the default cert from the TLS store.
 - **PrometheusLabelBuilder** (`app/runtime/PrometheusLabelBuilder.java`) — generates Prometheus `docker_sd_configs` labels per resolved runtime type: Spring Boot `/actuator/prometheus:8081`, Quarkus/native `/q/metrics:9000`, plain Java `/metrics:9464`. Labels merged into container metadata alongside Traefik labels at deploy time.
 - **DockerNetworkManager** (`app/runtime/DockerNetworkManager.java`) — manages two Docker network tiers:
   - `cameleer-traefik` — shared network; Traefik, server, and all app containers attach here. Server joined via docker-compose with `cameleer-server` DNS alias.
   - `cameleer-env-{slug}` — per-environment isolated network; containers in the same environment discover each other via Docker DNS. In SaaS mode, env networks are tenant-scoped: `cameleer-env-{tenantId}-{envSlug}` (overloaded `envNetworkName(tenantId, envSlug)` method) to prevent cross-tenant collisions when multiple tenants have identically-named environments.
 - **DockerEventMonitor** (`app/runtime/DockerEventMonitor.java`) — persistent Docker event stream listener for containers with `managed-by=cameleer-server` label. Detects die/oom/start/stop events and updates deployment replica states. Periodic reconciliation (@Scheduled every 30s) inspects actual container state and corrects deployment status mismatches (fixes stale DEGRADED with all replicas healthy).
 - **DeploymentProgress** (`ui/src/components/DeploymentProgress.tsx`) — UI step indicator showing 7 deploy stages with amber active/green completed styling.
-- **ContainerLogForwarder** (`app/runtime/ContainerLogForwarder.java`) — streams Docker container stdout/stderr to ClickHouse `logs` table with `source='container'`. Uses `docker logs --follow` per container, batches lines every 2s or 50 lines. Parses Docker timestamp prefix, infers log level via regex. `DeploymentExecutor` starts capture after each replica launches with the replica's `instanceId` (`{envSlug}-{appSlug}-{replicaIndex}`); `DockerEventMonitor` stops capture on die/oom. 60-second max capture timeout with 30s cleanup scheduler. Thread pool of 10 daemon threads. Container logs use the same `instanceId` as the agent (set via `CAMELEER_AGENT_INSTANCEID` env var) for unified log correlation at the instance level.
+- **ContainerLogForwarder** (`app/runtime/ContainerLogForwarder.java`) — streams Docker container stdout/stderr to ClickHouse `logs` table with `source='container'`. Uses `docker logs --follow` per container, batches lines every 2s or 50 lines. Parses Docker timestamp prefix, infers log level via regex. `DeploymentExecutor` starts capture after each replica launches with the replica's `instanceId` (`{envSlug}-{appSlug}-{replicaIndex}-{generation}`); `DockerEventMonitor` stops capture on die/oom. 60-second max capture timeout with 30s cleanup scheduler. Thread pool of 10 daemon threads. Container logs use the same `instanceId` as the agent (set via `CAMELEER_AGENT_INSTANCEID` env var) for unified log correlation at the instance level. Instance-id changes per deployment — cross-deploy queries aggregate on `application + environment` (and optionally `replica_index`).
 - **StartupLogPanel** (`ui/src/components/StartupLogPanel.tsx`) — collapsible log panel rendered below `DeploymentProgress`. Queries `/api/v1/logs?source=container&application={appSlug}&environment={envSlug}`. Auto-polls every 3s while deployment is STARTING; shows green "live" badge during polling, red "stopped" badge on FAILED. Uses `useStartupLogs` hook and `LogViewer` (design system).
 
+## Container Hardening (issue #152)
+
+`DockerRuntimeOrchestrator.startContainer` applies an unconditional hardening contract to BOTH the loader init-container AND the main tenant container (`baseHardenedHostConfig()` is the shared helper). Java 17 has no SecurityManager so the JVM is not a security boundary, and isolation must live below it. Defaults are fail-closed and have no opt-out:
+
+- `cap_drop` = every `Capability.values()` (effectively ALL — docker-java's enum has no `ALL` constant). Outbound TCP still works (no caps needed); raw sockets, ptrace, mounts, and bind <1024 are denied.
+- `security_opt`: `no-new-privileges:true`, `apparmor=docker-default`. Default seccomp profile is applied implicitly when `seccomp=` is absent.
+- `read_only` rootfs = true.
+- `pids_limit` = 512 (`PIDS_LIMIT` constant).
+- `tmpfs` mount: `/tmp` with `rw,nosuid,size=256m`. **No `noexec`** — Netty/tcnative, Snappy, LZ4, Zstd dlopen native libs from `/tmp` via `mmap(PROT_EXEC)` which `noexec` blocks. Issue #153 will add per-app `writeableVolumes` for stateful tenants (Kafka Streams etc.).
+- `userns_mode` = `host:1000:65536` on both loader and main. Container root is never UID 0 on the host — closes the last open hardening item from issue #152.
+
+**Sandboxed runtime auto-detect**: at construction the orchestrator calls `dockerClient.infoCmd().exec().getRuntimes()` and uses `runsc` (gVisor) when present. Override with `cameleer.server.runtime.dockerruntime` (e.g. `kata` to force Kata Containers, or any other registered runtime). Empty/blank = auto. The override always wins over auto-detect. The `DockerRuntimeOrchestrator(DockerClient, String)` constructor is the canonical entry point; the single-arg constructor exists only as a convenience for tests that don't need an override.
+
+## Init-Container Loader Pattern (JAR fetch)
+
+`startContainer` is now a two-phase op per replica:
+
+1. **Volume create** — `cameleer-jars-{containerName}` named volume (per-replica, deterministic so cleanup in `removeContainer` can derive it).
+2. **Loader container** — `loaderImage` (default `registry.cameleer.io/cameleer/cameleer-runtime-loader:latest`, **built and published by the cameleer-saas repo** at `docker/runtime-loader/`; CI pushes to `gitea.siegeln.net` under the same path — both names resolve to the same registry), name `{containerName}-loader`, mount the volume **RW at `/app/jars`**, env vars `ARTIFACT_URL` + `ARTIFACT_EXPECTED_SIZE`. Loader downloads the JAR from the signed URL into the volume and exits 0. Orchestrator blocks on `waitContainerCmd().exec(WaitContainerResultCallback).awaitStatusCode(120, SECONDS)`. Loader container is removed in a `finally` block; on non-zero exit the volume is also removed and `RuntimeException` propagates so `DeploymentExecutor` marks the deployment FAILED. **Loader logs are captured before removal** (`captureLoaderLogs` — `logContainerCmd` with `withTail(50)`, capped at 4096 chars, 5s timeout) and appended to the thrown `RuntimeException` message as `". loader output: <text>"`. Best-effort: log-capture failures are swallowed and don't mask the original exit. The loader image's Dockerfile pre-creates `/app/jars` owned by `loader:loader` (UID 1000) so the orchestrator's fresh named volume initialises with that ownership — without it the empty volume comes up as `root:root 0755` and wget exits 1 with "Permission denied". `LoaderHardeningIT` is the cross-repo contract test (pulls the published `:latest` and asserts exit 0 under the orchestrator's hardening shape).
+3. **Main container** — same hardening contract, mount the same volume **RO at `/app/jars`**, entrypoint reads `/app/jars/app.jar` (Spring Boot/Quarkus: `-jar /app/jars/app.jar`; plain Java: `-cp /app/jars/app.jar <MainClass>`; native: `exec /app/jars/app.jar`).
+
+`removeContainer(id)` derives the volume name from the inspected container name (Docker prefixes it with `/`) and removes the volume after the container removes — blue/green doesn't leak volumes.
+
+`DeploymentExecutor` generates the signed URL via `ArtifactDownloadTokenSigner.sign(appVersion.id(), Duration.ofSeconds(artifactTokenTtlSeconds))` and passes `appVersion.id()`, the URL, `appVersion.jarSizeBytes()`, and the loader image into `ContainerRequest`. The host filesystem is no longer involved at deploy time.
+
+**Loader → server reachability**: the loader hits the Cameleer server from its **primary** Docker
+network only (`request.network()`, set from `CAMELEER_SERVER_RUNTIME_DOCKERNETWORK`). Additional networks
+(`cameleer-traefik`, per-env) are attached by `DockerNetworkManager.connectContainer` AFTER `startContainer`
+returns — by which time the loader has already exited. The loader cannot use them. The signed URL is built
+from `cameleer.server.runtime.artifactbaseurl` (preferred), falling back to `cameleer.server.runtime.serverurl`,
+falling back to `http://cameleer-server:8081`. The default works in SaaS mode because the tenant's primary
+network (`cameleer-tenant-{slug}`) hosts the tenant's own server — same `CAMELEER_SERVER_RUNTIME_DOCKERNETWORK`
+on both. For non-SaaS topologies, set `CAMELEER_SERVER_RUNTIME_ARTIFACTBASEURL` to a URL the loader can reach
+on its primary network.
+
 ## DeploymentExecutor Details
 
-Primary network for app containers is set via `CAMELEER_SERVER_RUNTIME_DOCKERNETWORK` env var (in SaaS mode: `cameleer-tenant-{slug}`); apps also connect to `cameleer-traefik` (routing) and `cameleer-env-{tenantId}-{envSlug}` (per-environment discovery) as additional networks. Resolves `runtimeType: auto` to concrete type from `AppVersion.detectedRuntimeType` at PRE_FLIGHT (fails deployment if unresolvable). Builds Docker entrypoint per runtime type (all JVM types use `-javaagent:/app/agent.jar -jar`, plain Java uses `-cp` with main class, native runs binary directly). Sets per-replica `CAMELEER_AGENT_INSTANCEID` env var to `{envSlug}-{appSlug}-{replicaIndex}` so container logs and agent logs share the same instance identity. Sets `CAMELEER_AGENT_*` env vars from `ResolvedContainerConfig` (routeControlEnabled, replayEnabled, health port). These are startup-only agent properties — changing them requires redeployment.
+Primary network for app containers is set via `CAMELEER_SERVER_RUNTIME_DOCKERNETWORK` env var (in SaaS mode: `cameleer-tenant-{slug}`); apps also connect to `cameleer-traefik` (routing) and `cameleer-env-{tenantId}-{envSlug}` (per-environment discovery) as additional networks. Resolves `runtimeType: auto` to concrete type from `AppVersion.detectedRuntimeType` at PRE_FLIGHT (fails deployment if unresolvable). Builds Docker entrypoint per runtime type (all JVM types use `-javaagent:/app/agent.jar -jar`, plain Java uses `-cp` with main class, native runs binary directly). Sets per-replica `CAMELEER_AGENT_INSTANCEID` env var to `{envSlug}-{appSlug}-{replicaIndex}-{generation}` so container logs and agent logs share the same instance identity. Sets `CAMELEER_AGENT_*` env vars from `ResolvedContainerConfig` (routeControlEnabled, replayEnabled, health port). These are startup-only agent properties — changing them requires redeployment.
+
+**Container naming** — `{tenantId}-{envSlug}-{appSlug}-{replicaIndex}-{generation}`, where `generation` is the first 8 characters of the deployment UUID. The generation suffix lets old + new replicas coexist during a blue/green swap (deterministic names without a generation used to 409). All lookups across the executor, `DockerEventMonitor`, and `ContainerLogForwarder` key on container **id**, not name — the name is operator-visibility only.
+
+**Strategy dispatch** — `DeploymentStrategy.fromWire(config.deploymentStrategy())` branches the executor. Unknown values fall back to BLUE_GREEN so misconfiguration never throws at runtime.
+
+- **Blue/green** (default): start all N new replicas → wait for ALL healthy → stop the previous deployment. Resource peak ≈ 2× replicas for the health-check window. Partial health aborts with status FAILED; the previous deployment is preserved untouched (user's safety net).
+- **Rolling**: replace replicas one at a time — start new[i] → wait healthy → stop old[i] → next. Resource peak = replicas + 1. Mid-rollout health failure stops in-flight new containers and aborts; already-replaced old replicas are NOT restored (not reversible) but un-replaced old[i+1..N] keep serving traffic. User redeploys to recover.
+
+Traffic routing is implicit: Traefik labels (`cameleer.app`, `cameleer.environment`) are generation-agnostic, so new replicas attract load balancing as soon as they come up healthy — no explicit swap step.
 
 ## Deployment Status Model
 
@@ -34,23 +78,20 @@ Primary network for app containers is set via `CAMELEER_SERVER_RUNTIME_DOCKERNET
 | `STOPPED` | Intentionally stopped or initial state |
 | `STARTING` | Deploy in progress |
 | `RUNNING` | All replicas healthy and serving |
-| `DEGRADED` | Some replicas healthy, some dead |
+| `DEGRADED` | Post-deploy: a replica died after the deploy was marked RUNNING. Set by `DockerEventMonitor` reconciliation, never by `DeploymentExecutor` directly. |
 | `STOPPING` | Graceful shutdown in progress |
-| `FAILED` | Terminal failure (pre-flight, health check, or crash) |
+| `FAILED` | Terminal failure (pre-flight, health check, or crash). Partial-healthy deploys now mark FAILED — DEGRADED is reserved for post-deploy drift. |
 
-**Replica support**: deployments can specify a replica count. `DEGRADED` is used when at least one but not all replicas are healthy.
+**Deploy stages** (`DeployStage`): PRE_FLIGHT -> PULL_IMAGE -> CREATE_NETWORK -> START_REPLICAS -> HEALTH_CHECK -> SWAP_TRAFFIC -> COMPLETE (or FAILED at any stage). Rolling reuses the same stage labels inside the per-replica loop; the UI progress bar shows the most recent stage.
 
-**Deploy stages** (`DeployStage`): PRE_FLIGHT -> PULL_IMAGE -> CREATE_NETWORK -> START_REPLICAS -> HEALTH_CHECK -> SWAP_TRAFFIC -> COMPLETE (or FAILED at any stage).
+**Deployment retention**: `DeploymentService.createDeployment()` deletes FAILED deployments for the same app+environment before creating a new one, preventing failed-attempt buildup. STOPPED deployments are preserved as restorable checkpoints — the UI Checkpoints disclosure lists every deployment with a non-null `deployed_config_snapshot` (RUNNING, DEGRADED, STOPPED) minus the current one.
-
-**Blue/green strategy**: when re-deploying, new replicas are started and health-checked before old ones are stopped, minimising downtime.
-
-**Deployment uniqueness**: `DeploymentService.createDeployment()` deletes any STOPPED/FAILED deployments for the same app+environment before creating a new one, preventing duplicate rows.
 
 ## JAR Management
 
 - **Retention policy** per environment: configurable maximum number of JAR versions to keep. Older JARs are deleted automatically.
 - **Nightly cleanup job** (`JarRetentionJob`, Spring `@Scheduled` 03:00): purges JARs exceeding the retention limit and removes orphaned files not referenced by any app version. Skips versions currently deployed.
-- **Volume-based JAR mounting** for Docker-in-Docker setups: set `CAMELEER_SERVER_RUNTIME_JARDOCKERVOLUME` to the Docker volume name that contains the JAR storage directory. When set, the orchestrator mounts this volume into the container instead of bind-mounting the host path (required when the SaaS container itself runs inside Docker and the host path is not accessible from sibling containers).
+- **Storage abstraction**: `ArtifactStore` (in `cameleer-server-core/storage`) is the only path that touches JAR bytes. `FilesystemArtifactStore` writes under `cameleer.server.runtime.jarstoragepath` (default `/data/jars`); the orchestrator never reads the host filesystem at deploy time.
+- **Loader-fetch at deploy time**: tenant containers no longer bind-mount JARs from the host. The loader init-container streams the JAR via a signed URL (HMAC-SHA256, TTL `cameleer.server.runtime.artifacttokenttlseconds`, default 600s) into a per-replica named volume; main mounts that volume RO. This works without host-path access and is the single path supported in Docker-in-Docker SaaS deployments.
 
 ## Runtime Type Detection
 

.claude/rules/metrics.md

@@ -8,7 +8,9 @@ paths:
 
 # Prometheus Metrics
 
-Server exposes `/api/v1/prometheus` (unauthenticated, Prometheus text format). Spring Boot Actuator provides JVM, GC, thread pool, and `http.server.requests` metrics automatically. Business metrics via `ServerMetrics` component:
+Server exposes `/api/v1/prometheus` (unauthenticated, Prometheus text format). Spring Boot Actuator provides JVM, GC, thread pool, and `http.server.requests` metrics automatically. Business metrics via `ServerMetrics` component.
+
+The same `MeterRegistry` is also snapshotted to ClickHouse every 60 s by `ServerMetricsSnapshotScheduler` (see "Server self-metrics persistence" at the bottom of this file) — so historical server-health data survives restarts without an external Prometheus.
 
 ## Gauges (auto-polled)
 
@@ -83,3 +85,23 @@ Mean processing time = `camel.route.policy.total_time / camel.route.policy.count
 | `cameleer.sse.reconnects.count` | counter | `instanceId` |
 | `cameleer.taps.evaluated.count` | counter | `instanceId` |
 | `cameleer.metrics.exported.count` | counter | `instanceId` |
+
+## Server self-metrics persistence
+
+`ServerMetricsSnapshotScheduler` walks `MeterRegistry.getMeters()` every 60 s (configurable via `cameleer.server.self-metrics.interval-ms`) and writes one row per Micrometer `Measurement` to the ClickHouse `server_metrics` table. Full registry is captured — Spring Boot Actuator series (`jvm.*`, `process.*`, `http.server.requests`, `hikaricp.*`, `jdbc.*`, `tomcat.*`, `logback.events`, `system.*`) plus `cameleer.*` and `alerting_*`.
+
+**Table** (`cameleer-server-app/src/main/resources/clickhouse/init.sql`):
+
+```
+server_metrics(tenant_id, collected_at, server_instance_id,
+               metric_name, metric_type, statistic, metric_value,
+               tags Map(String,String), server_received_at)
+```
+
+- `metric_type` — lowercase Micrometer `Meter.Type` (counter, gauge, timer, distribution_summary, long_task_timer, other)
+- `statistic` — Micrometer `Statistic.getTagValueRepresentation()` (value, count, total, total_time, max, mean, active_tasks, duration). Timers emit 3 rows per tick (count + total_time + max); gauges/counters emit 1 (`statistic='value'` or `'count'`).
+- No `environment` column — the server is env-agnostic.
+- `tenant_id` threaded from `cameleer.server.tenant.id` (single-tenant per server).
+- `server_instance_id` resolved once at boot by `ServerInstanceIdConfig` (property → HOSTNAME → localhost → UUID fallback). Rotates across restarts so counter resets are unambiguous.
+- TTL: 90 days (vs 365 for `agent_metrics`). Write-only in v1 — no query endpoint or UI page. Inspect via ClickHouse admin: `/api/v1/admin/clickhouse/query` or direct SQL.
+- Toggle off entirely with `cameleer.server.self-metrics.enabled=false` (uses `@ConditionalOnProperty`).

.claude/rules/ui.md

@@ -10,13 +10,18 @@ The UI has 4 main tabs: **Exchanges**, **Dashboard**, **Runtime**, **Deployments
 - **Exchanges** — route execution search and detail (`ui/src/pages/Exchanges/`)
 - **Dashboard** — metrics and stats with L1/L2/L3 drill-down (`ui/src/pages/DashboardTab/`)
 - **Runtime** — live agent status, logs, commands (`ui/src/pages/RuntimeTab/`). AgentHealth supports compact view (dense health-tinted cards) and expanded view (full GroupCard+DataTable per app). View mode persisted to localStorage.
-- **Deployments** — app management, JAR upload, deployment lifecycle (`ui/src/pages/AppsTab/`)
+- **Deployments** — unified app deployment page (`ui/src/pages/AppsTab/`)
-  - Config sub-tabs: **Monitoring | Resources | Variables | Traces & Taps | Route Recording**
+  - Routes: `/apps` (list, `AppListView` in `AppsTab.tsx`), `/apps/new` + `/apps/:slug` (both render `AppDeploymentPage`).
-  - Create app: full page at `/apps/new` (not a modal)
+  - Identity & Artifact section always visible; name editable pre-first-deploy, read-only after. JAR picker client-stages; new JAR + any form edits flip the primary button from `Save` to `Redeploy`. Environment fixed to the currently-selected env (no selector).
-  - Deployment progress: `ui/src/components/DeploymentProgress.tsx` (7-stage step indicator)
+  - Config sub-tabs: **Monitoring | Resources | Variables | Sensitive Keys | Deployment | ● Traces & Taps | ● Route Recording**. The four staged tabs feed dirty detection; the `●` live tabs apply in real-time (amber LiveBanner + default `?apply=live` on their writes) and never mark dirty.
+  - Primary action state machine: `Save` → `Uploading… N%` (during JAR upload; button shows percent with a tinted progress-fill overlay) → `Redeploy` → `Deploying…` during active deploy. Upload progress sourced from `useUploadJar` (XHR `upload.onprogress` → page-level `uploadPct` state). The button is disabled during `uploading` and `deploying`.
+  - Checkpoints render as a collapsible `CheckpointsTable` (default **collapsed**) **inside the Identity & Artifact `configGrid`** as an in-grid row (`Checkpoints | ▸ Expand (N)` / `▾ Collapse (N)`). `CheckpointsTable` returns a React.Fragment of grid-ready children so the label + trigger align with the other identity rows; when opened, a third grid child spans both columns via `grid-column: 1 / -1` so the 7-column table gets full width. Wired through `IdentitySection.checkpointsSlot` — `CheckpointDetailDrawer` stays in `IdentitySection.children` because it portals. Columns: Version · JAR (filename) · Deployed by · Deployed (relative `timeAgo` + user-locale sub-line via `new Date(iso).toLocaleString()`) · Strategy · Outcome · ›. Row click opens the drawer. Drawer tabs are ordered **Config | Logs** with `Config` as the default. Config panel has Snapshot / Diff vs current view modes. Replica filter in the Logs panel uses DS `Select`. Restore lives in the drawer footer (forces review). Visible row cap = `Environment.jarRetentionCount` (default 10 if 0/null); older rows accessible via "Show older (N)" expander. Currently-running deployment is excluded — represented separately by `StatusCard`. The empty-checkpoints case returns `null` (no row). The legacy `Checkpoints.tsx` row-list component is gone.
+  - Deployment tab: `StatusCard` + `DeploymentProgress` (during STARTING / FAILED) + flex-grow `StartupLogPanel` (no fixed maxHeight). Auto-activates when a deploy starts. The former `HistoryDisclosure` is retired — per-deployment config and logs live in the Checkpoints drawer. `StartupLogPanel` header mirrors the Runtime Application Log pattern: title + live/stopped badge + `N entries` + sort toggle (↑/↓, default **desc**) + refresh icon (`RefreshCw`). Sort drives the backend fetch via `useStartupLogs(…, sort)` so the 500-line limit returns the window closest to the user's interest; display order matches fetch order. Refresh scrolls to the latest edge (top for desc, bottom for asc). Sort + refresh buttons disable while a refetch is in flight. 3s polling while STARTING is unchanged.
+  - Unsaved-change router blocker uses DS `AlertDialog` (not `window.beforeunload`). Env switch intentionally discards edits without warning.
 
 **Admin pages** (ADMIN-only, under `/admin/`):
 - **Sensitive Keys** (`ui/src/pages/Admin/SensitiveKeysPage.tsx`) — global sensitive key masking config. Shows agent built-in defaults as outlined Badge reference, editable Tag pills for custom keys, amber-highlighted push-to-agents toggle. Keys add to (not replace) agent defaults. Per-app sensitive key additions managed via `ApplicationConfigController` API. Note: `AppConfigDetailPage.tsx` exists but is not routed in `router.tsx`.
+- **Server Metrics** (`ui/src/pages/Admin/ServerMetricsAdminPage.tsx`) — dashboard over the `server_metrics` ClickHouse table. Visibility matches Database/ClickHouse pages: gated on `capabilities.infrastructureEndpoints` in `buildAdminTreeNodes`; backend is `@ConditionalOnProperty(infrastructureendpoints) + @PreAuthorize('hasRole(ADMIN)')`. Uses the generic `/api/v1/admin/server-metrics/{catalog,instances,query}` API via `ui/src/api/queries/admin/serverMetrics.ts` hooks (`useServerMetricsCatalog`, `useServerMetricsInstances`, `useServerMetricsSeries`), all three of which take a `ServerMetricsRange = { from: Date; to: Date }`. Time range is driven by the global TopBar picker via `useGlobalFilters()` — no page-local selector; bucket size auto-scales through `stepSecondsFor(windowSeconds)` (10 s up to 1 h buckets). Toolbar is just server-instance badges. Sections: Server health (agents/ingestion/auth), JVM (memory/CPU/GC/threads), HTTP & DB pools, Alerting (conditional on catalog), Deployments (conditional on catalog). Each panel is a `ThemedChart` with `Line`/`Area` children from the design system; multi-series responses are flattened into overlap rows by bucket timestamp. Alerting and Deployments rows are hidden when their metrics aren't in the catalog (zero-deploy / alerting-disabled installs).
 
 ## Key UI Files
 
@@ -25,6 +30,8 @@ The UI has 4 main tabs: **Exchanges**, **Dashboard**, **Runtime**, **Deployments
 - `ui/src/auth/auth-store.ts` — Zustand: accessToken, user, roles, login/logout
 - `ui/src/api/environment-store.ts` — Zustand: selected environment (localStorage)
 - `ui/src/components/ContentTabs.tsx` — main tab switcher
+- `ui/src/components/EnvironmentSwitcherButton.tsx` + `EnvironmentSwitcherModal.tsx` — explicit env picker (button in TopBar; DS `Modal`-based list). Replaces the retired `EnvironmentSelector` (All-Envs dropdown). When `envRecords.length > 0` and the stored `selectedEnv` no longer matches any env, `LayoutShell` opens the modal in `forced` mode (non-dismissible). Switcher pulls env records from `useEnvironments()` (admin endpoint; readable by VIEWER+).
+- `ui/src/components/env-colors.ts` + `ui/src/styles/env-colors.css` — 8-swatch preset palette for the per-environment color indicator. Tokens `--env-color-slate/red/amber/green/teal/blue/purple/pink` are defined for both light and dark themes. `envColorVar(name)` falls back to `slate` for unknown values. `LayoutShell` renders a 3px fixed top bar in the current env's color (z-index 900, below DS modals).
 - `ui/src/components/ExecutionDiagram/` — interactive trace view (canvas)
 - `ui/src/components/ProcessDiagram/` — ELK-rendered route diagram
 - `ui/src/hooks/useScope.ts` — TabKey type, scope inference
@@ -33,6 +40,7 @@ The UI has 4 main tabs: **Exchanges**, **Dashboard**, **Runtime**, **Deployments
 - `ui/src/api/queries/agents.ts` — `useAgents` for agent list, `useInfiniteAgentEvents` for cursor-paginated timeline stream
 - `ui/src/hooks/useInfiniteStream.ts` — tanstack `useInfiniteQuery` wrapper with top-gated auto-refetch, flattened `items[]`, and `refresh()` invalidator
 - `ui/src/components/InfiniteScrollArea.tsx` — scrollable container with IntersectionObserver top/bottom sentinels. Streaming log/event views use this + `useInfiniteStream`. Bounded views (LogTab, StartupLogPanel) keep `useLogs`/`useStartupLogs`
+- `ui/src/components/SideDrawer.tsx` — project-local right-slide drawer (DS has Modal but no Drawer). Portal-rendered, ESC + transparent-backdrop click closes, sticky header/footer, sizes md/lg/xl. Currently consumed only by `CheckpointDetailDrawer` — promote to `@cameleer/design-system` once a second consumer appears.
 
 ## Alerts
 

.gitea/workflows/ci.yml

@@ -5,8 +5,20 @@ on:
     branches: [main, 'feature/**', 'fix/**', 'feat/**']
     tags-ignore:
       - 'v*'
+    paths-ignore:
+      - '.planning/**'
+      - 'docs/**'
+      - '**/*.md'
+      - '.claude/**'
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
   pull_request:
     branches: [main]
+    paths-ignore:
+      - '.planning/**'
+      - 'docs/**'
+      - '**/*.md'
+      - '.claude/**'
   delete:
 
 jobs:
@@ -45,11 +57,25 @@ jobs:
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-maven-
 
+      - name: Cache npm registry
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('ui/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-npm-
+
+      - name: Cache Vite build artifacts
+        uses: actions/cache@v4
+        with:
+          path: ui/node_modules/.vite
+          key: ${{ runner.os }}-vite-${{ hashFiles('ui/package-lock.json', 'ui/vite.config.ts') }}
+          restore-keys: ${{ runner.os }}-vite-
+
       - name: Build UI
         working-directory: ui
         run: |
           echo '//gitea.siegeln.net/api/packages/cameleer/npm/:_authToken=${REGISTRY_TOKEN}' >> .npmrc
-          npm ci
+          npm ci --prefer-offline --no-audit --fund=false
           npm run build
         env:
           REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
@@ -58,6 +84,12 @@ jobs:
       - name: Build and Test
         run: mvn clean verify -DskipITs -U --batch-mode
 
+      - name: Deploy minter to Maven registry
+        if: github.event_name == 'push'
+        run: mvn deploy -DskipTests -DskipITs --batch-mode -pl .,cameleer-license-api,cameleer-server-core,cameleer-license-minter
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+
   docker:
     needs: build
     runs-on: ubuntu-latest

AGENTS.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer-server** (8778 symbols, 22647 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer-server** (9731 symbols, 24987 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -10,20 +10,42 @@ Cameleer Server — observability server that receives, stores, and serves Camel
 
 - **cameleer** (`https://gitea.siegeln.net/cameleer/cameleer`) — the Java agent that instruments Camel applications
 - Protocol defined in `cameleer-common/PROTOCOL.md` in the agent repo
-- This server depends on `com.cameleer:cameleer-common` (shared models and graph API)
+- This server depends on `io.cameleer:cameleer-common` (shared models and graph API).
+
+## Registry naming (buildtime vs public)
+
+The Gitea container / Maven / npm registry has **two DNS names that resolve to the same instance**:
+
+- `gitea.siegeln.net` — internal hostname. CI pushes images here; `pom.xml`, `ui/.npmrc`, `ui/Dockerfile`, `ui/package-lock.json`, `deploy/`, and `.gitea/workflows/*.yml` all reference it. **Buildtime infrastructure.**
+- `registry.cameleer.io` — public alias customers pull from. Compiled-in defaults (`application.yml`, `DeploymentExecutor.java` `@Value`), customer-facing docs (`HOWTO.md`, `ui/README.md`), and runtime image refs use this. **Customer-visible.**
+
+The asymmetry is **intentional** during the institutionalization period — CI keeps publishing to the internal name while everything customer-shipped speaks the public name. Don't "fix" mismatches between, e.g., `pom.xml`'s registry URL and `application.yml`'s loader-image default; they speak to different audiences.
 
 ## Modules
 
+- `cameleer-license-api` — pure license contract types (`LicenseInfo`, `LicenseValidator`, `LicenseState`, `LicenseStateMachine`, `LicenseLimits`, `DefaultTierLimits`) under package `io.cameleer.license`. No Spring or server-runtime deps; consumed by `cameleer-server-core` (validation/runtime gate) and `cameleer-license-minter` (vendor signing) — and transitively by `cameleer-saas` via the minter — without inheriting server internals.
 - `cameleer-server-core` — domain logic, storage interfaces, services (no Spring dependencies)
 - `cameleer-server-app` — Spring Boot web app, REST controllers, SSE, persistence, Docker orchestration
+- `cameleer-license-minter` — vendor-only Ed25519 license signing library + CLI. Depends only on `cameleer-license-api` so consumers don't pull in `cameleer-server-core`.
 
 ## Build Commands
 
 ```bash
 mvn clean compile          # Compile all modules
 mvn clean verify           # Full build with tests
+mvn clean verify -DskipITs # Fast: unit tests only (no Testcontainers)
 ```
 
+### Faster local builds
+
+- **Surefire reuses forks** (`cameleer-server-app/pom.xml`): unit tests run with `forkCount=1C` + `reuseForks=true` — one JVM per CPU core, reused across classes. Test classes that mutate static state must clean up after themselves.
+- **Testcontainers reuse** — opt-in per developer. Add to `~/.testcontainers.properties`:
+  ```
+  testcontainers.reuse.enable=true
+  ```
+  Then `AbstractPostgresIT` containers persist across `mvn verify` runs (saves ~20s per run). Stop them manually when you need a clean DB: `docker rm -f $(docker ps -aq --filter label=org.testcontainers.reuse=true)`.
+- **UI build** dropped redundant `tsc --noEmit` from `npm run build` (Vite/esbuild type-checks during bundling). Run `npm run typecheck` explicitly when you want a full type-check pass.
+
 ## Run
 
 ```bash
@@ -34,7 +56,7 @@ java -jar cameleer-server-app/target/cameleer-server-app-1.0-SNAPSHOT.jar
 
 - Java 17+ required
 - Spring Boot 3.4.3 parent POM
-- Depends on `com.cameleer:cameleer-common` from Gitea Maven registry
+- Depends on `io.cameleer:cameleer-common` from Gitea Maven registry
 - Jackson `JavaTimeModule` for `Instant` deserialization
 - Communication: receives HTTP POST data from agents (executions, diagrams, metrics, logs), serves SSE event streams for config push/commands (config-update, deep-trace, replay, route-control)
 - URL taxonomy: user-facing data, config, and query endpoints live under `/api/v1/environments/{envSlug}/...`. Env is a path segment, resolved via the `@EnvPath` argument resolver (404 on unknown slug). Flat endpoints are only for: agent self-service (JWT-authoritative), cross-env admin (RBAC, OIDC, audit, license, thresholds, env CRUD), cross-env discovery (`/catalog`), content-addressed lookups (`/diagrams/{contentHash}/render`, `/executions/{id}`), and auth. See `.claude/rules/app-classes.md` for the full allow-list.
@@ -48,8 +70,10 @@ java -jar cameleer-server-app/target/cameleer-server-app-1.0-SNAPSHOT.jar
 - Log processor correlation: The agent sets `cameleer.processorId` in MDC, identifying which processor node emitted a log line.
 - Logging: ClickHouse JDBC set to INFO (`com.clickhouse`), HTTP client to WARN (`org.apache.hc.client5`) in application.yml
 - Security: JWT auth with RBAC (AGENT/VIEWER/OPERATOR/ADMIN roles), Ed25519 config signing (key derived deterministically from JWT secret via HMAC-SHA256), bootstrap token for registration. CORS: `CAMELEER_SERVER_SECURITY_CORSALLOWEDORIGINS` (comma-separated) overrides `CAMELEER_SERVER_SECURITY_UIORIGIN` for multi-origin setups. Infrastructure access: `CAMELEER_SERVER_SECURITY_INFRASTRUCTUREENDPOINTS=false` disables Database and ClickHouse admin endpoints. Last-ADMIN guard: system prevents removal of the last ADMIN role (409 Conflict). Password policy: min 12 chars, 3-of-4 character classes, no username match. Brute-force protection: 5 failed attempts -> 15 min lockout. Token revocation: `token_revoked_before` column on users, checked in `JwtAuthenticationFilter`, set on password change.
+- Login routing: `GET /api/v1/auth/capabilities` (unauthenticated) tells the SPA whether OIDC is the primary entry point. When OIDC is configured, the SSO button is the primary CTA and the local form is hidden behind `?local` (admin-recovery escape hatch). Per RFC 9700 §4.4 we do **not** use `prompt=none` for primary login — that returns `login_required` for first-time users and traps them on a local form.
 - OIDC: Optional external identity provider support (token exchange pattern). Configured via admin API/UI, stored in database (`server_config` table). Resource server mode: accepts external access tokens (Logto M2M) via JWKS validation when `CAMELEER_SERVER_SECURITY_OIDCISSUERURI` is set. Scope-based role mapping via `SystemRole.normalizeScope()`. System roles synced on every OIDC login via `applyClaimMappings()` in `OidcAuthController` (calls `clearManagedAssignments` + `assignManagedRole` on `RbacService`) — always overwrites managed role assignments; uses managed assignment origin to avoid touching group-inherited or directly-assigned roles. Supports ES384, ES256, RS256.
 - OIDC role extraction: `OidcTokenExchanger` reads roles from the **access_token** first (JWT with `at+jwt` type), then falls back to id_token. `OidcConfig` includes `audience` (RFC 8707 resource indicator) and `additionalScopes`. All provider-specific configuration is external — no provider-specific code in the server.
+- Container orchestration: tenant containers no longer bind-mount JARs from the host. `DockerRuntimeOrchestrator.startContainer` runs a 2-phase op per replica — a `cameleer-runtime-loader` init container fetches the JAR from a signed URL into a per-replica named volume, then the main container mounts that volume RO at `/app/jars`. The loader image (default `registry.cameleer.io/cameleer/cameleer-runtime-loader:latest`) is built and published by **cameleer-saas** at `docker/runtime-loader/` — this repo only consumes it. (Same image, internal push target is `gitea.siegeln.net/cameleer/cameleer-runtime-loader:latest`; see "Registry naming" above.) Env vars: `CAMELEER_SERVER_RUNTIME_LOADERIMAGE` (override loader image); `CAMELEER_SERVER_RUNTIME_ARTIFACTTOKENTTLSECONDS` (signed-URL TTL, default `600`); `CAMELEER_SERVER_RUNTIME_ARTIFACTBASEURL` (base URL the loader uses to reach the server; defaults to `cameleer.server.runtime.serverurl`, then `http://cameleer-server:8081`). See `.claude/rules/docker-orchestration.md` for the full loader pattern; `LoaderHardeningIT` is the cross-repo contract test.
 - Sensitive keys: Global enforced baseline for masking sensitive data in agent payloads. Merge rule: `final = global UNION per-app` (case-insensitive dedup, per-app can only add, never remove global keys).
 - User persistence: PostgreSQL `users` table, admin CRUD at `/api/v1/admin/users`. `users.user_id` is the **bare** identifier — local users as `<username>`, OIDC users as `oidc:<sub>`. JWT `sub` carries the `user:` namespace prefix so `JwtAuthenticationFilter` can tell user tokens from agent tokens; write paths (`UiAuthController`, `OidcAuthController`, `UserAdminController`) all upsert unprefixed, and env-scoped read-path controllers strip the `user:` prefix before using the value as an FK to `users.user_id` / `user_roles.user_id`. Alerting / outbound FKs (`alert_rules.created_by`, `outbound_connections.created_by`, …) therefore all reference the bare form.
 - Usage analytics: ClickHouse `usage_events` table tracks authenticated UI requests, flushed every 5s
@@ -85,7 +109,7 @@ When adding, removing, or renaming classes, controllers, endpoints, UI component
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer-server** (8778 symbols, 22647 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer-server** (10697 symbols, 27649 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

HOWTO.md

@@ -238,7 +238,7 @@ Logto is proxy-aware via `TRUST_PROXY_HEADER=1`. The `LOGTO_ENDPOINT` and `LOGTO
    - Note the **Client ID**
 3. **Create API Resource**: API Resources → Create
    - Name: `Cameleer Server API`
-   - Indicator: your API URL (e.g., `https://cameleer.siegeln.net/api`)
+   - Indicator: your API URL (e.g., `https://cameleer.example.com/api`)
    - Add permissions: `server:admin`, `server:operator`, `server:viewer`
 4. **Create M2M application** (for SaaS platform): Applications → Create → Machine-to-Machine
    - Name: `Cameleer SaaS`
@@ -494,11 +494,15 @@ Key settings in `cameleer-server-app/src/main/resources/application.yml`. All cu
 | `cameleer.server.runtime.enabled` | `true` | `CAMELEER_SERVER_RUNTIME_ENABLED` | Enable Docker orchestration |
 | `cameleer.server.runtime.baseimage` | `cameleer-runtime-base:latest` | `CAMELEER_SERVER_RUNTIME_BASEIMAGE` | Base Docker image for app containers |
 | `cameleer.server.runtime.dockernetwork` | `cameleer` | `CAMELEER_SERVER_RUNTIME_DOCKERNETWORK` | Primary Docker network |
-| `cameleer.server.runtime.jarstoragepath` | `/data/jars` | `CAMELEER_SERVER_RUNTIME_JARSTORAGEPATH` | JAR file storage directory |
+| `cameleer.server.runtime.dockerruntime` | *(empty = auto)* | `CAMELEER_SERVER_RUNTIME_DOCKERRUNTIME` | Container runtime override. Empty auto-detects gVisor (`runsc`) when registered with the daemon and falls back to the daemon default. Set to e.g. `kata` to force a specific runtime, or `runc` to force the default even if `runsc` is installed. |
-| `cameleer.server.runtime.jardockervolume` | *(empty)* | `CAMELEER_SERVER_RUNTIME_JARDOCKERVOLUME` | Docker volume for JAR sharing |
+| `cameleer.server.runtime.jarstoragepath` | `/data/jars` | `CAMELEER_SERVER_RUNTIME_JARSTORAGEPATH` | JAR file storage directory (used by `FilesystemArtifactStore`) |
+| `cameleer.server.runtime.loaderimage` | `registry.cameleer.io/cameleer/cameleer-runtime-loader:latest` | `CAMELEER_SERVER_RUNTIME_LOADERIMAGE` | Init-container image that fetches the JAR via signed URL |
+| `cameleer.server.runtime.artifacttokenttlseconds` | `600` | `CAMELEER_SERVER_RUNTIME_ARTIFACTTOKENTTLSECONDS` | TTL (seconds) for HMAC-signed artifact-download URLs |
+| `cameleer.server.runtime.artifactbaseurl` | *(empty)* | `CAMELEER_SERVER_RUNTIME_ARTIFACTBASEURL` | Base URL the loader uses to reach the server. Blank falls back to `serverurl`, then `http://cameleer-server:8081`. Must be reachable from the loader container's primary Docker network. |
 | `cameleer.server.runtime.routingmode` | `path` | `CAMELEER_SERVER_RUNTIME_ROUTINGMODE` | `path` or `subdomain` Traefik routing |
 | `cameleer.server.runtime.routingdomain` | `localhost` | `CAMELEER_SERVER_RUNTIME_ROUTINGDOMAIN` | Domain for Traefik routing labels |
 | `cameleer.server.runtime.serverurl` | *(empty)* | `CAMELEER_SERVER_RUNTIME_SERVERURL` | Server URL injected into app containers |
+| `cameleer.server.runtime.certresolver` | *(empty)* | `CAMELEER_SERVER_RUNTIME_CERTRESOLVER` | Traefik TLS cert resolver name (e.g. `letsencrypt`). Blank = omit the `tls.certresolver` label and let Traefik serve the default TLS-store cert |
 | `cameleer.server.runtime.agenthealthport` | `9464` | `CAMELEER_SERVER_RUNTIME_AGENTHEALTHPORT` | Agent health check port |
 | `cameleer.server.runtime.healthchecktimeout` | `60` | `CAMELEER_SERVER_RUNTIME_HEALTHCHECKTIMEOUT` | Health check timeout (seconds) |
 | `cameleer.server.runtime.container.memorylimit` | `512m` | `CAMELEER_SERVER_RUNTIME_CONTAINER_MEMORYLIMIT` | Default memory limit for app containers |
@@ -587,10 +591,10 @@ cameleer-demo namespace:
 
 | Service | URL |
 |---------|-----|
-| Web UI | `http://192.168.50.86:30090` |
+| Web UI | `http://<your-cluster-host>:30090` |
-| Server API | `http://192.168.50.86:30081/api/v1/health` |
+| Server API | `http://<your-cluster-host>:30081/api/v1/health` |
-| Swagger UI | `http://192.168.50.86:30081/api/v1/swagger-ui.html` |
+| Swagger UI | `http://<your-cluster-host>:30081/api/v1/swagger-ui.html` |
-| Deploy Demo | `http://192.168.50.86:30092` |
+| Deploy Demo | `http://<your-cluster-host>:30092` |
 | Logto API | `LOGTO_ENDPOINT` secret (NodePort 30951 direct, or behind reverse proxy) |
 | Logto Admin | `LOGTO_ADMIN_ENDPOINT` secret (NodePort 30952 direct, or behind reverse proxy) |
 

cameleer-license-api/pom.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.cameleer</groupId>
+        <artifactId>cameleer-server-parent</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>cameleer-license-api</artifactId>
+    <name>Cameleer License API</name>
+    <description>Pure license contract types — LicenseInfo, LicenseValidator, LicenseState, LicenseStateMachine, LicenseLimits, DefaultTierLimits. Shared by server-core (validation/runtime gate) and cameleer-license-minter (vendor-side signing). Has no Spring or server-runtime dependencies so consumers like cameleer-saas can depend on the minter without inheriting server internals.</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <executions>
+                    <!-- Plain library JAR — no repackage. -->
+                    <execution>
+                        <id>repackage</id>
+                        <phase>none</phase>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

cameleer-license-api/src/main/java/io/cameleer/license/DefaultTierLimits.java

@@ -0,0 +1,30 @@
+package io.cameleer.license;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public final class DefaultTierLimits {
+
+    public static final Map<String, Integer> DEFAULTS;
+
+    static {
+        Map<String, Integer> m = new LinkedHashMap<>();
+        m.put("max_environments", 1);
+        m.put("max_apps", 3);
+        m.put("max_agents", 5);
+        m.put("max_users", 3);
+        m.put("max_outbound_connections", 1);
+        m.put("max_alert_rules", 2);
+        m.put("max_total_cpu_millis", 2000);
+        m.put("max_total_memory_mb", 2048);
+        m.put("max_total_replicas", 5);
+        m.put("max_execution_retention_days", 1);
+        m.put("max_log_retention_days", 1);
+        m.put("max_metric_retention_days", 1);
+        m.put("max_jar_retention_count", 3);
+        DEFAULTS = Collections.unmodifiableMap(m);
+    }
+
+    private DefaultTierLimits() {}
+}

cameleer-license-api/src/main/java/io/cameleer/license/LicenseInfo.java

@@ -0,0 +1,46 @@
+package io.cameleer.license;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.Objects;
+import java.util.UUID;
+
+/** A parsed and signature-verified license. Construct via {@link LicenseValidator}. */
+public record LicenseInfo(
+        UUID licenseId,
+        String tenantId,
+        String label,
+        Map<String, Integer> limits,
+        Instant issuedAt,
+        Instant expiresAt,
+        int gracePeriodDays
+) {
+    public LicenseInfo {
+        Objects.requireNonNull(licenseId, "licenseId is required");
+        Objects.requireNonNull(tenantId, "tenantId is required");
+        Objects.requireNonNull(limits, "limits is required");
+        Objects.requireNonNull(issuedAt, "issuedAt is required");
+        Objects.requireNonNull(expiresAt, "expiresAt is required");
+        if (tenantId.isBlank()) {
+            throw new IllegalArgumentException("tenantId must not be blank");
+        }
+        if (gracePeriodDays < 0) {
+            throw new IllegalArgumentException("gracePeriodDays must be >= 0");
+        }
+    }
+
+    /** True iff now > expiresAt + gracePeriodDays. */
+    public boolean isExpired() {
+        Instant deadline = expiresAt.plusSeconds((long) gracePeriodDays * 86400);
+        return Instant.now().isAfter(deadline);
+    }
+
+    /** True iff now > expiresAt (regardless of grace). Used by the state machine to distinguish ACTIVE from GRACE. */
+    public boolean isAfterRawExpiry() {
+        return Instant.now().isAfter(expiresAt);
+    }
+
+    public int getLimit(String key, int defaultValue) {
+        return limits.getOrDefault(key, defaultValue);
+    }
+}

cameleer-license-api/src/main/java/io/cameleer/license/LicenseLimits.java

@@ -0,0 +1,36 @@
+package io.cameleer.license;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+
+public record LicenseLimits(Map<String, Integer> values) {
+
+    public LicenseLimits {
+        Objects.requireNonNull(values, "values");
+    }
+
+    public static LicenseLimits defaultsOnly() {
+        return new LicenseLimits(DefaultTierLimits.DEFAULTS);
+    }
+
+    public static LicenseLimits mergeOverDefaults(Map<String, Integer> overrides) {
+        Map<String, Integer> merged = new LinkedHashMap<>(DefaultTierLimits.DEFAULTS);
+        if (overrides != null) merged.putAll(overrides);
+        return new LicenseLimits(Collections.unmodifiableMap(merged));
+    }
+
+    public int get(String key) {
+        Integer v = values.get(key);
+        if (v == null) {
+            throw new IllegalArgumentException("Unknown license limit key: " + key);
+        }
+        return v;
+    }
+
+    public boolean isDefaultSourced(String key, LicenseInfo license) {
+        if (license == null) return true;
+        return !license.limits().containsKey(key);
+    }
+}

cameleer-license-api/src/main/java/io/cameleer/license/LicenseState.java

@@ -0,0 +1,9 @@
+package io.cameleer.license;
+
+public enum LicenseState {
+    ABSENT,
+    ACTIVE,
+    GRACE,
+    EXPIRED,
+    INVALID
+}

cameleer-license-api/src/main/java/io/cameleer/license/LicenseStateMachine.java

@@ -0,0 +1,26 @@
+package io.cameleer.license;
+
+public final class LicenseStateMachine {
+
+    private LicenseStateMachine() {}
+
+    /**
+     * @param license  parsed license, or null if no license is loaded
+     * @param invalidReason non-null if the last validation attempt failed
+     */
+    public static LicenseState classify(LicenseInfo license, String invalidReason) {
+        if (invalidReason != null) {
+            return LicenseState.INVALID;
+        }
+        if (license == null) {
+            return LicenseState.ABSENT;
+        }
+        if (!license.isAfterRawExpiry()) {
+            return LicenseState.ACTIVE;
+        }
+        if (!license.isExpired()) {
+            return LicenseState.GRACE;
+        }
+        return LicenseState.EXPIRED;
+    }
+}

cameleer-license-api/src/main/java/io/cameleer/license/LicenseValidator.java

@@ -1,14 +1,20 @@
-package com.cameleer.server.core.license;
+package io.cameleer.license;
 
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import java.security.*;
+import java.security.KeyFactory;
+import java.security.PublicKey;
+import java.security.Signature;
 import java.security.spec.X509EncodedKeySpec;
 import java.time.Instant;
-import java.util.*;
+import java.util.Base64;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.UUID;
 
 public class LicenseValidator {
 
@@ -16,8 +22,13 @@ public class LicenseValidator {
     private static final ObjectMapper objectMapper = new ObjectMapper();
 
     private final PublicKey publicKey;
+    private final String expectedTenantId;
 
-    public LicenseValidator(String publicKeyBase64) {
+    public LicenseValidator(String publicKeyBase64, String expectedTenantId) {
+        Objects.requireNonNull(expectedTenantId, "expectedTenantId is required");
+        if (expectedTenantId.isBlank()) {
+            throw new IllegalArgumentException("expectedTenantId must not be blank");
+        }
         try {
             byte[] keyBytes = Base64.getDecoder().decode(publicKeyBase64);
             KeyFactory kf = KeyFactory.getInstance("Ed25519");
@@ -25,6 +36,7 @@ public class LicenseValidator {
         } catch (Exception e) {
             throw new IllegalStateException("Failed to load license public key", e);
         }
+        this.expectedTenantId = expectedTenantId;
     }
 
     public LicenseInfo validate(String token) {
@@ -36,7 +48,6 @@ public class LicenseValidator {
         byte[] payloadBytes = Base64.getDecoder().decode(parts[0]);
         byte[] signatureBytes = Base64.getDecoder().decode(parts[1]);
 
-        // Verify signature
         try {
             Signature verifier = Signature.getInstance("Ed25519");
             verifier.initVerify(publicKey);
@@ -50,23 +61,25 @@ public class LicenseValidator {
             throw new SecurityException("License signature verification failed", e);
         }
 
-        // Parse payload
         try {
             JsonNode root = objectMapper.readTree(payloadBytes);
 
-            String tier = root.get("tier").asText();
+            String licenseIdStr = textOrThrow(root, "licenseId");
-
+            UUID licenseId;
-            Set<Feature> features = new HashSet<>();
-            if (root.has("features")) {
-                for (JsonNode f : root.get("features")) {
             try {
-                        features.add(Feature.valueOf(f.asText()));
+                licenseId = UUID.fromString(licenseIdStr);
             } catch (IllegalArgumentException e) {
-                        log.warn("Unknown feature in license: {}", f.asText());
+                throw new IllegalArgumentException("licenseId is not a valid UUID: " + licenseIdStr);
-                    }
             }
+
+            String tenantId = textOrThrow(root, "tenantId");
+            if (!tenantId.equals(expectedTenantId)) {
+                throw new IllegalArgumentException(
+                        "License tenantId '" + tenantId + "' does not match server tenant '" + expectedTenantId + "'");
             }
 
+            String label = root.has("label") ? root.get("label").asText() : null;
+
             Map<String, Integer> limits = new HashMap<>();
             if (root.has("limits")) {
                 root.get("limits").fields().forEachRemaining(entry ->
@@ -74,12 +87,17 @@ public class LicenseValidator {
             }
 
             Instant issuedAt = root.has("iat") ? Instant.ofEpochSecond(root.get("iat").asLong()) : Instant.now();
-            Instant expiresAt = root.has("exp") ? Instant.ofEpochSecond(root.get("exp").asLong()) : null;
+            if (!root.has("exp")) {
+                throw new IllegalArgumentException("exp is required");
+            }
+            Instant expiresAt = Instant.ofEpochSecond(root.get("exp").asLong());
+            int gracePeriodDays = root.has("gracePeriodDays") ? root.get("gracePeriodDays").asInt() : 0;
 
-            LicenseInfo info = new LicenseInfo(tier, features, limits, issuedAt, expiresAt);
+            LicenseInfo info = new LicenseInfo(licenseId, tenantId, label, limits, issuedAt, expiresAt, gracePeriodDays);
 
             if (info.isExpired()) {
-                throw new IllegalArgumentException("License expired at " + expiresAt);
+                throw new IllegalArgumentException("License expired at " + expiresAt
+                        + " (grace period " + gracePeriodDays + " days)");
             }
 
             return info;
@@ -89,4 +107,11 @@ public class LicenseValidator {
             throw new IllegalArgumentException("Failed to parse license payload", e);
         }
     }
+
+    private static String textOrThrow(JsonNode root, String field) {
+        if (!root.has(field) || root.get(field).asText().isBlank()) {
+            throw new IllegalArgumentException(field + " is required");
+        }
+        return root.get(field).asText();
+    }
 }

cameleer-license-api/src/test/java/io/cameleer/license/DefaultTierLimitsTest.java

@@ -0,0 +1,30 @@
+package io.cameleer.license;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class DefaultTierLimitsTest {
+
+    @Test
+    void allDocumentedKeysHaveDefaults() {
+        for (String key : new String[]{
+                "max_environments", "max_apps", "max_agents", "max_users",
+                "max_outbound_connections", "max_alert_rules",
+                "max_total_cpu_millis", "max_total_memory_mb", "max_total_replicas",
+                "max_execution_retention_days", "max_log_retention_days",
+                "max_metric_retention_days", "max_jar_retention_count"
+        }) {
+            assertThat(DefaultTierLimits.DEFAULTS).containsKey(key);
+        }
+    }
+
+    @Test
+    void specificValues() {
+        assertThat(DefaultTierLimits.DEFAULTS.get("max_environments")).isEqualTo(1);
+        assertThat(DefaultTierLimits.DEFAULTS.get("max_apps")).isEqualTo(3);
+        assertThat(DefaultTierLimits.DEFAULTS.get("max_agents")).isEqualTo(5);
+        assertThat(DefaultTierLimits.DEFAULTS.get("max_total_cpu_millis")).isEqualTo(2000);
+        assertThat(DefaultTierLimits.DEFAULTS.get("max_log_retention_days")).isEqualTo(1);
+    }
+}

cameleer-license-api/src/test/java/io/cameleer/license/LicenseInfoTest.java

@@ -0,0 +1,64 @@
+package io.cameleer.license;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class LicenseInfoTest {
+
+    @Test
+    void requiresLicenseId() {
+        assertThatThrownBy(() -> new LicenseInfo(
+                null, "acme", "label",
+                Map.of(), Instant.now(), Instant.now().plusSeconds(60), 0))
+                .isInstanceOf(NullPointerException.class)
+                .hasMessageContaining("licenseId");
+    }
+
+    @Test
+    void requiresTenantId() {
+        assertThatThrownBy(() -> new LicenseInfo(
+                UUID.randomUUID(), null, "label",
+                Map.of(), Instant.now(), Instant.now().plusSeconds(60), 0))
+                .isInstanceOf(NullPointerException.class)
+                .hasMessageContaining("tenantId");
+    }
+
+    @Test
+    void emptyTenantIdRejected() {
+        assertThatThrownBy(() -> new LicenseInfo(
+                UUID.randomUUID(), "  ", "label",
+                Map.of(), Instant.now(), Instant.now().plusSeconds(60), 0))
+                .isInstanceOf(IllegalArgumentException.class);
+    }
+
+    @Test
+    void getLimit_returnsDefaultWhenMissing() {
+        LicenseInfo info = new LicenseInfo(
+                UUID.randomUUID(), "acme", null,
+                Map.of("max_apps", 5), Instant.now(),
+                Instant.now().plusSeconds(60), 0);
+        assertThat(info.getLimit("max_apps", 99)).isEqualTo(5);
+        assertThat(info.getLimit("max_users", 99)).isEqualTo(99);
+    }
+
+    @Test
+    void isExpired_honoursGracePeriod() {
+        Instant pastByTen = Instant.now().minusSeconds(10 * 86400);
+        LicenseInfo withinGrace = new LicenseInfo(
+                UUID.randomUUID(), "acme", null, Map.of(),
+                Instant.now().minusSeconds(40 * 86400),
+                pastByTen, 30);
+        assertThat(withinGrace.isExpired()).isFalse(); // 10 days into a 30-day grace
+        LicenseInfo pastGrace = new LicenseInfo(
+                UUID.randomUUID(), "acme", null, Map.of(),
+                Instant.now().minusSeconds(40 * 86400),
+                pastByTen, 5);
+        assertThat(pastGrace.isExpired()).isTrue(); // 10 days is past the 5-day grace
+    }
+}

cameleer-license-api/src/test/java/io/cameleer/license/LicenseStateMachineTest.java

@@ -0,0 +1,57 @@
+package io.cameleer.license;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class LicenseStateMachineTest {
+
+    @Test
+    void noLicense_isAbsent() {
+        assertThat(LicenseStateMachine.classify(null, null)).isEqualTo(LicenseState.ABSENT);
+    }
+
+    @Test
+    void invalidReason_isInvalid() {
+        assertThat(LicenseStateMachine.classify(null, "signature failed")).isEqualTo(LicenseState.INVALID);
+    }
+
+    @Test
+    void activeBeforeExp() {
+        LicenseInfo info = info(Instant.now().plusSeconds(86400), 0);
+        assertThat(LicenseStateMachine.classify(info, null)).isEqualTo(LicenseState.ACTIVE);
+    }
+
+    @Test
+    void graceWithinGracePeriod() {
+        LicenseInfo info = info(Instant.now().minusSeconds(86400), 7);
+        assertThat(LicenseStateMachine.classify(info, null)).isEqualTo(LicenseState.GRACE);
+    }
+
+    @Test
+    void expiredAfterGrace() {
+        LicenseInfo info = info(Instant.now().minusSeconds(8L * 86400), 7);
+        assertThat(LicenseStateMachine.classify(info, null)).isEqualTo(LicenseState.EXPIRED);
+    }
+
+    @Test
+    void expiredImmediatelyWithZeroGrace() {
+        LicenseInfo info = info(Instant.now().minusSeconds(60), 0);
+        assertThat(LicenseStateMachine.classify(info, null)).isEqualTo(LicenseState.EXPIRED);
+    }
+
+    @Test
+    void invalidWinsOverPresentLicense() {
+        LicenseInfo info = info(Instant.now().plusSeconds(86400), 0);
+        assertThat(LicenseStateMachine.classify(info, "tenant mismatch")).isEqualTo(LicenseState.INVALID);
+    }
+
+    private LicenseInfo info(Instant exp, int graceDays) {
+        return new LicenseInfo(UUID.randomUUID(), "acme", null, Map.of(),
+                Instant.now().minusSeconds(3600), exp, graceDays);
+    }
+}

cameleer-license-api/src/test/java/io/cameleer/license/LicenseValidatorTest.java

@@ -0,0 +1,141 @@
+package io.cameleer.license;
+
+import org.junit.jupiter.api.Test;
+
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
+import java.security.PrivateKey;
+import java.security.Signature;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.Base64;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class LicenseValidatorTest {
+
+    private KeyPair generateKeyPair() throws Exception {
+        KeyPairGenerator kpg = KeyPairGenerator.getInstance("Ed25519");
+        return kpg.generateKeyPair();
+    }
+
+    private String sign(PrivateKey key, String payload) throws Exception {
+        Signature signer = Signature.getInstance("Ed25519");
+        signer.initSign(key);
+        signer.update(payload.getBytes());
+        return Base64.getEncoder().encodeToString(signer.sign());
+    }
+
+    @Test
+    void validate_validLicense_returnsLicenseInfo() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "acme");
+
+        Instant expires = Instant.now().plus(365, ChronoUnit.DAYS);
+        String payload = """
+                {"licenseId":"%s","tenantId":"acme","label":"HIGH","tier":"HIGH","limits":{"max_agents":50,"retention_days":90},"iat":%d,"exp":%d,"gracePeriodDays":7}
+                """.formatted(UUID.randomUUID(), Instant.now().getEpochSecond(), expires.getEpochSecond()).trim();
+        String signature = sign(kp.getPrivate(), payload);
+        String token = Base64.getEncoder().encodeToString(payload.getBytes()) + "." + signature;
+
+        LicenseInfo info = validator.validate(token);
+
+        assertThat(info.label()).isEqualTo("HIGH");
+        assertThat(info.getLimit("max_agents", 0)).isEqualTo(50);
+        assertThat(info.isExpired()).isFalse();
+        assertThat(info.tenantId()).isEqualTo("acme");
+        assertThat(info.gracePeriodDays()).isEqualTo(7);
+    }
+
+    @Test
+    void validate_expiredLicense_throwsException() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "acme");
+
+        Instant past = Instant.now().minus(1, ChronoUnit.DAYS);
+        String payload = """
+                {"licenseId":"%s","tenantId":"acme","tier":"LOW","limits":{},"iat":%d,"exp":%d}
+                """.formatted(UUID.randomUUID(), past.minus(30, ChronoUnit.DAYS).getEpochSecond(), past.getEpochSecond()).trim();
+        String signature = sign(kp.getPrivate(), payload);
+        String token = Base64.getEncoder().encodeToString(payload.getBytes()) + "." + signature;
+
+        assertThatThrownBy(() -> validator.validate(token))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("expired");
+    }
+
+    @Test
+    void validate_tamperedPayload_throwsException() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "acme");
+
+        String payload = """
+                {"licenseId":"%s","tenantId":"acme","tier":"LOW","limits":{},"iat":0,"exp":9999999999}
+                """.formatted(UUID.randomUUID()).trim();
+        String signature = sign(kp.getPrivate(), payload);
+
+        // Tamper with payload
+        String tampered = payload.replace("LOW", "BUSINESS");
+        String token = Base64.getEncoder().encodeToString(tampered.getBytes()) + "." + signature;
+
+        assertThatThrownBy(() -> validator.validate(token))
+                .isInstanceOf(SecurityException.class)
+                .hasMessageContaining("signature");
+    }
+
+    @Test
+    void validate_missingTenantId_throws() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "acme");
+
+        Instant exp = Instant.now().plus(30, ChronoUnit.DAYS);
+        String payload = """
+                {"licenseId":"%s","tier":"X","limits":{},"iat":%d,"exp":%d}
+                """.formatted(UUID.randomUUID(), Instant.now().getEpochSecond(), exp.getEpochSecond()).trim();
+        String token = Base64.getEncoder().encodeToString(payload.getBytes()) + "." + sign(kp.getPrivate(), payload);
+
+        assertThatThrownBy(() -> validator.validate(token))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("tenantId");
+    }
+
+    @Test
+    void validate_tenantIdMismatch_throws() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "beta");
+
+        Instant exp = Instant.now().plus(30, ChronoUnit.DAYS);
+        String payload = """
+                {"licenseId":"%s","tenantId":"acme","tier":"X","limits":{},"iat":%d,"exp":%d}
+                """.formatted(UUID.randomUUID(), Instant.now().getEpochSecond(), exp.getEpochSecond()).trim();
+        String token = Base64.getEncoder().encodeToString(payload.getBytes()) + "." + sign(kp.getPrivate(), payload);
+
+        assertThatThrownBy(() -> validator.validate(token))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("tenantId");
+    }
+
+    @Test
+    void validate_missingLicenseId_throws() throws Exception {
+        KeyPair kp = generateKeyPair();
+        String publicKeyBase64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+        LicenseValidator validator = new LicenseValidator(publicKeyBase64, "acme");
+
+        Instant exp = Instant.now().plus(30, ChronoUnit.DAYS);
+        String payload = """
+                {"tenantId":"acme","tier":"X","limits":{},"iat":%d,"exp":%d}
+                """.formatted(Instant.now().getEpochSecond(), exp.getEpochSecond()).trim();
+        String token = Base64.getEncoder().encodeToString(payload.getBytes()) + "." + sign(kp.getPrivate(), payload);
+
+        assertThatThrownBy(() -> validator.validate(token))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("licenseId");
+    }
+}

cameleer-license-minter/README.md

@@ -0,0 +1,287 @@
+# cameleer-license-minter
+
+Standalone vendor-side tool for producing signed Ed25519 license tokens consumed by `cameleer-server`. The minter is intentionally **not** a runtime or compile-scope dependency of the server — the server only ships with the matching public key and validates tokens via `LicenseValidator`. The private signing key never leaves the vendor's environment.
+
+- Module GAV: `io.cameleer:cameleer-license-minter:1.0-SNAPSHOT`
+- Maven coordinates of the runtime server (does **not** transitively pull this module): `io.cameleer:cameleer-server-app:1.0-SNAPSHOT`
+- Build artifacts (after `mvn -pl cameleer-license-minter package`):
+  - `target/cameleer-license-minter-1.0-SNAPSHOT.jar` — plain library JAR (consumable as a Maven `test` dependency or via the `LicenseMinter` API in custom tooling)
+  - `target/cameleer-license-minter-1.0-SNAPSHOT-cli.jar` — fat CLI JAR with main class `io.cameleer.license.minter.cli.LicenseMinterCli`
+
+## Table of contents
+
+## Audience
+
+## Build
+
+## Public Java API
+
+## CLI usage
+
+## Token format
+
+## LicenseInfo schema
+
+## Limits dictionary
+
+## Generating an Ed25519 key pair
+
+## Worked example
+
+## Security guidance
+
+## Compatibility / runtime separation
+
+---
+
+## Audience
+
+Vendors / SaaS operators issuing licenses to customers who run `cameleer-server`. End-customer operators looking for *how to install* a token should read `docs/license-enforcement.md` instead.
+
+## Build
+
+```bash
+# From the repo root
+mvn -pl cameleer-license-minter package
+```
+
+Two JARs land in `cameleer-license-minter/target/`:
+
+| Artifact | Purpose |
+|---|---|
+| `cameleer-license-minter-1.0-SNAPSHOT.jar` | Plain library (the `repackage` execution for the main artifact is disabled; see `pom.xml:50-54`). Use this when embedding the minter inside your own tooling or a unit test that needs a fresh signed token. |
+| `cameleer-license-minter-1.0-SNAPSHOT-cli.jar` | Fat CLI JAR. Repackaged by Spring Boot's `spring-boot-maven-plugin` with classifier `cli`; main class is `io.cameleer.license.minter.cli.LicenseMinterCli`. |
+
+## Public Java API
+
+`io.cameleer.license.minter.LicenseMinter` is the only entry point for the library. It is a final, stateless utility class:
+
+```java
+import io.cameleer.license.minter.LicenseMinter;
+import io.cameleer.license.LicenseInfo;
+
+LicenseInfo info = new LicenseInfo(
+        java.util.UUID.randomUUID(),
+        "acme-prod",                               // tenantId — must match server's CAMELEER_SERVER_TENANT_ID
+        "Acme Production (Tier B)",                 // human label, optional
+        java.util.Map.of(
+                "max_environments", 3,
+                "max_apps",         25,
+                "max_agents",       50,
+                "max_users",        20,
+                "max_total_replicas", 30
+        ),
+        java.time.Instant.now(),                    // issuedAt
+        java.time.Instant.parse("2027-01-01T00:00:00Z"), // expiresAt
+        7                                           // gracePeriodDays
+);
+
+String token = LicenseMinter.mint(info, ed25519PrivateKey);
+```
+
+Source: `cameleer-license-minter/src/main/java/com/cameleer/license/minter/LicenseMinter.java:20`.
+
+The method is thread-safe; the underlying Jackson `ObjectMapper` is configured once with `ORDER_MAP_ENTRIES_BY_KEYS` so canonical-JSON serialization is deterministic across runs and process boundaries.
+
+`LicenseMinter.mint` will throw `IllegalStateException` if the JCE provider rejects the private key or the payload cannot be serialized.
+
+## CLI usage
+
+The CLI entry point is `io.cameleer.license.minter.cli.LicenseMinterCli`. Run it from the fat JAR produced by the build:
+
+```bash
+java -jar cameleer-license-minter/target/cameleer-license-minter-1.0-SNAPSHOT-cli.jar \
+    --private-key=/secure/keys/cameleer-license-priv.pem \
+    --tenant=acme-prod \
+    --label="Acme Production (Tier B)" \
+    --expires=2027-01-01 \
+    --grace-days=7 \
+    --max-environments=3 \
+    --max-apps=25 \
+    --max-agents=50 \
+    --max-users=20 \
+    --max-total-replicas=30 \
+    --output=/secure/out/acme-prod.lic \
+    --public-key=/secure/keys/cameleer-license-pub.b64 \
+    --verify
+```
+
+### Flag reference
+
+Source of truth: `cameleer-license-minter/src/main/java/com/cameleer/license/minter/cli/LicenseMinterCli.java:26`.
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--private-key=<path>` | yes | Path to a PKCS#8-encoded Ed25519 private key. Both PEM (`-----BEGIN PRIVATE KEY-----`) and raw base64 are accepted (`LicenseMinterCli.readEd25519PrivateKey`). |
+| `--tenant=<tenantId>` | yes | The exact `tenantId` the server will compare against `CAMELEER_SERVER_TENANT_ID`. Mismatch causes the validator to throw at install / revalidation. |
+| `--expires=<YYYY-MM-DD>` | yes | Expiration date interpreted as midnight UTC. The validator considers tokens expired once `now > exp + gracePeriodDays`. |
+| `--label=<text>` | no | Human-readable label, surfaced via `GET /api/v1/admin/license` and `/api/v1/admin/license/usage`. |
+| `--grace-days=<int>` | no | Number of days the license stays usable after `--expires`. Defaults to `0`. |
+| `--max-<limitkey>=<int>` | no, repeatable | Each `--max-foo-bar` flag becomes the limit key `max_foo_bar`. See the limits dictionary below. Unknown keys are accepted by the minter (the server side ignores keys it does not understand and falls through to defaults). |
+| `--output=<path>` | no | Write the token to a file. When omitted, the token is printed to stdout. On `--verify` failure the file is deleted. |
+| `--public-key=<path>` | no, required for `--verify` | Path to the matching base64 X.509 SPKI public key file (one line, no PEM markers). |
+| `--verify` | no | After minting, parse + signature-check the token using `--public-key` and `--tenant`. Exits non-zero if verification fails. |
+
+Exit codes: `0` on success, `1` on minting / IO failure, `2` on argument validation failure, `3` on `--verify` failure.
+
+## Token format
+
+A token is the concatenation of two **standard** base64 segments joined by a literal `.`:
+
+```
+base64(canonicalJson) + "." + base64(ed25519Signature)
+```
+
+- The canonical JSON payload is produced by `LicenseMinter.canonicalPayload(...)` with keys sorted lexicographically and `limits` rendered as a sorted object. This makes the byte sequence deterministic given a fixed `LicenseInfo`.
+- The signature is computed with `Signature.getInstance("Ed25519")` over the canonical payload bytes (not over the base64-encoded form).
+- Encoding is `Base64.getEncoder()` (RFC 4648 §4 — *not* base64url). The validator decodes with the matching `Base64.getDecoder()`.
+
+`LicenseValidator.validate(...)` (`cameleer-license-api/src/main/java/com/cameleer/license/LicenseValidator.java:42`) splits on the first `.`, decodes both halves, verifies the signature, then deserializes the payload.
+
+## LicenseInfo schema
+
+Source: `cameleer-license-api/src/main/java/com/cameleer/license/LicenseInfo.java`. Field-by-field:
+
+| Field | Type | Required | Semantics |
+|---|---|---|---|
+| `licenseId` | `UUID` | yes | Stable identifier for this token. The server's audit trail records install/replace transitions by license id; renewals must use a fresh UUID so audit history is non-ambiguous. |
+| `tenantId` | `String` | yes | Must equal the server's `CAMELEER_SERVER_TENANT_ID`. The validator throws `IllegalArgumentException` on mismatch. Blank values are rejected by the canonical record constructor. |
+| `label` | `String` | no | Free-form human label. Surfaced on the admin/usage endpoints and the operator UI. Has no enforcement semantics. |
+| `limits` | `Map<String,Integer>` | yes (may be empty) | License-specific overrides. Any key that appears here is unioned over `DefaultTierLimits.DEFAULTS` to form the effective caps in `ACTIVE` / `GRACE` states. Keys not present fall through to defaults. |
+| `issuedAt` | `Instant` (epoch seconds in JSON `iat`) | yes | Stamped by the minter; not currently consulted by the validator beyond informational logging. |
+| `expiresAt` | `Instant` (epoch seconds in JSON `exp`) | yes | The validator throws if `now > expiresAt + gracePeriodDays * 86400` at install or revalidation. |
+| `gracePeriodDays` | `int` | yes (>= 0) | Window after `expiresAt` during which the gate transitions to `GRACE` (license still grants its caps) before flipping to `EXPIRED`. Negative values are rejected at construction. |
+
+## Limits dictionary
+
+Canonical key set: `cameleer-license-api/src/main/java/com/cameleer/license/DefaultTierLimits.java`. Any key not listed here is silently ignored by the server's `LicenseGate.getEffectiveLimits()`.
+
+| CLI flag | Key | Default | What the server enforces |
+|---|---|---|---|
+| `--max-environments` | `max_environments` | 1 | `EnvironmentService.create(...)` consults `LicenseEnforcer.assertWithinCap("max_environments", currentCount, 1)`. |
+| `--max-apps` | `max_apps` | 3 | `AppService.createApp(...)` checks total app count across all envs. |
+| `--max-agents` | `max_agents` | 5 | `AgentRegistryService.register(...)` checks live agent count. |
+| `--max-users` | `max_users` | 3 | User creation paths (`UserAdminController`, `UiAuthController` self-signup, `OidcAuthController` first-login). |
+| `--max-outbound-connections` | `max_outbound_connections` | 1 | `OutboundConnectionServiceImpl.create(...)`. |
+| `--max-alert-rules` | `max_alert_rules` | 2 | `AlertRuleController.create(...)`. |
+| `--max-total-cpu-millis` | `max_total_cpu_millis` | 2000 | `DeploymentExecutor` PRE_FLIGHT compute cap (sum of `replicas * cpuLimit` over non-stopped deployments). |
+| `--max-total-memory-mb` | `max_total_memory_mb` | 2048 | `DeploymentExecutor` PRE_FLIGHT compute cap (sum of `replicas * memoryLimitMb`). |
+| `--max-total-replicas` | `max_total_replicas` | 5 | `DeploymentExecutor` PRE_FLIGHT compute cap (sum of `replicas`). |
+| `--max-execution-retention-days` | `max_execution_retention_days` | 1 | ClickHouse TTL cap for `executions`, `processor_executions`. Effective TTL = `min(cap, env.executionRetentionDays)`. |
+| `--max-log-retention-days` | `max_log_retention_days` | 1 | ClickHouse TTL cap for `logs`. |
+| `--max-metric-retention-days` | `max_metric_retention_days` | 1 | ClickHouse TTL cap for `agent_metrics`, `agent_events`. |
+| `--max-jar-retention-count` | `max_jar_retention_count` | 3 | `EnvironmentAdminController` PUT `/{envSlug}/jar-retention` rejects requests above this cap. Also bounds the daily `JarRetentionJob`. |
+
+## Generating an Ed25519 key pair
+
+The minter and validator both rely on the JCE `Ed25519` algorithm shipped with JDK 17+. No external crypto library is needed.
+
+```java
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
+import java.util.Base64;
+
+KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+
+// 32-byte public key, X.509 SubjectPublicKeyInfo wrapped — this is what the server expects.
+String publicKeyB64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+
+// PKCS#8 private key — the CLI's --private-key reader accepts this either as raw base64
+// or PEM-wrapped (`-----BEGIN PRIVATE KEY-----`).
+String privateKeyB64 = Base64.getEncoder().encodeToString(kp.getPrivate().getEncoded());
+```
+
+A one-liner using the JDK's `keytool` is **not** sufficient — `keytool` cannot produce raw Ed25519 PKCS#8 in a directly-usable shape for our reader. Generating via the API above (or `openssl genpkey -algorithm ed25519`) is the supported path.
+
+For OpenSSL:
+
+```bash
+openssl genpkey -algorithm ed25519 -out cameleer-license-priv.pem
+openssl pkey -in cameleer-license-priv.pem -pubout -outform DER \
+  | base64 -w0 > cameleer-license-pub.b64
+```
+
+The resulting `cameleer-license-pub.b64` is the value to put into `CAMELEER_SERVER_LICENSE_PUBLICKEY`.
+
+## Worked example
+
+End-to-end: generate a key pair, mint a license, install it on a running server, verify enforcement.
+
+```bash
+# 1. Vendor side — generate the keypair
+openssl genpkey -algorithm ed25519 -out /secrets/cameleer-priv.pem
+openssl pkey -in /secrets/cameleer-priv.pem -pubout -outform DER \
+  | base64 -w0 > /secrets/cameleer-pub.b64
+
+# 2. Vendor side — distribute the public key (commit to deployment config / Vault / k8s Secret)
+cat /secrets/cameleer-pub.b64
+#   MCowBQYDK2VwAyEAxxxxx...
+
+# 3. Vendor side — mint a license for a customer tenant
+mvn -pl cameleer-license-minter package -DskipTests
+java -jar cameleer-license-minter/target/cameleer-license-minter-1.0-SNAPSHOT-cli.jar \
+    --private-key=/secrets/cameleer-priv.pem \
+    --public-key=/secrets/cameleer-pub.b64 \
+    --tenant=acme-prod \
+    --label="Acme Production" \
+    --expires=2027-01-01 \
+    --grace-days=14 \
+    --max-environments=3 \
+    --max-apps=25 \
+    --max-agents=50 \
+    --max-users=20 \
+    --max-total-replicas=30 \
+    --max-total-cpu-millis=15000 \
+    --max-total-memory-mb=16384 \
+    --max-execution-retention-days=30 \
+    --max-log-retention-days=14 \
+    --max-metric-retention-days=14 \
+    --max-jar-retention-count=10 \
+    --output=/tmp/acme.lic \
+    --verify
+
+# 4. Customer side — server boots with public key + tenant id matching the mint
+export CAMELEER_SERVER_TENANT_ID=acme-prod
+export CAMELEER_SERVER_LICENSE_PUBLICKEY=$(cat /secrets/cameleer-pub.b64)
+
+# 5. Customer side — install via the admin API after boot
+curl -X POST https://server.example.com/api/v1/admin/license \
+     -H "Authorization: Bearer ${ADMIN_JWT}" \
+     -H "Content-Type: application/json" \
+     -d "{\"token\": \"$(cat /tmp/acme.lic)\"}"
+
+# 6. Customer side — verify it was accepted
+curl https://server.example.com/api/v1/admin/license \
+     -H "Authorization: Bearer ${ADMIN_JWT}"
+# {"state":"ACTIVE","invalidReason":null,"envelope":{...},"lastValidatedAt":"..."}
+
+curl https://server.example.com/api/v1/admin/license/usage \
+     -H "Authorization: Bearer ${ADMIN_JWT}"
+# Shows current/cap/source per limit key
+```
+
+For boot-time installation (preferred for SaaS-managed deployments), set `CAMELEER_SERVER_LICENSE_TOKEN` instead of POSTing — see `docs/license-enforcement.md`.
+
+## Security guidance
+
+- **The Ed25519 private key is the trust root.** Anyone who holds it can mint licenses for any tenant. Treat it like a code-signing key.
+- **Storage.** Production private keys belong in an HSM, KMS (e.g. AWS KMS / GCP KMS with non-exportable signing), or a sealed Vault transit backend. A sealed file on a laptop is acceptable for low-volume / pre-production minting only and should never be committed to git or shared via chat.
+- **Rotation.** Rotation is destructive: every customer running with the *old* public key will reject all new tokens signed with the *new* private key. The pragmatic procedure is:
+  1. Generate the new keypair.
+  2. Distribute the new public key (`CAMELEER_SERVER_LICENSE_PUBLICKEY`) to every tenant's server config.
+  3. Once tenants confirm they are running with the new public key, re-mint and re-issue every active license under the new key.
+  4. Decommission the old private key.
+  Practical revocation flows through expiry — keep license terms short enough (12 months or less) that planned rotations stay aligned with renewal cadence.
+- **Auditing.** The server records every install/replace/reject under `AuditCategory.LICENSE`. The minter itself does not write audit rows; if you need a vendor-side audit trail of mint operations, wrap `LicenseMinter.mint(...)` in your own ticketing pipeline.
+- **Never commit private keys.** `.gitignore` does not block them by name — use a `secrets/` directory excluded by your repository's policy, or store them entirely outside the working tree.
+
+## Compatibility / runtime separation
+
+The minter is intentionally absent from `cameleer-server-app`'s production classpath. To verify after a build:
+
+```bash
+mvn -pl cameleer-server-app dependency:tree | grep license-minter
+# expected: empty output (or, in development branches, a single line scoped 'test')
+```
+
+`cameleer-license-minter/pom.xml` depends on `cameleer-license-api` for the pure license contract types (`LicenseInfo`, `LicenseValidator`) used by mint + `--verify`. It deliberately does **not** depend on `cameleer-server-core`, so consumers of the minter (e.g. `cameleer-saas`) do not inherit server-runtime types onto their classpath. The server app intentionally does not depend on the minter — vendors mint outside the customer-deployed runtime, and a compromised customer cannot leverage server code to forge tokens.

cameleer-license-minter/pom.xml

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.cameleer</groupId>
+        <artifactId>cameleer-server-parent</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>cameleer-license-minter</artifactId>
+    <name>Cameleer License Minter</name>
+    <description>Vendor-only Ed25519 license signing library + CLI</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.cameleer</groupId>
+            <artifactId>cameleer-license-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <executions>
+                    <!-- Disable the default repackage so the main artifact stays as a plain library
+                         JAR consumable as a Maven test-scope dependency by cameleer-server-app. -->
+                    <execution>
+                        <id>repackage</id>
+                        <phase>none</phase>
+                    </execution>
+                    <execution>
+                        <id>repackage-cli</id>
+                        <goals>
+                            <goal>repackage</goal>
+                        </goals>
+                        <configuration>
+                            <classifier>cli</classifier>
+                            <mainClass>io.cameleer.license.minter.cli.LicenseMinterCli</mainClass>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

cameleer-license-minter/src/main/java/io/cameleer/license/minter/LicenseMinter.java

@@ -0,0 +1,52 @@
+package io.cameleer.license.minter;
+
+import io.cameleer.license.LicenseInfo;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+import java.security.PrivateKey;
+import java.security.Signature;
+import java.util.Base64;
+import java.util.TreeMap;
+
+public final class LicenseMinter {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper()
+            .configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true);
+
+    private LicenseMinter() {}
+
+    public static String mint(LicenseInfo info, PrivateKey ed25519PrivateKey) {
+        byte[] payload = canonicalPayload(info);
+        try {
+            Signature signer = Signature.getInstance("Ed25519");
+            signer.initSign(ed25519PrivateKey);
+            signer.update(payload);
+            byte[] sig = signer.sign();
+            return Base64.getEncoder().encodeToString(payload) + "." + Base64.getEncoder().encodeToString(sig);
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to sign license", e);
+        }
+    }
+
+    static byte[] canonicalPayload(LicenseInfo info) {
+        ObjectNode root = MAPPER.createObjectNode();
+        root.put("exp", info.expiresAt().getEpochSecond());
+        root.put("gracePeriodDays", info.gracePeriodDays());
+        root.put("iat", info.issuedAt().getEpochSecond());
+        if (info.label() != null) {
+            root.put("label", info.label());
+        }
+        root.put("licenseId", info.licenseId().toString());
+        ObjectNode limits = MAPPER.createObjectNode();
+        new TreeMap<>(info.limits()).forEach(limits::put);
+        root.set("limits", limits);
+        root.put("tenantId", info.tenantId());
+        try {
+            return MAPPER.writeValueAsBytes(root);
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to serialize license payload", e);
+        }
+    }
+}

cameleer-license-minter/src/main/java/io/cameleer/license/minter/cli/LicenseMinterCli.java

@@ -0,0 +1,136 @@
+package io.cameleer.license.minter.cli;
+
+import io.cameleer.license.minter.LicenseMinter;
+import io.cameleer.license.LicenseInfo;
+
+import java.io.PrintStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyFactory;
+import java.security.PrivateKey;
+import java.security.spec.PKCS8EncodedKeySpec;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.util.Base64;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.UUID;
+
+public final class LicenseMinterCli {
+
+    private static final Set<String> KNOWN_FLAGS = Set.of(
+            "--private-key", "--public-key", "--tenant", "--label",
+            "--expires", "--grace-days", "--output", "--verify"
+    );
+
+    public static void main(String[] args) {
+        System.exit(run(args));
+    }
+
+    public static int run(String[] args) {
+        return run(args, System.out, System.err);
+    }
+
+    public static int run(String[] args, PrintStream out, PrintStream err) {
+        Map<String, String> flags = new LinkedHashMap<>();
+        Set<String> bool = new HashSet<>();
+        Map<String, Integer> limits = new TreeMap<>();
+        for (String arg : args) {
+            if (!arg.startsWith("--")) {
+                err.println("unexpected positional argument: " + arg);
+                return 2;
+            }
+            int eq = arg.indexOf('=');
+            String key = eq < 0 ? arg : arg.substring(0, eq);
+            String value = eq < 0 ? null : arg.substring(eq + 1);
+            if (key.startsWith("--max-")) {
+                String limitKey = "max_" + key.substring("--max-".length()).replace('-', '_');
+                if (value == null) {
+                    err.println("missing value for " + key);
+                    return 2;
+                }
+                limits.put(limitKey, Integer.parseInt(value));
+                continue;
+            }
+            if (!KNOWN_FLAGS.contains(key)) {
+                err.println("unknown flag: " + key);
+                return 2;
+            }
+            if (value == null) {
+                bool.add(key);
+            } else {
+                flags.put(key, value);
+            }
+        }
+
+        String privPath = flags.get("--private-key");
+        String tenant = flags.get("--tenant");
+        String expiresIso = flags.get("--expires");
+        if (privPath == null || tenant == null || expiresIso == null) {
+            err.println("required: --private-key --tenant --expires");
+            return 2;
+        }
+
+        try {
+            PrivateKey privateKey = readEd25519PrivateKey(Path.of(privPath));
+            int graceDays = Integer.parseInt(flags.getOrDefault("--grace-days", "0"));
+            Instant exp = LocalDate.parse(expiresIso).atStartOfDay(ZoneOffset.UTC).toInstant();
+            LicenseInfo info = new LicenseInfo(
+                    UUID.randomUUID(),
+                    tenant,
+                    flags.get("--label"),
+                    Collections.unmodifiableMap(limits),
+                    Instant.now(),
+                    exp,
+                    graceDays
+            );
+            String token = LicenseMinter.mint(info, privateKey);
+
+            String outPath = flags.get("--output");
+            if (outPath != null) {
+                Files.writeString(Path.of(outPath), token);
+                out.println("wrote " + outPath);
+            } else {
+                out.println(token);
+            }
+            if (bool.contains("--verify")) {
+                String pubPath = flags.get("--public-key");
+                if (pubPath == null) {
+                    err.println("--verify requires --public-key");
+                    if (outPath != null) Files.deleteIfExists(Path.of(outPath));
+                    return 2;
+                }
+                try {
+                    String pubB64 = Files.readString(Path.of(pubPath)).trim();
+                    new io.cameleer.license.LicenseValidator(pubB64, tenant).validate(token);
+                    out.println("verified ok");
+                } catch (Exception ve) {
+                    err.println("VERIFY FAILED: " + ve.getMessage());
+                    if (outPath != null) Files.deleteIfExists(Path.of(outPath));
+                    return 3;
+                }
+            }
+            return 0;
+        } catch (Exception e) {
+            err.println("ERROR: " + e.getMessage());
+            return 1;
+        }
+    }
+
+    private static PrivateKey readEd25519PrivateKey(Path path) throws Exception {
+        String s = Files.readString(path).trim();
+        if (s.startsWith("-----BEGIN")) {
+            s = s.replaceAll("-----BEGIN [A-Z ]+-----", "")
+                 .replaceAll("-----END [A-Z ]+-----", "")
+                 .replaceAll("\\s", "");
+        }
+        byte[] der = Base64.getDecoder().decode(s);
+        return KeyFactory.getInstance("Ed25519")
+                .generatePrivate(new PKCS8EncodedKeySpec(der));
+    }
+}

cameleer-license-minter/src/test/java/io/cameleer/license/minter/LicenseMinterTest.java

@@ -0,0 +1,53 @@
+package io.cameleer.license.minter;
+
+import io.cameleer.license.LicenseInfo;
+import io.cameleer.license.LicenseValidator;
+import org.junit.jupiter.api.Test;
+
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
+import java.time.Instant;
+import java.util.Base64;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class LicenseMinterTest {
+
+    @Test
+    void roundTrip_validatorAcceptsMintedToken() throws Exception {
+        KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        String publicB64 = Base64.getEncoder().encodeToString(kp.getPublic().getEncoded());
+
+        LicenseInfo info = new LicenseInfo(
+                UUID.randomUUID(), "acme", "ACME prod",
+                Map.of("max_apps", 50, "max_agents", 100),
+                Instant.now(), Instant.now().plusSeconds(86400), 7);
+
+        String token = LicenseMinter.mint(info, kp.getPrivate());
+
+        LicenseInfo parsed = new LicenseValidator(publicB64, "acme").validate(token);
+        assertThat(parsed.licenseId()).isEqualTo(info.licenseId());
+        assertThat(parsed.tenantId()).isEqualTo("acme");
+        assertThat(parsed.limits().get("max_apps")).isEqualTo(50);
+        assertThat(parsed.gracePeriodDays()).isEqualTo(7);
+    }
+
+    @Test
+    void canonicalJson_isStableAcrossRuns() throws Exception {
+        KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        UUID id = UUID.randomUUID();
+        Instant now = Instant.parse("2026-04-25T10:00:00Z");
+        Instant exp = Instant.parse("2027-04-25T10:00:00Z");
+        LinkedHashMap<String, Integer> limits = new LinkedHashMap<>();
+        limits.put("max_apps", 5);
+        limits.put("max_agents", 10);
+        LicenseInfo info = new LicenseInfo(id, "acme", "label", limits, now, exp, 0);
+
+        String t1 = LicenseMinter.mint(info, kp.getPrivate());
+        String t2 = LicenseMinter.mint(info, kp.getPrivate());
+        assertThat(t1).isEqualTo(t2);
+    }
+}

cameleer-license-minter/src/test/java/io/cameleer/license/minter/cli/LicenseMinterCliTest.java

@@ -0,0 +1,112 @@
+package io.cameleer.license.minter.cli;
+
+import io.cameleer.license.LicenseValidator;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
+import java.util.Base64;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class LicenseMinterCliTest {
+
+    @TempDir Path tmp;
+
+    @Test
+    void mints_validToken_validatorAccepts() throws Exception {
+        KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        Path priv = tmp.resolve("priv.b64");
+        Path pub = tmp.resolve("pub.b64");
+        Files.writeString(priv, Base64.getEncoder().encodeToString(kp.getPrivate().getEncoded()));
+        Files.writeString(pub, Base64.getEncoder().encodeToString(kp.getPublic().getEncoded()));
+        Path out = tmp.resolve("license.tok");
+
+        int code = LicenseMinterCli.run(new String[]{
+                "--private-key=" + priv,
+                "--tenant=acme",
+                "--label=ACME",
+                "--expires=2099-12-31",
+                "--grace-days=30",
+                "--max-apps=50",
+                "--output=" + out
+        });
+
+        assertThat(code).isEqualTo(0);
+        String token = Files.readString(out).trim();
+        var info = new LicenseValidator(Files.readString(pub).trim(), "acme").validate(token);
+        assertThat(info.tenantId()).isEqualTo("acme");
+        assertThat(info.limits().get("max_apps")).isEqualTo(50);
+        assertThat(info.gracePeriodDays()).isEqualTo(30);
+    }
+
+    @Test
+    void unknownFlag_failsFast() {
+        int code = LicenseMinterCli.run(new String[]{"--frobnicate=yes"});
+        assertThat(code).isNotZero();
+    }
+
+    @Test
+    void verify_happyPath_succeeds() throws Exception {
+        KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        Path priv = tmp.resolve("priv.b64");
+        Path pub = tmp.resolve("pub.b64");
+        Files.writeString(priv, Base64.getEncoder().encodeToString(kp.getPrivate().getEncoded()));
+        Files.writeString(pub, Base64.getEncoder().encodeToString(kp.getPublic().getEncoded()));
+        Path out = tmp.resolve("license.tok");
+
+        int code = LicenseMinterCli.run(new String[]{
+                "--private-key=" + priv,
+                "--public-key=" + pub,
+                "--tenant=acme",
+                "--expires=2099-12-31",
+                "--output=" + out,
+                "--verify"
+        });
+
+        assertThat(code).isEqualTo(0);
+        assertThat(out).exists();
+    }
+
+    @Test
+    void verify_wrongPublicKey_deletesOutputAndExitsNonZero() throws Exception {
+        KeyPair signing = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        KeyPair other = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        Path priv = tmp.resolve("priv.b64");
+        Path pub = tmp.resolve("pub.b64");
+        Files.writeString(priv, Base64.getEncoder().encodeToString(signing.getPrivate().getEncoded()));
+        Files.writeString(pub, Base64.getEncoder().encodeToString(other.getPublic().getEncoded()));
+        Path out = tmp.resolve("license.tok");
+
+        int code = LicenseMinterCli.run(new String[]{
+                "--private-key=" + priv,
+                "--public-key=" + pub,
+                "--tenant=acme",
+                "--expires=2099-12-31",
+                "--output=" + out,
+                "--verify"
+        });
+
+        assertThat(code).isNotZero();
+        assertThat(out).doesNotExist();
+    }
+
+    @Test
+    void verify_withoutPublicKey_fails() throws Exception {
+        KeyPair kp = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+        Path priv = tmp.resolve("priv.b64");
+        Files.writeString(priv, Base64.getEncoder().encodeToString(kp.getPrivate().getEncoded()));
+
+        int code = LicenseMinterCli.run(new String[]{
+                "--private-key=" + priv,
+                "--tenant=acme",
+                "--expires=2099-12-31",
+                "--verify"
+        });
+
+        assertThat(code).isNotZero();
+    }
+}

cameleer-server-app/pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
-        <groupId>com.cameleer</groupId>
+        <groupId>io.cameleer</groupId>
         <artifactId>cameleer-server-parent</artifactId>
         <version>1.0-SNAPSHOT</version>
     </parent>
@@ -16,9 +16,15 @@
 
     <dependencies>
         <dependency>
-            <groupId>com.cameleer</groupId>
+            <groupId>io.cameleer</groupId>
             <artifactId>cameleer-server-core</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.cameleer</groupId>
+            <artifactId>cameleer-license-minter</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>
@@ -189,8 +195,8 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
                 <configuration>
-                    <forkCount>1</forkCount>
+                    <forkCount>1C</forkCount>
-                    <reuseForks>false</reuseForks>
+                    <reuseForks>true</reuseForks>
                 </configuration>
             </plugin>
             <plugin>

cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/eval/ConditionEvaluator.java

@@ -1,12 +0,0 @@
-package com.cameleer.server.app.alerting.eval;
-
-import com.cameleer.server.core.alerting.AlertCondition;
-import com.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ConditionKind;
-
-public interface ConditionEvaluator<C extends AlertCondition> {
-
-    ConditionKind kind();
-
-    EvalResult evaluate(C condition, AlertRule rule, EvalContext ctx);
-}

cameleer-server-app/src/main/java/com/cameleer/server/app/config/LicenseBeanConfig.java

@@ -1,68 +0,0 @@
-package com.cameleer.server.app.config;
-
-import com.cameleer.server.core.license.LicenseGate;
-import com.cameleer.server.core.license.LicenseInfo;
-import com.cameleer.server.core.license.LicenseValidator;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-
-import java.nio.file.Files;
-import java.nio.file.Path;
-
-@Configuration
-public class LicenseBeanConfig {
-
-    private static final Logger log = LoggerFactory.getLogger(LicenseBeanConfig.class);
-
-    @Value("${cameleer.server.license.token:}")
-    private String licenseToken;
-
-    @Value("${cameleer.server.license.file:}")
-    private String licenseFile;
-
-    @Value("${cameleer.server.license.publickey:}")
-    private String licensePublicKey;
-
-    @Bean
-    public LicenseGate licenseGate() {
-        LicenseGate gate = new LicenseGate();
-
-        String token = resolveLicenseToken();
-        if (token == null || token.isBlank()) {
-            log.info("No license configured — running in open mode (all features enabled)");
-            return gate;
-        }
-
-        if (licensePublicKey == null || licensePublicKey.isBlank()) {
-            log.warn("License token provided but no public key configured (CAMELEER_SERVER_LICENSE_PUBLICKEY). Running in open mode.");
-            return gate;
-        }
-
-        try {
-            LicenseValidator validator = new LicenseValidator(licensePublicKey);
-            LicenseInfo info = validator.validate(token);
-            gate.load(info);
-        } catch (Exception e) {
-            log.error("Failed to validate license: {}. Running in open mode.", e.getMessage());
-        }
-
-        return gate;
-    }
-
-    private String resolveLicenseToken() {
-        if (licenseToken != null && !licenseToken.isBlank()) {
-            return licenseToken;
-        }
-        if (licenseFile != null && !licenseFile.isBlank()) {
-            try {
-                return Files.readString(Path.of(licenseFile)).trim();
-            } catch (Exception e) {
-                log.warn("Failed to read license file {}: {}", licenseFile, e.getMessage());
-            }
-        }
-        return null;
-    }
-}

cameleer-server-app/src/main/java/com/cameleer/server/app/controller/LicenseAdminController.java

@@ -1,53 +0,0 @@
-package com.cameleer.server.app.controller;
-
-import com.cameleer.server.core.license.LicenseGate;
-import com.cameleer.server.core.license.LicenseInfo;
-import com.cameleer.server.core.license.LicenseValidator;
-import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.http.ResponseEntity;
-import org.springframework.security.access.prepost.PreAuthorize;
-import org.springframework.web.bind.annotation.*;
-
-import java.util.Map;
-
-@RestController
-@RequestMapping("/api/v1/admin/license")
-@PreAuthorize("hasRole('ADMIN')")
-@Tag(name = "License Admin", description = "License management")
-public class LicenseAdminController {
-
-    private final LicenseGate licenseGate;
-    private final String licensePublicKey;
-
-    public LicenseAdminController(LicenseGate licenseGate,
-                                   @Value("${cameleer.server.license.publickey:}") String licensePublicKey) {
-        this.licenseGate = licenseGate;
-        this.licensePublicKey = licensePublicKey;
-    }
-
-    @GetMapping
-    @Operation(summary = "Get current license info")
-    public ResponseEntity<LicenseInfo> getCurrent() {
-        return ResponseEntity.ok(licenseGate.getCurrent());
-    }
-
-    record UpdateLicenseRequest(String token) {}
-
-    @PostMapping
-    @Operation(summary = "Update license token at runtime")
-    public ResponseEntity<?> update(@RequestBody UpdateLicenseRequest request) {
-        if (licensePublicKey == null || licensePublicKey.isBlank()) {
-            return ResponseEntity.badRequest().body(Map.of("error", "No license public key configured"));
-        }
-        try {
-            LicenseValidator validator = new LicenseValidator(licensePublicKey);
-            LicenseInfo info = validator.validate(request.token());
-            licenseGate.load(info);
-            return ResponseEntity.ok(info);
-        } catch (Exception e) {
-            return ResponseEntity.badRequest().body(Map.of("error", e.getMessage()));
-        }
-    }
-}

cameleer-server-app/src/main/java/com/cameleer/server/app/runtime/DeploymentExecutor.java

@@ -1,408 +0,0 @@
-package com.cameleer.server.app.runtime;
-
-import com.cameleer.server.app.metrics.ServerMetrics;
-import com.cameleer.server.app.storage.PostgresDeploymentRepository;
-import com.cameleer.server.core.runtime.*;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.scheduling.annotation.Async;
-import org.springframework.stereotype.Service;
-
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.*;
-
-@Service
-public class DeploymentExecutor {
-
-    private static final Logger log = LoggerFactory.getLogger(DeploymentExecutor.class);
-
-    private final RuntimeOrchestrator orchestrator;
-    private final DeploymentService deploymentService;
-    private final AppService appService;
-    private final EnvironmentService envService;
-    private final DeploymentRepository deploymentRepository;
-    private final PostgresDeploymentRepository pgDeployRepo;
-
-    @Autowired(required = false)
-    private DockerNetworkManager networkManager;
-
-    @Value("${cameleer.server.runtime.baseimage:gitea.siegeln.net/cameleer/cameleer-runtime-base:latest}")
-    private String baseImage;
-
-    @Value("${cameleer.server.runtime.dockernetwork:cameleer}")
-    private String dockerNetwork;
-
-    @Value("${cameleer.server.runtime.container.memorylimit:512m}")
-    private String globalMemoryLimit;
-
-    @Value("${cameleer.server.runtime.container.cpushares:512}")
-    private int globalCpuShares;
-
-    @Value("${cameleer.server.runtime.healthchecktimeout:60}")
-    private int healthCheckTimeout;
-
-    @Value("${cameleer.server.runtime.agenthealthport:9464}")
-    private int agentHealthPort;
-
-    @Value("${cameleer.server.security.bootstraptoken:}")
-    private String bootstrapToken;
-
-    @Value("${cameleer.server.runtime.routingmode:path}")
-    private String globalRoutingMode;
-
-    @Value("${cameleer.server.runtime.routingdomain:localhost}")
-    private String globalRoutingDomain;
-
-    @Value("${cameleer.server.runtime.serverurl:}")
-    private String globalServerUrl;
-
-    @Value("${cameleer.server.runtime.jardockervolume:}")
-    private String jarDockerVolume;
-
-    @Value("${cameleer.server.runtime.jarstoragepath:/data/jars}")
-    private String jarStoragePath;
-
-    @Value("${cameleer.server.tenant.id:default}")
-    private String tenantId;
-
-    @Autowired
-    private ServerMetrics serverMetrics;
-
-    public DeploymentExecutor(RuntimeOrchestrator orchestrator,
-                              DeploymentService deploymentService,
-                              AppService appService,
-                              EnvironmentService envService,
-                              DeploymentRepository deploymentRepository) {
-        this.orchestrator = orchestrator;
-        this.deploymentService = deploymentService;
-        this.appService = appService;
-        this.envService = envService;
-        this.deploymentRepository = deploymentRepository;
-        this.pgDeployRepo = (PostgresDeploymentRepository) deploymentRepository;
-    }
-
-    @Async("deploymentTaskExecutor")
-    public void executeAsync(Deployment deployment) {
-        long deployStart = System.currentTimeMillis();
-        try {
-            App app = appService.getById(deployment.appId());
-            Environment env = envService.getById(deployment.environmentId());
-            String jarPath = appService.resolveJarPath(deployment.appVersionId());
-
-            var globalDefaults = new ConfigMerger.GlobalRuntimeDefaults(
-                    parseMemoryLimitMb(globalMemoryLimit),
-                    globalCpuShares,
-                    globalRoutingMode,
-                    globalRoutingDomain,
-                    globalServerUrl.isBlank() ? "http://cameleer-server:8081" : globalServerUrl
-            );
-            ResolvedContainerConfig config = ConfigMerger.resolve(
-                    globalDefaults, env.defaultContainerConfig(), app.containerConfig());
-
-            pgDeployRepo.updateDeploymentStrategy(deployment.id(), config.deploymentStrategy());
-            pgDeployRepo.updateResolvedConfig(deployment.id(), resolvedConfigToMap(config));
-
-            // === PRE-FLIGHT ===
-            updateStage(deployment.id(), DeployStage.PRE_FLIGHT);
-            preFlightChecks(jarPath, config);
-
-            // Resolve runtime type
-            String resolvedRuntimeType = config.runtimeType();
-            String mainClass = null;
-            if ("auto".equalsIgnoreCase(resolvedRuntimeType)) {
-                AppVersion appVersion = appService.getVersion(deployment.appVersionId());
-                if (appVersion.detectedRuntimeType() == null) {
-                    throw new IllegalStateException(
-                            "Could not detect runtime type for JAR '" + appVersion.jarFilename() +
-                            "'. Set runtimeType explicitly in app configuration.");
-                }
-                resolvedRuntimeType = appVersion.detectedRuntimeType();
-                mainClass = appVersion.detectedMainClass();
-            } else if ("plain-java".equals(resolvedRuntimeType)) {
-                AppVersion appVersion = appService.getVersion(deployment.appVersionId());
-                mainClass = appVersion.detectedMainClass();
-                if (mainClass == null) {
-                    throw new IllegalStateException(
-                            "Runtime type 'plain-java' requires a Main-Class in the JAR manifest, " +
-                            "but none was detected for '" + appVersion.jarFilename() + "'.");
-                }
-            }
-
-            // === PULL IMAGE ===
-            updateStage(deployment.id(), DeployStage.PULL_IMAGE);
-            orchestrator.pullImage(baseImage);
-
-            // === CREATE NETWORKS ===
-            updateStage(deployment.id(), DeployStage.CREATE_NETWORK);
-            // Primary network: use configured CAMELEER_DOCKER_NETWORK (tenant-isolated in SaaS mode)
-            String primaryNetwork = dockerNetwork;
-            String envNet = null;
-            List<String> additionalNets = new ArrayList<>();
-            if (networkManager != null) {
-                networkManager.ensureNetwork(primaryNetwork);
-                // Traefik network for routing (apps need to be reachable by Traefik)
-                networkManager.ensureNetwork(DockerNetworkManager.TRAEFIK_NETWORK);
-                additionalNets.add(DockerNetworkManager.TRAEFIK_NETWORK);
-                // Per-environment network scoped to tenant to prevent cross-tenant collisions
-                envNet = DockerNetworkManager.envNetworkName(tenantId, env.slug());
-                networkManager.ensureNetwork(envNet);
-                additionalNets.add(envNet);
-            }
-
-            // User-configured extra networks (e.g., monitoring)
-            if (networkManager != null && config.extraNetworks() != null) {
-                for (String net : config.extraNetworks()) {
-                    if (!net.isBlank() && !additionalNets.contains(net)) {
-                        networkManager.ensureNetwork(net);
-                        additionalNets.add(net);
-                    }
-                }
-            }
-
-            // === START REPLICAS ===
-            updateStage(deployment.id(), DeployStage.START_REPLICAS);
-
-            Map<String, String> baseEnvVars = buildEnvVars(app, env, config);
-            Map<String, String> prometheusLabels = PrometheusLabelBuilder.build(resolvedRuntimeType);
-
-            List<Map<String, Object>> replicaStates = new ArrayList<>();
-            List<String> newContainerIds = new ArrayList<>();
-
-            for (int i = 0; i < config.replicas(); i++) {
-                String instanceId = env.slug() + "-" + app.slug() + "-" + i;
-                String containerName = tenantId + "-" + instanceId;
-
-                // Per-replica labels (include replica index and instance-id)
-                Map<String, String> labels = TraefikLabelBuilder.build(app.slug(), env.slug(), tenantId, config, i);
-                labels.putAll(prometheusLabels);
-
-                // Per-replica env vars (set agent instance ID to match container log identity)
-                Map<String, String> replicaEnvVars = new LinkedHashMap<>(baseEnvVars);
-                replicaEnvVars.put("CAMELEER_AGENT_INSTANCEID", instanceId);
-
-                String volumeName = jarDockerVolume != null && !jarDockerVolume.isBlank() ? jarDockerVolume : null;
-                ContainerRequest request = new ContainerRequest(
-                        containerName, baseImage, jarPath,
-                        volumeName, jarStoragePath,
-                        primaryNetwork,
-                        additionalNets,
-                        replicaEnvVars, labels,
-                        config.memoryLimitBytes(), config.memoryReserveBytes(),
-                        config.dockerCpuShares(), config.dockerCpuQuota(),
-                        config.exposedPorts(), agentHealthPort,
-                        "on-failure", 3,
-                        resolvedRuntimeType, config.customArgs(), mainClass
-                );
-
-                String containerId = orchestrator.startContainer(request);
-                newContainerIds.add(containerId);
-
-                // Connect to additional networks after container is started
-                for (String net : additionalNets) {
-                    if (networkManager != null) {
-                        networkManager.connectContainer(containerId, net);
-                    }
-                }
-
-                orchestrator.startLogCapture(containerId, instanceId, app.slug(), env.slug(), tenantId);
-
-                replicaStates.add(Map.of(
-                        "index", i,
-                        "containerId", containerId,
-                        "containerName", containerName,
-                        "status", "STARTING"
-                ));
-            }
-
-            pgDeployRepo.updateReplicaStates(deployment.id(), replicaStates);
-
-            // === HEALTH CHECK ===
-            updateStage(deployment.id(), DeployStage.HEALTH_CHECK);
-            int healthyCount = waitForAnyHealthy(newContainerIds, healthCheckTimeout);
-
-            if (healthyCount == 0) {
-                for (String cid : newContainerIds) {
-                    try { orchestrator.stopContainer(cid); orchestrator.removeContainer(cid); }
-                    catch (Exception e) { log.warn("Cleanup failed for {}: {}", cid, e.getMessage()); }
-                }
-                pgDeployRepo.updateDeployStage(deployment.id(), null);
-                deploymentService.markFailed(deployment.id(), "No replicas passed health check within " + healthCheckTimeout + "s");
-                serverMetrics.recordDeploymentOutcome("FAILED");
-                serverMetrics.recordDeploymentDuration(deployStart);
-                return;
-            }
-
-            replicaStates = updateReplicaHealth(replicaStates, newContainerIds);
-            pgDeployRepo.updateReplicaStates(deployment.id(), replicaStates);
-
-            // === SWAP TRAFFIC ===
-            updateStage(deployment.id(), DeployStage.SWAP_TRAFFIC);
-
-            Optional<Deployment> existing = deploymentRepository.findActiveByAppIdAndEnvironmentId(
-                    deployment.appId(), deployment.environmentId());
-            if (existing.isPresent() && !existing.get().id().equals(deployment.id())) {
-                stopDeploymentContainers(existing.get());
-                deploymentService.markStopped(existing.get().id());
-                log.info("Stopped previous deployment {} for replacement", existing.get().id());
-            }
-
-            // === COMPLETE ===
-            updateStage(deployment.id(), DeployStage.COMPLETE);
-
-            String primaryContainerId = newContainerIds.get(0);
-            DeploymentStatus finalStatus = healthyCount == config.replicas()
-                    ? DeploymentStatus.RUNNING : DeploymentStatus.DEGRADED;
-            deploymentService.markRunning(deployment.id(), primaryContainerId);
-            if (finalStatus == DeploymentStatus.DEGRADED) {
-                deploymentRepository.updateStatus(deployment.id(), DeploymentStatus.DEGRADED,
-                        primaryContainerId, null);
-            }
-
-            pgDeployRepo.updateDeployStage(deployment.id(), null);
-            serverMetrics.recordDeploymentOutcome(finalStatus.name());
-            serverMetrics.recordDeploymentDuration(deployStart);
-            log.info("Deployment {} is {} ({}/{} replicas healthy)",
-                    deployment.id(), finalStatus, healthyCount, config.replicas());
-
-        } catch (Exception e) {
-            log.error("Deployment {} FAILED: {}", deployment.id(), e.getMessage(), e);
-            pgDeployRepo.updateDeployStage(deployment.id(), null);
-            deploymentService.markFailed(deployment.id(), e.getMessage());
-            serverMetrics.recordDeploymentOutcome("FAILED");
-            serverMetrics.recordDeploymentDuration(deployStart);
-        }
-    }
-
-    public void stopDeployment(Deployment deployment) {
-        pgDeployRepo.updateTargetState(deployment.id(), "STOPPED");
-        deploymentRepository.updateStatus(deployment.id(), DeploymentStatus.STOPPING,
-                deployment.containerId(), null);
-
-        stopDeploymentContainers(deployment);
-        deploymentService.markStopped(deployment.id());
-    }
-
-    private void stopDeploymentContainers(Deployment deployment) {
-        List<Map<String, Object>> replicas = deployment.replicaStates() != null
-                ? deployment.replicaStates() : List.of();
-        for (Map<String, Object> replica : replicas) {
-            String cid = (String) replica.get("containerId");
-            if (cid != null) {
-                try {
-                    orchestrator.stopContainer(cid);
-                    orchestrator.removeContainer(cid);
-                } catch (Exception e) {
-                    log.warn("Failed to stop replica container {}: {}", cid, e.getMessage());
-                }
-            }
-        }
-        if (deployment.containerId() != null && replicas.isEmpty()) {
-            try {
-                orchestrator.stopContainer(deployment.containerId());
-                orchestrator.removeContainer(deployment.containerId());
-            } catch (Exception e) {
-                log.warn("Failed to stop container {}: {}", deployment.containerId(), e.getMessage());
-            }
-        }
-    }
-
-    private void preFlightChecks(String jarPath, ResolvedContainerConfig config) {
-        if (!Files.exists(Path.of(jarPath))) {
-            throw new IllegalStateException("JAR file not found: " + jarPath);
-        }
-        if (config.memoryLimitMb() <= 0) {
-            throw new IllegalStateException("Memory limit must be positive, got: " + config.memoryLimitMb());
-        }
-        if (config.appPort() <= 0 || config.appPort() > 65535) {
-            throw new IllegalStateException("Invalid app port: " + config.appPort());
-        }
-        if (config.replicas() < 1) {
-            throw new IllegalStateException("Replicas must be >= 1, got: " + config.replicas());
-        }
-    }
-
-    private Map<String, String> buildEnvVars(App app, Environment env, ResolvedContainerConfig config) {
-        Map<String, String> envVars = new LinkedHashMap<>();
-        envVars.put("CAMELEER_AGENT_EXPORT_TYPE", "HTTP");
-        envVars.put("CAMELEER_AGENT_APPLICATION", app.slug());
-        envVars.put("CAMELEER_AGENT_ENVIRONMENT", env.slug());
-        envVars.put("CAMELEER_AGENT_EXPORT_ENDPOINT", config.serverUrl());
-        envVars.put("CAMELEER_AGENT_ROUTECONTROL_ENABLED", String.valueOf(config.routeControlEnabled()));
-        envVars.put("CAMELEER_AGENT_REPLAY_ENABLED", String.valueOf(config.replayEnabled()));
-        envVars.put("CAMELEER_AGENT_HEALTH_ENABLED", "true");
-        envVars.put("CAMELEER_AGENT_HEALTH_PORT", String.valueOf(agentHealthPort));
-        if (bootstrapToken != null && !bootstrapToken.isBlank()) {
-            envVars.put("CAMELEER_AGENT_AUTH_TOKEN", bootstrapToken);
-        }
-        envVars.putAll(config.customEnvVars());
-        return envVars;
-    }
-
-    private int waitForAnyHealthy(List<String> containerIds, int timeoutSeconds) {
-        long deadline = System.currentTimeMillis() + (timeoutSeconds * 1000L);
-        int lastHealthy = 0;
-        while (System.currentTimeMillis() < deadline) {
-            int healthy = 0;
-            for (String cid : containerIds) {
-                ContainerStatus status = orchestrator.getContainerStatus(cid);
-                if ("healthy".equals(status.state())) healthy++;
-            }
-            lastHealthy = healthy;
-            if (healthy == containerIds.size()) return healthy;
-            try { Thread.sleep(2000); } catch (InterruptedException e) {
-                Thread.currentThread().interrupt();
-                return lastHealthy;
-            }
-        }
-        return lastHealthy;
-    }
-
-    private List<Map<String, Object>> updateReplicaHealth(List<Map<String, Object>> replicas,
-                                                           List<String> containerIds) {
-        List<Map<String, Object>> updated = new ArrayList<>();
-        for (Map<String, Object> replica : replicas) {
-            String cid = (String) replica.get("containerId");
-            ContainerStatus status = orchestrator.getContainerStatus(cid);
-            Map<String, Object> copy = new HashMap<>(replica);
-            copy.put("status", status.running() ? "RUNNING" : "DEAD");
-            updated.add(copy);
-        }
-        return updated;
-    }
-
-    private void updateStage(UUID deploymentId, DeployStage stage) {
-        pgDeployRepo.updateDeployStage(deploymentId, stage.name());
-    }
-
-    private int parseMemoryLimitMb(String limit) {
-        limit = limit.trim().toLowerCase();
-        if (limit.endsWith("g")) return (int) (Double.parseDouble(limit.replace("g", "")) * 1024);
-        if (limit.endsWith("m")) return (int) Double.parseDouble(limit.replace("m", ""));
-        return Integer.parseInt(limit);
-    }
-
-    private Map<String, Object> resolvedConfigToMap(ResolvedContainerConfig config) {
-        Map<String, Object> map = new LinkedHashMap<>();
-        map.put("memoryLimitMb", config.memoryLimitMb());
-        if (config.memoryReserveMb() != null) map.put("memoryReserveMb", config.memoryReserveMb());
-        map.put("cpuRequest", config.cpuRequest());
-        if (config.cpuLimit() != null) map.put("cpuLimit", config.cpuLimit());
-        map.put("appPort", config.appPort());
-        map.put("exposedPorts", config.exposedPorts());
-        map.put("customEnvVars", config.customEnvVars());
-        map.put("stripPathPrefix", config.stripPathPrefix());
-        map.put("sslOffloading", config.sslOffloading());
-        map.put("routingMode", config.routingMode());
-        map.put("routingDomain", config.routingDomain());
-        map.put("serverUrl", config.serverUrl());
-        map.put("replicas", config.replicas());
-        map.put("deploymentStrategy", config.deploymentStrategy());
-        map.put("runtimeType", config.runtimeType());
-        map.put("customArgs", config.customArgs());
-        map.put("extraNetworks", config.extraNetworks());
-        return map;
-    }
-}

cameleer-server-app/src/main/java/com/cameleer/server/app/runtime/DockerRuntimeOrchestrator.java

@@ -1,219 +0,0 @@
-package com.cameleer.server.app.runtime;
-
-import com.cameleer.server.core.runtime.ContainerRequest;
-import com.cameleer.server.core.runtime.ContainerStatus;
-import com.cameleer.server.core.runtime.RuntimeOrchestrator;
-import com.github.dockerjava.api.DockerClient;
-import com.github.dockerjava.api.async.ResultCallback;
-import com.github.dockerjava.api.model.AccessMode;
-import com.github.dockerjava.api.model.Bind;
-import com.github.dockerjava.api.model.Frame;
-import com.github.dockerjava.api.model.HealthCheck;
-import com.github.dockerjava.api.model.HostConfig;
-import com.github.dockerjava.api.model.RestartPolicy;
-import com.github.dockerjava.api.model.Volume;
-import jakarta.annotation.PreDestroy;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import java.io.IOException;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Map;
-import java.util.stream.Stream;
-
-public class DockerRuntimeOrchestrator implements RuntimeOrchestrator {
-
-    private static final Logger log = LoggerFactory.getLogger(DockerRuntimeOrchestrator.class);
-    private final DockerClient dockerClient;
-
-    private ContainerLogForwarder logForwarder;
-
-    public DockerRuntimeOrchestrator(DockerClient dockerClient) {
-        this.dockerClient = dockerClient;
-    }
-
-    public void setLogForwarder(ContainerLogForwarder logForwarder) {
-        this.logForwarder = logForwarder;
-    }
-
-    @PreDestroy
-    public void close() throws IOException {
-        if (dockerClient != null) {
-            dockerClient.close();
-        }
-    }
-
-    @Override
-    public boolean isEnabled() {
-        return true;
-    }
-
-    @Override
-    public void pullImage(String image) {
-        try {
-            log.info("Pulling image {}", image);
-            dockerClient.pullImageCmd(image).start().awaitCompletion();
-            log.info("Image pulled: {}", image);
-        } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            log.warn("Image pull interrupted for {}", image);
-        } catch (Exception e) {
-            log.warn("Failed to pull image {} (will use local cache if available): {}", image, e.getMessage());
-        }
-    }
-
-    @Override
-    public String startContainer(ContainerRequest request) {
-        List<String> envList = request.envVars().entrySet().stream()
-                .map(e -> e.getKey() + "=" + e.getValue()).toList();
-
-        HostConfig hostConfig = HostConfig.newHostConfig()
-                .withMemory(request.memoryLimitBytes())
-                .withMemorySwap(request.memoryLimitBytes())
-                .withCpuShares(request.cpuShares())
-                .withNetworkMode(request.network())
-                .withRestartPolicy(RestartPolicy.onFailureRestart(request.restartPolicyMaxRetries()));
-
-        // JAR mounting: volume mount (Docker-in-Docker) or bind mount (host path)
-        if (request.jarVolumeName() != null && !request.jarVolumeName().isBlank()) {
-            // Mount the named volume at the jar storage base path
-            Bind volumeBind = new Bind(request.jarVolumeName(), new Volume(request.jarVolumeMountPath()), AccessMode.ro);
-            hostConfig.withBinds(volumeBind);
-        } else {
-            Bind jarBind = new Bind(request.jarPath(), new Volume("/app/app.jar"), AccessMode.ro);
-            hostConfig.withBinds(jarBind);
-        }
-
-        if (request.memoryReserveBytes() != null) {
-            hostConfig.withMemoryReservation(request.memoryReserveBytes());
-        }
-        if (request.cpuQuota() != null) {
-            hostConfig.withCpuQuota(request.cpuQuota());
-        }
-
-        // Resolve the JAR path for the entrypoint
-        String appJarPath;
-        if (request.jarVolumeName() != null && !request.jarVolumeName().isBlank()) {
-            appJarPath = request.jarPath();
-        } else {
-            appJarPath = "/app/app.jar";
-        }
-
-        var createCmd = dockerClient.createContainerCmd(request.baseImage())
-                .withName(request.containerName())
-                .withEnv(envList)
-                .withLabels(request.labels() != null ? request.labels() : Map.of())
-                .withHostConfig(hostConfig)
-                .withHealthcheck(new HealthCheck()
-                        .withTest(List.of("CMD-SHELL",
-                                "wget -qO- http://localhost:" + request.healthCheckPort() + "/cameleer/health || exit 1"))
-                        .withInterval(10_000_000_000L)
-                        .withTimeout(5_000_000_000L)
-                        .withRetries(3)
-                        .withStartPeriod(30_000_000_000L));
-
-        // Build entrypoint based on runtime type
-        String customArgs = request.customArgs() != null && !request.customArgs().isBlank()
-                ? " " + request.customArgs() : "";
-        String entrypoint = switch (request.runtimeType()) {
-            case "plain-java" -> "exec java -javaagent:/app/agent.jar" + customArgs +
-                    " -cp " + appJarPath + " " + request.mainClass();
-            case "native" -> "exec " + appJarPath + customArgs;
-            default -> // spring-boot, quarkus, and others all use -jar
-                    "exec java -javaagent:/app/agent.jar" + customArgs + " -jar " + appJarPath;
-        };
-        createCmd.withEntrypoint("sh", "-c", entrypoint);
-
-        if (request.exposedPorts() != null && !request.exposedPorts().isEmpty()) {
-            var ports = request.exposedPorts().stream()
-                    .map(p -> com.github.dockerjava.api.model.ExposedPort.tcp(p))
-                    .toArray(com.github.dockerjava.api.model.ExposedPort[]::new);
-            createCmd.withExposedPorts(ports);
-        }
-
-        var container = createCmd.exec();
-        dockerClient.startContainerCmd(container.getId()).exec();
-
-        log.info("Started container {} ({})", request.containerName(), container.getId());
-        return container.getId();
-    }
-
-    public DockerClient getDockerClient() {
-        return dockerClient;
-    }
-
-    @Override
-    public void stopContainer(String containerId) {
-        try {
-            dockerClient.stopContainerCmd(containerId).withTimeout(30).exec();
-            log.info("Stopped container {}", containerId);
-        } catch (Exception e) {
-            log.warn("Failed to stop container {}: {}", containerId, e.getMessage());
-        }
-    }
-
-    @Override
-    public void removeContainer(String containerId) {
-        try {
-            dockerClient.removeContainerCmd(containerId).withForce(true).exec();
-            log.info("Removed container {}", containerId);
-        } catch (Exception e) {
-            log.warn("Failed to remove container {}: {}", containerId, e.getMessage());
-        }
-    }
-
-    @Override
-    public ContainerStatus getContainerStatus(String containerId) {
-        try {
-            var inspection = dockerClient.inspectContainerCmd(containerId).exec();
-            var state = inspection.getState();
-            var health = state.getHealth();
-            var healthStatus = health != null ? health.getStatus() : null;
-            // Use health status if available, otherwise fall back to container state
-            var effectiveState = healthStatus != null ? healthStatus : state.getStatus();
-            return new ContainerStatus(
-                    effectiveState,
-                    Boolean.TRUE.equals(state.getRunning()),
-                    state.getExitCodeLong() != null ? state.getExitCodeLong().intValue() : 0,
-                    state.getError());
-        } catch (Exception e) {
-            return new ContainerStatus("not_found", false, -1, e.getMessage());
-        }
-    }
-
-    @Override
-    public Stream<String> getLogs(String containerId, int tailLines) {
-        List<String> logLines = new ArrayList<>();
-        try {
-            dockerClient.logContainerCmd(containerId)
-                    .withStdOut(true)
-                    .withStdErr(true)
-                    .withTail(tailLines)
-                    .withTimestamps(true)
-                    .exec(new ResultCallback.Adapter<Frame>() {
-                        @Override
-                        public void onNext(Frame frame) {
-                            logLines.add(new String(frame.getPayload()).trim());
-                        }
-                    }).awaitCompletion();
-        } catch (Exception e) {
-            log.warn("Failed to get logs for container {}: {}", containerId, e.getMessage());
-        }
-        return logLines.stream();
-    }
-
-    @Override
-    public void startLogCapture(String containerId, String instanceId, String appSlug, String envSlug, String tenantId) {
-        if (logForwarder != null) {
-            logForwarder.startCapture(containerId, instanceId, appSlug, envSlug, tenantId);
-        }
-    }
-
-    @Override
-    public void stopLogCapture(String containerId) {
-        if (logForwarder != null) {
-            logForwarder.stopCapture(containerId);
-        }
-    }
-}

cameleer-server-app/src/main/java/io/cameleer/server/app/CameleerServerApplication.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app;
+package io.cameleer.server.app;
 
-import com.cameleer.server.app.config.AgentRegistryConfig;
+import io.cameleer.server.app.config.AgentRegistryConfig;
-import com.cameleer.server.app.config.IngestionConfig;
+import io.cameleer.server.app.config.IngestionConfig;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
@@ -13,11 +13,11 @@ import java.util.TimeZone;
 /**
  * Main entry point for the Cameleer Server application.
  * <p>
- * Scans {@code com.cameleer.server.app} and {@code com.cameleer.server.core} packages.
+ * Scans {@code io.cameleer.server.app} and {@code io.cameleer.server.core} packages.
  */
 @SpringBootApplication(scanBasePackages = {
-        "com.cameleer.server.app",
+        "io.cameleer.server.app",
-        "com.cameleer.server.core"
+        "io.cameleer.server.core"
 })
 @EnableAsync
 @EnableScheduling

cameleer-server-app/src/main/java/io/cameleer/server/app/agent/AgentLifecycleMonitor.java

@@ -1,10 +1,10 @@
-package com.cameleer.server.app.agent;
+package io.cameleer.server.app.agent;
 
-import com.cameleer.server.app.metrics.ServerMetrics;
+import io.cameleer.server.app.metrics.ServerMetrics;
-import com.cameleer.server.core.agent.AgentEventService;
+import io.cameleer.server.core.agent.AgentEventService;
-import com.cameleer.server.core.agent.AgentInfo;
+import io.cameleer.server.core.agent.AgentInfo;
-import com.cameleer.server.core.agent.AgentRegistryService;
+import io.cameleer.server.core.agent.AgentRegistryService;
-import com.cameleer.server.core.agent.AgentState;
+import io.cameleer.server.core.agent.AgentState;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;

cameleer-server-app/src/main/java/io/cameleer/server/app/agent/SseConnectionManager.java

@@ -1,9 +1,9 @@
-package com.cameleer.server.app.agent;
+package io.cameleer.server.app.agent;
 
-import com.cameleer.server.app.config.AgentRegistryConfig;
+import io.cameleer.server.app.config.AgentRegistryConfig;
-import com.cameleer.server.core.agent.AgentCommand;
+import io.cameleer.server.core.agent.AgentCommand;
-import com.cameleer.server.core.agent.AgentEventListener;
+import io.cameleer.server.core.agent.AgentEventListener;
-import com.cameleer.server.core.agent.AgentRegistryService;
+import io.cameleer.server.core.agent.AgentRegistryService;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.PostConstruct;

cameleer-server-app/src/main/java/io/cameleer/server/app/agent/SsePayloadSigner.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.agent;
+package io.cameleer.server.app.agent;
 
-import com.cameleer.server.core.security.Ed25519SigningService;
+import io.cameleer.server.core.security.Ed25519SigningService;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/config/AlertingBeanConfig.java

@@ -1,12 +1,12 @@
-package com.cameleer.server.app.alerting.config;
+package io.cameleer.server.app.alerting.config;
 
-import com.cameleer.server.app.alerting.eval.PerKindCircuitBreaker;
+import io.cameleer.server.app.alerting.eval.PerKindCircuitBreaker;
-import com.cameleer.server.app.alerting.metrics.AlertingMetrics;
+import io.cameleer.server.app.alerting.metrics.AlertingMetrics;
-import com.cameleer.server.app.alerting.storage.*;
+import io.cameleer.server.app.alerting.storage.*;
-import com.cameleer.server.core.alerting.AlertInstanceRepository;
+import io.cameleer.server.core.alerting.AlertInstanceRepository;
-import com.cameleer.server.core.alerting.AlertNotificationRepository;
+import io.cameleer.server.core.alerting.AlertNotificationRepository;
-import com.cameleer.server.core.alerting.AlertRuleRepository;
+import io.cameleer.server.core.alerting.AlertRuleRepository;
-import com.cameleer.server.core.alerting.AlertSilenceRepository;
+import io.cameleer.server.core.alerting.AlertSilenceRepository;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/config/AlertingProperties.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.config;
+package io.cameleer.server.app.alerting.config;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 
@@ -16,7 +16,8 @@ public record AlertingProperties(
         Integer eventRetentionDays,
         Integer notificationRetentionDays,
         Integer webhookTimeoutMs,
-        Integer webhookMaxAttempts) {
+        Integer webhookMaxAttempts,
+        Integer perExchangeDeployBacklogCapSeconds) {
 
     public int effectiveEvaluatorTickIntervalMs() {
         int raw = evaluatorTickIntervalMs == null ? 5000 : evaluatorTickIntervalMs;
@@ -70,4 +71,9 @@ public record AlertingProperties(
     public int cbCooldownSeconds() {
         return circuitBreakerCooldownSeconds == null ? 60 : circuitBreakerCooldownSeconds;
     }
+
+    public int effectivePerExchangeDeployBacklogCapSeconds() {
+        // Default 24 h. Zero or negative = disabled (no clamp — first-run uses rule.createdAt as today).
+        return perExchangeDeployBacklogCapSeconds == null ? 86_400 : perExchangeDeployBacklogCapSeconds;
+    }
 }

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/controller/AlertController.java

@@ -1,15 +1,15 @@
-package com.cameleer.server.app.alerting.controller;
+package io.cameleer.server.app.alerting.controller;
 
-import com.cameleer.server.app.alerting.dto.AlertDto;
+import io.cameleer.server.app.alerting.dto.AlertDto;
-import com.cameleer.server.app.alerting.dto.BulkIdsRequest;
+import io.cameleer.server.app.alerting.dto.BulkIdsRequest;
-import com.cameleer.server.app.alerting.dto.UnreadCountResponse;
+import io.cameleer.server.app.alerting.dto.UnreadCountResponse;
-import com.cameleer.server.app.alerting.notify.InAppInboxQuery;
+import io.cameleer.server.app.alerting.notify.InAppInboxQuery;
-import com.cameleer.server.app.web.EnvPath;
+import io.cameleer.server.app.web.EnvPath;
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertInstanceRepository;
+import io.cameleer.server.core.alerting.AlertInstanceRepository;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.AlertState;
+import io.cameleer.server.core.alerting.AlertState;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import org.springframework.http.HttpStatus;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/controller/AlertNotificationController.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.controller;
+package io.cameleer.server.app.alerting.controller;
 
-import com.cameleer.server.app.alerting.dto.AlertNotificationDto;
+import io.cameleer.server.app.alerting.dto.AlertNotificationDto;
-import com.cameleer.server.app.web.EnvPath;
+import io.cameleer.server.app.web.EnvPath;
-import com.cameleer.server.core.alerting.AlertNotification;
+import io.cameleer.server.core.alerting.AlertNotification;
-import com.cameleer.server.core.alerting.AlertNotificationRepository;
+import io.cameleer.server.core.alerting.AlertNotificationRepository;
-import com.cameleer.server.core.alerting.NotificationStatus;
+import io.cameleer.server.core.alerting.NotificationStatus;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.access.prepost.PreAuthorize;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/controller/AlertRuleController.java

@@ -1,31 +1,33 @@
-package com.cameleer.server.app.alerting.controller;
+package io.cameleer.server.app.alerting.controller;
 
-import com.cameleer.server.app.alerting.dto.AlertRuleRequest;
+import io.cameleer.server.app.alerting.dto.AlertRuleRequest;
-import com.cameleer.server.app.alerting.dto.AlertRuleResponse;
+import io.cameleer.server.app.alerting.dto.AlertRuleResponse;
-import com.cameleer.server.app.alerting.dto.RenderPreviewRequest;
+import io.cameleer.server.app.alerting.dto.RenderPreviewRequest;
-import com.cameleer.server.app.alerting.dto.RenderPreviewResponse;
+import io.cameleer.server.app.alerting.dto.RenderPreviewResponse;
-import com.cameleer.server.app.alerting.dto.TestEvaluateRequest;
+import io.cameleer.server.app.alerting.dto.TestEvaluateRequest;
-import com.cameleer.server.app.alerting.dto.TestEvaluateResponse;
+import io.cameleer.server.app.alerting.dto.TestEvaluateResponse;
-import com.cameleer.server.app.alerting.dto.WebhookBindingRequest;
+import io.cameleer.server.app.alerting.dto.WebhookBindingRequest;
-import com.cameleer.server.app.alerting.eval.ConditionEvaluator;
+import io.cameleer.server.app.alerting.eval.ConditionEvaluator;
-import com.cameleer.server.app.alerting.eval.EvalContext;
+import io.cameleer.server.app.alerting.eval.EvalContext;
-import com.cameleer.server.app.alerting.eval.EvalResult;
+import io.cameleer.server.app.alerting.eval.EvalResult;
-import com.cameleer.server.app.alerting.eval.TickCache;
+import io.cameleer.server.app.alerting.eval.TickCache;
-import com.cameleer.server.app.alerting.notify.MustacheRenderer;
+import io.cameleer.server.app.alerting.notify.MustacheRenderer;
-import com.cameleer.server.app.web.EnvPath;
+import io.cameleer.server.app.license.LicenseEnforcer;
-import com.cameleer.server.core.admin.AuditCategory;
+import io.cameleer.server.app.web.EnvPath;
-import com.cameleer.server.core.admin.AuditResult;
+import io.cameleer.server.core.admin.AuditCategory;
-import com.cameleer.server.core.admin.AuditService;
+import io.cameleer.server.core.admin.AuditResult;
-import com.cameleer.server.core.alerting.AlertCondition;
+import io.cameleer.server.core.admin.AuditService;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertCondition;
-import com.cameleer.server.core.alerting.AlertRuleRepository;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.AlertRuleTarget;
+import io.cameleer.server.core.alerting.AlertRuleRepository;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.AlertRuleTarget;
-import com.cameleer.server.core.alerting.ExchangeMatchCondition;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.WebhookBinding;
+import io.cameleer.server.core.alerting.ExchangeMatchCondition;
-import com.cameleer.server.core.outbound.OutboundConnection;
+import io.cameleer.server.core.alerting.FireMode;
-import com.cameleer.server.core.outbound.OutboundConnectionService;
+import io.cameleer.server.core.alerting.WebhookBinding;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.outbound.OutboundConnection;
+import io.cameleer.server.core.outbound.OutboundConnectionService;
+import io.cameleer.server.core.runtime.Environment;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
@@ -77,6 +79,7 @@ public class AlertRuleController {
     private final Map<ConditionKind, ConditionEvaluator<?>> evaluators;
     private final Clock clock;
     private final String tenantId;
+    private final LicenseEnforcer licenseEnforcer;
 
     @SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
     public AlertRuleController(AlertRuleRepository ruleRepo,
@@ -85,7 +88,8 @@ public class AlertRuleController {
                                MustacheRenderer renderer,
                                List<ConditionEvaluator<?>> evaluatorList,
                                Clock alertingClock,
-                               @Value("${cameleer.server.tenant.id:default}") String tenantId) {
+                               @Value("${cameleer.server.tenant.id:default}") String tenantId,
+                               LicenseEnforcer licenseEnforcer) {
         this.ruleRepo = ruleRepo;
         this.connectionService = connectionService;
         this.auditService = auditService;
@@ -96,6 +100,7 @@ public class AlertRuleController {
         }
         this.clock = alertingClock;
         this.tenantId = tenantId;
+        this.licenseEnforcer = licenseEnforcer;
     }
 
     // -------------------------------------------------------------------------
@@ -125,7 +130,10 @@ public class AlertRuleController {
             @Valid @RequestBody AlertRuleRequest req,
             HttpServletRequest httpRequest) {
 
+        licenseEnforcer.assertWithinCap("max_alert_rules", ruleRepo.count(), 1);
+
         validateAttributeKeys(req.condition());
+        validateBusinessRules(req);
         validateWebhooks(req.webhooks(), env.id());
 
         AlertRule draft = buildRule(null, env.id(), req, currentUserId());
@@ -147,6 +155,7 @@ public class AlertRuleController {
 
         AlertRule existing = requireRule(id, env.id());
         validateAttributeKeys(req.condition());
+        validateBusinessRules(req);
         validateWebhooks(req.webhooks(), env.id());
 
         AlertRule updated = buildRule(existing, env.id(), req, currentUserId());
@@ -258,6 +267,36 @@ public class AlertRuleController {
     // Helpers
     // -------------------------------------------------------------------------
 
+    /**
+     * Cross-field business-rule validation for {@link AlertRuleRequest}.
+     *
+     * <p>PER_EXCHANGE rules: re-notify and for-duration are nonsensical (each fire is its own
+     * exchange — there's no "still firing" window and nothing to re-notify about). Reject 400
+     * if either is non-zero.
+     *
+     * <p>All rules: reject 400 if both webhooks and targets are empty — such a rule can never
+     * notify anyone and is a pure footgun.
+     */
+    private void validateBusinessRules(AlertRuleRequest req) {
+        if (req.condition() instanceof ExchangeMatchCondition ex
+                && ex.fireMode() == FireMode.PER_EXCHANGE) {
+            if (req.reNotifyMinutes() != null && req.reNotifyMinutes() != 0) {
+                throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                        "reNotifyMinutes must be 0 for PER_EXCHANGE rules (re-notify does not apply)");
+            }
+            if (req.forDurationSeconds() != null && req.forDurationSeconds() != 0) {
+                throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                        "forDurationSeconds must be 0 for PER_EXCHANGE rules");
+            }
+        }
+        boolean noWebhooks = req.webhooks() == null || req.webhooks().isEmpty();
+        boolean noTargets  = req.targets()  == null || req.targets().isEmpty();
+        if (noWebhooks && noTargets) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                    "rule must have at least one webhook or target — otherwise it never notifies anyone");
+        }
+    }
+
     /**
      * Validates that all attribute keys in an {@link ExchangeMatchCondition} match
      * {@code ^[a-zA-Z0-9._-]+$}. Keys are inlined into ClickHouse SQL, making this

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/controller/AlertSilenceController.java

@@ -1,14 +1,14 @@
-package com.cameleer.server.app.alerting.controller;
+package io.cameleer.server.app.alerting.controller;
 
-import com.cameleer.server.app.alerting.dto.AlertSilenceRequest;
+import io.cameleer.server.app.alerting.dto.AlertSilenceRequest;
-import com.cameleer.server.app.alerting.dto.AlertSilenceResponse;
+import io.cameleer.server.app.alerting.dto.AlertSilenceResponse;
-import com.cameleer.server.app.web.EnvPath;
+import io.cameleer.server.app.web.EnvPath;
-import com.cameleer.server.core.admin.AuditCategory;
+import io.cameleer.server.core.admin.AuditCategory;
-import com.cameleer.server.core.admin.AuditResult;
+import io.cameleer.server.core.admin.AuditResult;
-import com.cameleer.server.core.admin.AuditService;
+import io.cameleer.server.core.admin.AuditService;
-import com.cameleer.server.core.alerting.AlertSilence;
+import io.cameleer.server.core.alerting.AlertSilence;
-import com.cameleer.server.core.alerting.AlertSilenceRepository;
+import io.cameleer.server.core.alerting.AlertSilenceRepository;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertDto.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.AlertState;
+import io.cameleer.server.core.alerting.AlertState;
 
 import java.time.Instant;
 import java.util.Map;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertNotificationDto.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertNotification;
+import io.cameleer.server.core.alerting.AlertNotification;
-import com.cameleer.server.core.alerting.NotificationStatus;
+import io.cameleer.server.core.alerting.NotificationStatus;
 
 import java.time.Instant;
 import java.util.UUID;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertRuleRequest.java

@@ -1,9 +1,9 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertCondition;
+import io.cameleer.server.core.alerting.AlertCondition;
-import com.cameleer.server.core.alerting.AlertRuleTarget;
+import io.cameleer.server.core.alerting.AlertRuleTarget;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertRuleResponse.java

@@ -1,10 +1,10 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertCondition;
+import io.cameleer.server.core.alerting.AlertCondition;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.AlertRuleTarget;
+import io.cameleer.server.core.alerting.AlertRuleTarget;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
 
 import java.time.Instant;
 import java.util.List;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertSilenceRequest.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.SilenceMatcher;
+import io.cameleer.server.core.alerting.SilenceMatcher;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotNull;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/AlertSilenceResponse.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertSilence;
+import io.cameleer.server.core.alerting.AlertSilence;
-import com.cameleer.server.core.alerting.SilenceMatcher;
+import io.cameleer.server.core.alerting.SilenceMatcher;
 
 import java.time.Instant;
 import java.util.UUID;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/BulkIdsRequest.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Size;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/RenderPreviewRequest.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
 import java.util.Map;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/RenderPreviewResponse.java

@@ -1,3 +1,3 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
 public record RenderPreviewResponse(String title, String message) {}

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/TestEvaluateRequest.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
 /**
  * Request body for POST {id}/test-evaluate.

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/TestEvaluateResponse.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.app.alerting.eval.EvalResult;
+import io.cameleer.server.app.alerting.eval.EvalResult;
 
 /**
  * Result of a one-shot evaluator run against live data (does not persist any state).

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/UnreadCountResponse.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
 
 import java.util.EnumMap;
 import java.util.Map;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/WebhookBindingRequest.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
 import jakarta.validation.constraints.NotNull;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/dto/WebhookBindingResponse.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.dto;
+package io.cameleer.server.app.alerting.dto;
 
-import com.cameleer.server.core.alerting.WebhookBinding;
+import io.cameleer.server.core.alerting.WebhookBinding;
 
 import java.util.Map;
 import java.util.UUID;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/AgentLifecycleEvaluator.java

@@ -1,13 +1,13 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.agent.AgentEventRecord;
+import io.cameleer.server.core.agent.AgentEventRecord;
-import com.cameleer.server.core.agent.AgentEventRepository;
+import io.cameleer.server.core.agent.AgentEventRepository;
-import com.cameleer.server.core.alerting.AgentLifecycleCondition;
+import io.cameleer.server.core.alerting.AgentLifecycleCondition;
-import com.cameleer.server.core.alerting.AgentLifecycleEventType;
+import io.cameleer.server.core.alerting.AgentLifecycleEventType;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.AlertScope;
+import io.cameleer.server.core.alerting.AlertScope;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
 import org.springframework.stereotype.Component;
 
 import java.time.Instant;
@@ -64,13 +64,13 @@ public class AgentLifecycleEvaluator implements ConditionEvaluator<AgentLifecycl
         List<AgentEventRecord> matches = eventRepo.findInWindow(
                 envSlug, appSlug, agentId, typeNames, from, to, MAX_EVENTS_PER_TICK);
 
-        if (matches.isEmpty()) return new EvalResult.Batch(List.of());
+        if (matches.isEmpty()) return new EvalResult.Batch(List.of(), Map.of());
 
         List<EvalResult.Firing> firings = new ArrayList<>(matches.size());
         for (AgentEventRecord ev : matches) {
             firings.add(toFiring(ev));
         }
-        return new EvalResult.Batch(firings);
+        return new EvalResult.Batch(firings, Map.of());
     }
 
     private static EvalResult.Firing toFiring(AgentEventRecord ev) {

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/AgentStateEvaluator.java

@@ -1,12 +1,12 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.agent.AgentInfo;
+import io.cameleer.server.core.agent.AgentInfo;
-import com.cameleer.server.core.agent.AgentRegistryService;
+import io.cameleer.server.core.agent.AgentRegistryService;
-import com.cameleer.server.core.agent.AgentState;
+import io.cameleer.server.core.agent.AgentState;
-import com.cameleer.server.core.alerting.AgentStateCondition;
+import io.cameleer.server.core.alerting.AgentStateCondition;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.AlertScope;
+import io.cameleer.server.core.alerting.AlertScope;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
 import org.springframework.stereotype.Component;
 
 import java.time.Instant;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/AlertEvaluatorJob.java

@@ -1,12 +1,12 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.app.alerting.config.AlertingProperties;
+import io.cameleer.server.app.alerting.config.AlertingProperties;
-import com.cameleer.server.app.alerting.metrics.AlertingMetrics;
+import io.cameleer.server.app.alerting.metrics.AlertingMetrics;
-import com.cameleer.server.app.alerting.notify.MustacheRenderer;
+import io.cameleer.server.app.alerting.notify.MustacheRenderer;
-import com.cameleer.server.app.alerting.notify.NotificationContextBuilder;
+import io.cameleer.server.app.alerting.notify.NotificationContextBuilder;
-import com.cameleer.server.core.alerting.*;
+import io.cameleer.server.core.alerting.*;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -47,6 +47,7 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
     private final NotificationContextBuilder contextBuilder;
     private final EnvironmentRepository environmentRepo;
     private final ObjectMapper objectMapper;
+    private final BatchResultApplier batchResultApplier;
     private final String instanceId;
     private final String tenantId;
     private final Clock clock;
@@ -64,6 +65,7 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
             NotificationContextBuilder contextBuilder,
             EnvironmentRepository environmentRepo,
             ObjectMapper objectMapper,
+            BatchResultApplier batchResultApplier,
             @Qualifier("alertingInstanceId") String instanceId,
             @Value("${cameleer.server.tenant.id:default}") String tenantId,
             Clock alertingClock,
@@ -80,6 +82,7 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
         this.contextBuilder     = contextBuilder;
         this.environmentRepo    = environmentRepo;
         this.objectMapper       = objectMapper;
+        this.batchResultApplier = batchResultApplier;
         this.instanceId         = instanceId;
         this.tenantId           = tenantId;
         this.clock              = alertingClock;
@@ -112,23 +115,63 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
 
         for (AlertRule rule : claimed) {
             Instant nextRun = Instant.now(clock).plusSeconds(rule.evaluationIntervalSeconds());
-            try {
             if (circuitBreaker.isOpen(rule.conditionKind())) {
                 log.debug("Circuit breaker open for {}; skipping rule {}", rule.conditionKind(), rule.id());
+                reschedule(rule, nextRun);
                 continue;
             }
-                EvalResult result = metrics.evalDuration(rule.conditionKind())
+
+            EvalResult result;
+            try {
+                result = metrics.evalDuration(rule.conditionKind())
                         .recordCallable(() -> evaluateSafely(rule, ctx));
+            } catch (Exception e) {
+                metrics.evalError(rule.conditionKind(), rule.id());
+                circuitBreaker.recordFailure(rule.conditionKind());
+                log.warn("Evaluator error for rule {} ({}): {}", rule.id(), rule.conditionKind(), e.toString());
+                // Evaluation itself failed — release the claim so the rule can be
+                // retried on the next tick. Cursor stays put.
+                reschedule(rule, nextRun);
+                continue;
+            }
+
+            if (result instanceof EvalResult.Batch b) {
+                // Phase 2: the Batch path is atomic. The @Transactional apply() on
+                // BatchResultApplier wraps instance writes, notification enqueues,
+                // AND the cursor advance + releaseClaim into a single tx. A
+                // mid-batch fault rolls everything back — including the cursor —
+                // so the next tick replays the whole batch exactly once.
+                try {
+                    batchResultApplier.apply(rule, b, nextRun);
+                    circuitBreaker.recordSuccess(rule.conditionKind());
+                } catch (Exception e) {
+                    metrics.evalError(rule.conditionKind(), rule.id());
+                    circuitBreaker.recordFailure(rule.conditionKind());
+                    log.warn("Batch apply failed for rule {} ({}): {} — rolling back; next tick will retry",
+                            rule.id(), rule.conditionKind(), e.toString());
+                    // The transaction rolled back. Do NOT call reschedule here —
+                    // leaving claim + next_evaluation_at as they were means the
+                    // claim TTL takes over and the rule becomes due on its own.
+                    // Rethrowing is unnecessary for correctness — the cursor
+                    // stayed put, so exactly-once-per-exchange is preserved.
+                }
+            } else {
+                // Non-Batch path (FIRING / Clear / Error): classic apply + rule
+                // reschedule. Not wrapped in a single tx — semantics unchanged
+                // from pre-Phase-2.
+                try {
                     applyResult(rule, result);
                     circuitBreaker.recordSuccess(rule.conditionKind());
                 } catch (Exception e) {
                     metrics.evalError(rule.conditionKind(), rule.id());
                     circuitBreaker.recordFailure(rule.conditionKind());
-                log.warn("Evaluator error for rule {} ({}): {}", rule.id(), rule.conditionKind(), e.toString());
+                    log.warn("applyResult failed for rule {} ({}): {}",
+                            rule.id(), rule.conditionKind(), e.toString());
                 } finally {
                     reschedule(rule, nextRun);
                 }
             }
+        }
 
         sweepReNotify();
     }
@@ -171,14 +214,10 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
     // -------------------------------------------------------------------------
 
     private void applyResult(AlertRule rule, EvalResult result) {
-        if (result instanceof EvalResult.Batch b) {
+        // Note: the Batch path is handled by BatchResultApplier (transactional) —
-            // PER_EXCHANGE mode: each Firing in the batch creates its own AlertInstance
+        // tick() routes Batch results there directly and never calls applyResult
-            for (EvalResult.Firing f : b.firings()) {
+        // for them. This method only handles FIRING / Clear / Error state-machine
-                applyBatchFiring(rule, f);
+        // transitions for the classic (non-PER_EXCHANGE) path.
-            }
-            return;
-        }
-
         AlertInstance current = instanceRepo.findOpenForRule(rule.id()).orElse(null);
         Instant now = Instant.now(clock);
 
@@ -199,19 +238,6 @@ public class AlertEvaluatorJob implements SchedulingConfigurer {
         });
     }
 
-    /**
-     * Batch (PER_EXCHANGE) mode: always create a fresh FIRING instance per Firing entry.
-     * No forDuration check — each exchange is its own event.
-     */
-    private void applyBatchFiring(AlertRule rule, EvalResult.Firing f) {
-        Instant now = Instant.now(clock);
-        AlertInstance instance = AlertStateTransitions.newInstance(rule, f, AlertState.FIRING, now)
-                .withRuleSnapshot(snapshotRule(rule));
-        AlertInstance enriched = enrichTitleMessage(rule, instance);
-        AlertInstance persisted = instanceRepo.save(enriched);
-        enqueueNotifications(rule, persisted, now);
-    }
-
     // -------------------------------------------------------------------------
     // Title / message rendering
     // -------------------------------------------------------------------------

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/AlertStateTransitions.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.AlertRuleTarget;
+import io.cameleer.server.core.alerting.AlertRuleTarget;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.AlertState;
+import io.cameleer.server.core.alerting.AlertState;
-import com.cameleer.server.core.alerting.TargetKind;
+import io.cameleer.server.core.alerting.TargetKind;
 
 import java.time.Instant;
 import java.util.List;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/BatchResultApplier.java

@@ -0,0 +1,144 @@
+package io.cameleer.server.app.alerting.eval;
+
+import io.cameleer.server.app.alerting.notify.MustacheRenderer;
+import io.cameleer.server.app.alerting.notify.NotificationContextBuilder;
+import io.cameleer.server.core.alerting.*;
+import io.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * Applies a {@link EvalResult.Batch} result to persistent state inside a single
+ * transaction: instance writes, notification enqueues, and the rule's cursor
+ * advance + {@code releaseClaim} either all commit or all roll back together.
+ * <p>
+ * Lives in its own bean so the {@code @Transactional} annotation engages via the
+ * Spring proxy when invoked from {@link AlertEvaluatorJob#tick()}; calling it as
+ * {@code this.apply(...)} from {@code AlertEvaluatorJob} (a bean calling its own
+ * method) would bypass the proxy and silently disable the transaction.
+ * <p>
+ * Phase 2 of the per-exchange exactly-once plan (see
+ * {@code docs/superpowers/plans/2026-04-22-per-exchange-exactly-once.md}).
+ */
+@Component
+public class BatchResultApplier {
+
+    private static final Logger log = LoggerFactory.getLogger(BatchResultApplier.class);
+
+    private final AlertRuleRepository ruleRepo;
+    private final AlertInstanceRepository instanceRepo;
+    private final AlertNotificationRepository notificationRepo;
+    private final MustacheRenderer renderer;
+    private final NotificationContextBuilder contextBuilder;
+    private final EnvironmentRepository environmentRepo;
+    private final ObjectMapper objectMapper;
+    private final Clock clock;
+
+    public BatchResultApplier(
+            AlertRuleRepository ruleRepo,
+            AlertInstanceRepository instanceRepo,
+            AlertNotificationRepository notificationRepo,
+            MustacheRenderer renderer,
+            NotificationContextBuilder contextBuilder,
+            EnvironmentRepository environmentRepo,
+            ObjectMapper objectMapper,
+            Clock alertingClock) {
+        this.ruleRepo         = ruleRepo;
+        this.instanceRepo     = instanceRepo;
+        this.notificationRepo = notificationRepo;
+        this.renderer         = renderer;
+        this.contextBuilder   = contextBuilder;
+        this.environmentRepo  = environmentRepo;
+        this.objectMapper     = objectMapper;
+        this.clock            = alertingClock;
+    }
+
+    /**
+     * Atomically apply a Batch result for a single rule:
+     * <ol>
+     *   <li>persist a FIRING instance per firing + enqueue its notifications</li>
+     *   <li>advance the rule's cursor ({@code evalState}) iff the batch supplied one</li>
+     *   <li>release the claim with the new {@code nextRun} + {@code evalState}</li>
+     * </ol>
+     * Any exception thrown from the repo calls rolls back every write — including
+     * the cursor advance — so the rule is replayable on the next tick.
+     */
+    @Transactional
+    public void apply(AlertRule rule, EvalResult.Batch batch, Instant nextRun) {
+        for (EvalResult.Firing f : batch.firings()) {
+            applyBatchFiring(rule, f);
+        }
+        Map<String, Object> nextEvalState =
+                batch.nextEvalState().isEmpty() ? rule.evalState() : batch.nextEvalState();
+        ruleRepo.releaseClaim(rule.id(), nextRun, nextEvalState);
+    }
+
+    /**
+     * Batch (PER_EXCHANGE) mode: always create a fresh FIRING instance per Firing entry.
+     * No forDuration check — each exchange is its own event.
+     */
+    private void applyBatchFiring(AlertRule rule, EvalResult.Firing f) {
+        Instant now = Instant.now(clock);
+        AlertInstance instance = AlertStateTransitions.newInstance(rule, f, AlertState.FIRING, now)
+                .withRuleSnapshot(snapshotRule(rule));
+        AlertInstance enriched = enrichTitleMessage(rule, instance);
+        AlertInstance persisted = instanceRepo.save(enriched);
+        enqueueNotifications(rule, persisted, now);
+    }
+
+    private AlertInstance enrichTitleMessage(AlertRule rule, AlertInstance instance) {
+        Environment env = environmentRepo.findById(rule.environmentId()).orElse(null);
+        Map<String, Object> ctx = contextBuilder.build(rule, instance, env, null);
+        String title   = renderer.render(rule.notificationTitleTmpl(), ctx);
+        String message = renderer.render(rule.notificationMessageTmpl(), ctx);
+        return instance.withTitleMessage(title, message);
+    }
+
+    private void enqueueNotifications(AlertRule rule, AlertInstance instance, Instant now) {
+        for (WebhookBinding w : rule.webhooks()) {
+            Map<String, Object> payload = buildPayload(rule, instance);
+            notificationRepo.save(new AlertNotification(
+                    UUID.randomUUID(),
+                    instance.id(),
+                    w.id(),
+                    w.outboundConnectionId(),
+                    NotificationStatus.PENDING,
+                    0,
+                    now,
+                    null, null, null, null,
+                    payload,
+                    null,
+                    now));
+        }
+    }
+
+    private Map<String, Object> buildPayload(AlertRule rule, AlertInstance instance) {
+        Environment env = environmentRepo.findById(rule.environmentId()).orElse(null);
+        return contextBuilder.build(rule, instance, env, null);
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> snapshotRule(AlertRule rule) {
+        try {
+            Map<String, Object> raw = objectMapper.convertValue(rule, Map.class);
+            // Map.copyOf (used in AlertInstance compact ctor) rejects null values —
+            // strip them so the snapshot is safe to store.
+            Map<String, Object> safe = new LinkedHashMap<>();
+            raw.forEach((k, v) -> { if (v != null) safe.put(k, v); });
+            return safe;
+        } catch (Exception e) {
+            log.warn("Failed to snapshot rule {}: {}", rule.id(), e.getMessage());
+            return Map.of("id", rule.id().toString(), "name", rule.name());
+        }
+    }
+}

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/ConditionEvaluator.java

@@ -0,0 +1,12 @@
+package io.cameleer.server.app.alerting.eval;
+
+import io.cameleer.server.core.alerting.AlertCondition;
+import io.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.ConditionKind;
+
+public interface ConditionEvaluator<C extends AlertCondition> {
+
+    ConditionKind kind();
+
+    EvalResult evaluate(C condition, AlertRule rule, EvalContext ctx);
+}

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/DeploymentStateEvaluator.java

@@ -1,12 +1,12 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.DeploymentStateCondition;
+import io.cameleer.server.core.alerting.DeploymentStateCondition;
-import com.cameleer.server.core.runtime.App;
+import io.cameleer.server.core.runtime.App;
-import com.cameleer.server.core.runtime.AppRepository;
+import io.cameleer.server.core.runtime.AppRepository;
-import com.cameleer.server.core.runtime.Deployment;
+import io.cameleer.server.core.runtime.Deployment;
-import com.cameleer.server.core.runtime.DeploymentRepository;
+import io.cameleer.server.core.runtime.DeploymentRepository;
 import org.springframework.stereotype.Component;
 
 import java.util.List;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/EvalContext.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
 import java.time.Instant;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/EvalResult.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
 import java.util.List;
 import java.util.Map;
@@ -17,9 +17,14 @@ public sealed interface EvalResult {
 
     record Error(Throwable cause) implements EvalResult {}
 
-    record Batch(List<Firing> firings) implements EvalResult {
+    record Batch(List<Firing> firings, Map<String, Object> nextEvalState) implements EvalResult {
         public Batch {
             firings = firings == null ? List.of() : List.copyOf(firings);
+            nextEvalState = nextEvalState == null ? Map.of() : Map.copyOf(nextEvalState);
+        }
+        /** Convenience: a Batch with no cursor update (first-run empty, or no matches). */
+        public static Batch empty() {
+            return new Batch(List.of(), Map.of());
         }
     }
 }

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/ExchangeMatchEvaluator.java

@@ -1,19 +1,21 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.app.search.ClickHouseSearchIndex;
+import io.cameleer.server.app.alerting.config.AlertingProperties;
-import com.cameleer.server.core.alerting.AlertMatchSpec;
+import io.cameleer.server.app.search.ClickHouseSearchIndex;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertMatchSpec;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ExchangeMatchCondition;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.FireMode;
+import io.cameleer.server.core.alerting.ExchangeMatchCondition;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.alerting.FireMode;
-import com.cameleer.server.core.search.ExecutionSummary;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
-import com.cameleer.server.core.search.SearchRequest;
+import io.cameleer.server.core.search.ExecutionSummary;
-import com.cameleer.server.core.search.SearchResult;
+import io.cameleer.server.core.search.SearchRequest;
+import io.cameleer.server.core.search.SearchResult;
 import org.springframework.stereotype.Component;
 
 import java.time.Instant;
 import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -23,10 +25,14 @@ public class ExchangeMatchEvaluator implements ConditionEvaluator<ExchangeMatchC
 
     private final ClickHouseSearchIndex searchIndex;
     private final EnvironmentRepository envRepo;
+    private final AlertingProperties alertingProperties;
 
-    public ExchangeMatchEvaluator(ClickHouseSearchIndex searchIndex, EnvironmentRepository envRepo) {
+    public ExchangeMatchEvaluator(ClickHouseSearchIndex searchIndex,
+                                  EnvironmentRepository envRepo,
+                                  AlertingProperties alertingProperties) {
         this.searchIndex        = searchIndex;
         this.envRepo            = envRepo;
+        this.alertingProperties = alertingProperties;
     }
 
     @Override
@@ -85,19 +91,31 @@ public class ExchangeMatchEvaluator implements ConditionEvaluator<ExchangeMatchC
         String routeId = c.scope() != null ? c.scope().routeId() : null;
         ExchangeMatchCondition.ExchangeFilter filter = c.filter();
 
-        // Resolve cursor from evalState
+        // Resolve composite cursor: (startTime, executionId)
-        Instant cursor = null;
+        Instant cursorTs;
-        Object raw = rule.evalState().get("lastExchangeTs");
+        String cursorId;
+        Object raw = rule.evalState().get("lastExchangeCursor");
         if (raw instanceof String s && !s.isBlank()) {
-            try { cursor = Instant.parse(s); } catch (Exception ignored) {}
+            int pipe = s.indexOf('|');
-        } else if (raw instanceof Instant i) {
+            if (pipe < 0) {
-            cursor = i;
+                // Malformed — treat as first-run (with deploy-backlog-cap clamp).
+                cursorTs = firstRunCursorTs(rule, ctx);
+                cursorId = "";
+            } else {
+                cursorTs = Instant.parse(s.substring(0, pipe));
+                cursorId = s.substring(pipe + 1);
+            }
+        } else {
+            // First run — bounded by rule.createdAt, empty executionId so any real id sorts after it.
+            // Clamp to deploy-backlog-cap to avoid backlog flooding for long-lived rules on first
+            // post-deploy tick. Normal-advance path (valid cursor above) is intentionally unaffected.
+            cursorTs = firstRunCursorTs(rule, ctx);
+            cursorId = "";
         }
 
-        // Build SearchRequest — use cursor as timeFrom so we only see exchanges after last run
         var req = new SearchRequest(
                 filter != null ? filter.status() : null,
-                cursor,                          // timeFrom = cursor (or null for first run)
+                cursorTs,                        // timeFrom
                 ctx.now(),                       // timeTo
                 null, null, null,                // durationMin/Max, correlationId
                 null, null, null, null,          // text variants
@@ -110,23 +128,26 @@ public class ExchangeMatchEvaluator implements ConditionEvaluator<ExchangeMatchC
                 50,
                 "startTime",
                 "asc",                           // asc so we process oldest first
+                cursorId.isEmpty() ? null : cursorId,  // afterExecutionId — null on first run enables >=
                 envSlug
         );
 
         SearchResult<ExecutionSummary> result = searchIndex.search(req);
         List<ExecutionSummary> matches = result.data();
 
-        if (matches.isEmpty()) return new EvalResult.Batch(List.of());
+        if (matches.isEmpty()) return EvalResult.Batch.empty();
 
-        // Find the latest startTime across all matches — becomes the next cursor
+        // Ensure deterministic ordering for cursor advance
-        Instant latestTs = matches.stream()
+        matches = new ArrayList<>(matches);
-                .map(ExecutionSummary::startTime)
+        matches.sort(Comparator
-                .max(Instant::compareTo)
+                .comparing(ExecutionSummary::startTime)
-                .orElse(ctx.now());
+                .thenComparing(ExecutionSummary::executionId));
+
+        ExecutionSummary last = matches.get(matches.size() - 1);
+        String nextCursorSerialized = last.startTime().toString() + "|" + last.executionId();
 
         List<EvalResult.Firing> firings = new ArrayList<>();
-        for (int i = 0; i < matches.size(); i++) {
+        for (ExecutionSummary ex : matches) {
-            ExecutionSummary ex = matches.get(i);
             Map<String, Object> ctx2 = new HashMap<>();
             ctx2.put("exchange", Map.of(
                     "id",        ex.executionId(),
@@ -135,15 +156,32 @@ public class ExchangeMatchEvaluator implements ConditionEvaluator<ExchangeMatchC
                     "startTime", ex.startTime() == null ? "" : ex.startTime().toString()
             ));
             ctx2.put("app", Map.of("slug", ex.applicationId() == null ? "" : ex.applicationId()));
-
-            // Attach the next-cursor to the last firing so the job can extract it
-            if (i == matches.size() - 1) {
-                ctx2.put("_nextCursor", latestTs);
-            }
-
             firings.add(new EvalResult.Firing(1.0, null, ctx2));
         }
 
-        return new EvalResult.Batch(firings);
+        Map<String, Object> nextEvalState = new HashMap<>(rule.evalState());
+        nextEvalState.put("lastExchangeCursor", nextCursorSerialized);
+        return new EvalResult.Batch(firings, nextEvalState);
+    }
+
+    /**
+     * First-run cursor timestamp: {@code rule.createdAt()}, clamped to
+     * {@code now - perExchangeDeployBacklogCapSeconds} so a long-lived PER_EXCHANGE rule
+     * doesn't scan from its creation date forward on first post-deploy tick.
+     * <p>
+     * Cap ≤ 0 disables the clamp (first-run falls back to {@code rule.createdAt()} verbatim).
+     * Applied only on first-run / malformed-cursor paths — the normal-advance path is
+     * intentionally unaffected so legitimate missed ticks are not silently skipped.
+     */
+    private Instant firstRunCursorTs(AlertRule rule, EvalContext ctx) {
+        Instant cursorTs = rule.createdAt();
+        int capSeconds = alertingProperties.effectivePerExchangeDeployBacklogCapSeconds();
+        if (capSeconds > 0) {
+            Instant capFloor = ctx.now().minusSeconds(capSeconds);
+            if (cursorTs == null || cursorTs.isBefore(capFloor)) {
+                cursorTs = capFloor;
+            }
+        }
+        return cursorTs;
     }
 }

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/JvmMetricEvaluator.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.alerting.AggregationOp;
+import io.cameleer.server.core.alerting.AggregationOp;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.JvmMetricCondition;
+import io.cameleer.server.core.alerting.JvmMetricCondition;
-import com.cameleer.server.core.storage.MetricsQueryStore;
+import io.cameleer.server.core.storage.MetricsQueryStore;
-import com.cameleer.server.core.storage.model.MetricTimeSeries;
+import io.cameleer.server.core.storage.model.MetricTimeSeries;
 import org.springframework.stereotype.Component;
 
 import java.util.List;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/LogPatternEvaluator.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.app.search.ClickHouseLogStore;
+import io.cameleer.server.app.search.ClickHouseLogStore;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.LogPatternCondition;
+import io.cameleer.server.core.alerting.LogPatternCondition;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
-import com.cameleer.server.core.search.LogSearchRequest;
+import io.cameleer.server.core.search.LogSearchRequest;
 import org.springframework.stereotype.Component;
 
 import java.time.Instant;
@@ -61,7 +61,8 @@ public class LogPatternEvaluator implements ConditionEvaluator<LogPatternConditi
                     to,
                     null,   // cursor
                     1,      // limit (count query; value irrelevant)
-                    "desc"  // sort
+                    "desc", // sort
+                    null    // instanceIds
             );
             return logStore.countLogs(req);
         });

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/PerKindCircuitBreaker.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.app.alerting.metrics.AlertingMetrics;
+import io.cameleer.server.app.alerting.metrics.AlertingMetrics;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
 
 import java.time.Clock;
 import java.time.Duration;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/RouteMetricEvaluator.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.RouteMetricCondition;
+import io.cameleer.server.core.alerting.RouteMetricCondition;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
-import com.cameleer.server.core.search.ExecutionStats;
+import io.cameleer.server.core.search.ExecutionStats;
-import com.cameleer.server.core.storage.StatsStore;
+import io.cameleer.server.core.storage.StatsStore;
 import org.springframework.stereotype.Component;
 
 import java.time.Instant;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/eval/TickCache.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.eval;
+package io.cameleer.server.app.alerting.eval;
 
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Supplier;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/metrics/AlertingMetrics.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.metrics;
+package io.cameleer.server.app.alerting.metrics;
 
-import com.cameleer.server.core.alerting.AlertState;
+import io.cameleer.server.core.alerting.AlertState;
-import com.cameleer.server.core.alerting.ConditionKind;
+import io.cameleer.server.core.alerting.ConditionKind;
-import com.cameleer.server.core.alerting.NotificationStatus;
+import io.cameleer.server.core.alerting.NotificationStatus;
 import io.micrometer.core.instrument.Counter;
 import io.micrometer.core.instrument.Gauge;
 import io.micrometer.core.instrument.MeterRegistry;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/HmacSigner.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
 import org.springframework.stereotype.Component;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/InAppInboxQuery.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
-import com.cameleer.server.app.alerting.dto.UnreadCountResponse;
+import io.cameleer.server.app.alerting.dto.UnreadCountResponse;
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertInstanceRepository;
+import io.cameleer.server.core.alerting.AlertInstanceRepository;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.AlertState;
+import io.cameleer.server.core.alerting.AlertState;
-import com.cameleer.server.core.rbac.RbacService;
+import io.cameleer.server.core.rbac.RbacService;
 import org.springframework.stereotype.Component;
 
 import java.time.Clock;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/MustacheRenderer.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
 import com.samskivert.mustache.Mustache;
 import org.slf4j.Logger;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/NotificationContextBuilder.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
 import org.springframework.stereotype.Component;
 
 import java.util.LinkedHashMap;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/NotificationDispatchJob.java

@@ -1,11 +1,11 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
-import com.cameleer.server.app.alerting.config.AlertingProperties;
+import io.cameleer.server.app.alerting.config.AlertingProperties;
-import com.cameleer.server.app.alerting.metrics.AlertingMetrics;
+import io.cameleer.server.app.alerting.metrics.AlertingMetrics;
-import com.cameleer.server.core.alerting.*;
+import io.cameleer.server.core.alerting.*;
-import com.cameleer.server.core.outbound.OutboundConnectionRepository;
+import io.cameleer.server.core.outbound.OutboundConnectionRepository;
-import com.cameleer.server.core.runtime.Environment;
+import io.cameleer.server.core.runtime.Environment;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Qualifier;
@@ -23,7 +23,7 @@ import java.util.Map;
  * Claim-polling outbox loop that dispatches {@link AlertNotification} records.
  * <p>
  * On each tick, claims a batch of due notifications, resolves the backing
- * {@link AlertInstance} and {@link com.cameleer.server.core.outbound.OutboundConnection},
+ * {@link AlertInstance} and {@link io.cameleer.server.core.outbound.OutboundConnection},
  * checks active silences, delegates to {@link WebhookDispatcher}, and persists the outcome.
  * <p>
  * Retry backoff: {@code retryAfter × attempts} (30 s, 60 s, 90 s, …).

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/SilenceMatcherService.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.SilenceMatcher;
+import io.cameleer.server.core.alerting.SilenceMatcher;
 import org.springframework.stereotype.Component;
 
 /**

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/notify/WebhookDispatcher.java

@@ -1,16 +1,16 @@
-package com.cameleer.server.app.alerting.notify;
+package io.cameleer.server.app.alerting.notify;
 
-import com.cameleer.server.app.alerting.config.AlertingProperties;
+import io.cameleer.server.app.alerting.config.AlertingProperties;
-import com.cameleer.server.app.outbound.crypto.SecretCipher;
+import io.cameleer.server.app.outbound.crypto.SecretCipher;
-import com.cameleer.server.core.alerting.AlertInstance;
+import io.cameleer.server.core.alerting.AlertInstance;
-import com.cameleer.server.core.alerting.AlertNotification;
+import io.cameleer.server.core.alerting.AlertNotification;
-import com.cameleer.server.core.alerting.AlertRule;
+import io.cameleer.server.core.alerting.AlertRule;
-import com.cameleer.server.core.alerting.NotificationStatus;
+import io.cameleer.server.core.alerting.NotificationStatus;
-import com.cameleer.server.core.alerting.WebhookBinding;
+import io.cameleer.server.core.alerting.WebhookBinding;
-import com.cameleer.server.core.http.OutboundHttpClientFactory;
+import io.cameleer.server.core.http.OutboundHttpClientFactory;
-import com.cameleer.server.core.http.OutboundHttpRequestContext;
+import io.cameleer.server.core.http.OutboundHttpRequestContext;
-import com.cameleer.server.core.outbound.OutboundConnection;
+import io.cameleer.server.core.outbound.OutboundConnection;
-import com.cameleer.server.core.outbound.OutboundMethod;
+import io.cameleer.server.core.outbound.OutboundMethod;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.apache.hc.client5.http.classic.methods.HttpPatch;
 import org.apache.hc.client5.http.classic.methods.HttpPost;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/retention/AlertingRetentionJob.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.retention;
+package io.cameleer.server.app.alerting.retention;
 
-import com.cameleer.server.app.alerting.config.AlertingProperties;
+import io.cameleer.server.app.alerting.config.AlertingProperties;
-import com.cameleer.server.core.alerting.AlertInstanceRepository;
+import io.cameleer.server.core.alerting.AlertInstanceRepository;
-import com.cameleer.server.core.alerting.AlertNotificationRepository;
+import io.cameleer.server.core.alerting.AlertNotificationRepository;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;
@@ -15,9 +15,9 @@ import java.time.temporal.ChronoUnit;
 /**
  * Nightly retention job for alerting data.
  * <p>
- * Deletes RESOLVED {@link com.cameleer.server.core.alerting.AlertInstance} rows older than
+ * Deletes RESOLVED {@link io.cameleer.server.core.alerting.AlertInstance} rows older than
  * {@code cameleer.server.alerting.eventRetentionDays} and DELIVERED/FAILED
- * {@link com.cameleer.server.core.alerting.AlertNotification} rows older than
+ * {@link io.cameleer.server.core.alerting.AlertNotification} rows older than
  * {@code cameleer.server.alerting.notificationRetentionDays}.
  * <p>
  * Duplicate runs across replicas are tolerable — the DELETEs are idempotent.

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepository.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.storage;
+package io.cameleer.server.app.alerting.storage;
 
-import com.cameleer.server.core.alerting.*;
+import io.cameleer.server.core.alerting.*;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.slf4j.Logger;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/storage/PostgresAlertNotificationRepository.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.alerting.storage;
+package io.cameleer.server.app.alerting.storage;
 
-import com.cameleer.server.core.alerting.AlertNotification;
+import io.cameleer.server.core.alerting.AlertNotification;
-import com.cameleer.server.core.alerting.AlertNotificationRepository;
+import io.cameleer.server.core.alerting.AlertNotificationRepository;
-import com.cameleer.server.core.alerting.NotificationStatus;
+import io.cameleer.server.core.alerting.NotificationStatus;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.jdbc.core.JdbcTemplate;

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/storage/PostgresAlertRuleRepository.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.alerting.storage;
+package io.cameleer.server.app.alerting.storage;
 
-import com.cameleer.server.core.alerting.*;
+import io.cameleer.server.core.alerting.*;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.jdbc.core.JdbcTemplate;
@@ -113,6 +113,12 @@ public class PostgresAlertRuleRepository implements AlertRuleRepository {
         jdbc.update("DELETE FROM alert_rules WHERE id = ?", id);
     }
 
+    @Override
+    public long count() {
+        Long n = jdbc.queryForObject("SELECT COUNT(*) FROM alert_rules", Long.class);
+        return n == null ? 0L : n;
+    }
+
     @Override
     public List<AlertRule> claimDueRules(String instanceId, int batchSize, int claimTtlSeconds) {
         String sql = """

cameleer-server-app/src/main/java/io/cameleer/server/app/alerting/storage/PostgresAlertSilenceRepository.java

@@ -1,9 +1,9 @@
-package com.cameleer.server.app.alerting.storage;
+package io.cameleer.server.app.alerting.storage;
 
-import com.cameleer.server.core.alerting.AlertSilence;
+import io.cameleer.server.core.alerting.AlertSilence;
-import com.cameleer.server.core.alerting.AlertSilenceRepository;
+import io.cameleer.server.core.alerting.AlertSilenceRepository;
-import com.cameleer.server.core.alerting.AlertSeverity;
+import io.cameleer.server.core.alerting.AlertSeverity;
-import com.cameleer.server.core.alerting.SilenceMatcher;
+import io.cameleer.server.core.alerting.SilenceMatcher;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.jdbc.core.RowMapper;

cameleer-server-app/src/main/java/io/cameleer/server/app/analytics/UsageFlushScheduler.java

@@ -1,6 +1,6 @@
-package com.cameleer.server.app.analytics;
+package io.cameleer.server.app.analytics;
 
-import com.cameleer.server.app.storage.ClickHouseUsageTracker;
+import io.cameleer.server.app.storage.ClickHouseUsageTracker;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;

cameleer-server-app/src/main/java/io/cameleer/server/app/analytics/UsageTrackingInterceptor.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app.analytics;
+package io.cameleer.server.app.analytics;
 
-import com.cameleer.server.core.analytics.UsageEvent;
+import io.cameleer.server.core.analytics.UsageEvent;
-import com.cameleer.server.core.analytics.UsageTracker;
+import io.cameleer.server.core.analytics.UsageTracker;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import org.springframework.security.core.Authentication;

cameleer-server-app/src/main/java/io/cameleer/server/app/config/AgentRegistryBeanConfig.java

@@ -1,9 +1,9 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
-import com.cameleer.server.core.agent.AgentEventRepository;
+import io.cameleer.server.core.agent.AgentEventRepository;
-import com.cameleer.server.core.agent.AgentEventService;
+import io.cameleer.server.core.agent.AgentEventService;
-import com.cameleer.server.core.agent.AgentRegistryService;
+import io.cameleer.server.core.agent.AgentRegistryService;
-import com.cameleer.server.core.agent.RouteStateRegistry;
+import io.cameleer.server.core.agent.RouteStateRegistry;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -17,11 +17,13 @@ import org.springframework.context.annotation.Configuration;
 public class AgentRegistryBeanConfig {
 
     @Bean
-    public AgentRegistryService agentRegistryService(AgentRegistryConfig config) {
+    public AgentRegistryService agentRegistryService(AgentRegistryConfig config,
+                                                      io.cameleer.server.app.license.LicenseEnforcer enforcer) {
         return new AgentRegistryService(
                 config.getStaleThresholdMs(),
                 config.getDeadThresholdMs(),
-                config.getCommandExpiryMs()
+                config.getCommandExpiryMs(),
+                current -> enforcer.assertWithinCap("max_agents", current, 1)
         );
     }
 

cameleer-server-app/src/main/java/io/cameleer/server/app/config/AgentRegistryConfig.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/config/ClickHouseConfig.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import com.zaxxer.hikari.HikariDataSource;
 import org.springframework.beans.factory.annotation.Qualifier;

cameleer-server-app/src/main/java/io/cameleer/server/app/config/ClickHouseProperties.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/config/ClickHouseSchemaInitializer.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

cameleer-server-app/src/main/java/io/cameleer/server/app/config/DiagramBeanConfig.java

@@ -1,7 +1,7 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
-import com.cameleer.server.app.diagram.ElkDiagramRenderer;
+import io.cameleer.server.app.diagram.ElkDiagramRenderer;
-import com.cameleer.server.core.diagram.DiagramRenderer;
+import io.cameleer.server.core.diagram.DiagramRenderer;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/config/IngestionBeanConfig.java

@@ -1,10 +1,10 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
-import com.cameleer.server.core.ingestion.BufferedLogEntry;
+import io.cameleer.server.core.ingestion.BufferedLogEntry;
-import com.cameleer.server.core.ingestion.ChunkAccumulator;
+import io.cameleer.server.core.ingestion.ChunkAccumulator;
-import com.cameleer.server.core.ingestion.MergedExecution;
+import io.cameleer.server.core.ingestion.MergedExecution;
-import com.cameleer.server.core.ingestion.WriteBuffer;
+import io.cameleer.server.core.ingestion.WriteBuffer;
-import com.cameleer.server.core.storage.model.MetricsSnapshot;
+import io.cameleer.server.core.storage.model.MetricsSnapshot;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -12,7 +12,7 @@ import org.springframework.context.annotation.Configuration;
  * Creates write buffer beans for the ingestion pipeline.
  * <p>
  * Each {@link WriteBuffer} instance is shared between the
- * {@link com.cameleer.server.core.ingestion.IngestionService} (producer side)
+ * {@link io.cameleer.server.core.ingestion.IngestionService} (producer side)
  * and the flush scheduler (consumer side).
  */
 @Configuration

cameleer-server-app/src/main/java/io/cameleer/server/app/config/IngestionConfig.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 

cameleer-server-app/src/main/java/io/cameleer/server/app/config/LicenseBeanConfig.java

@@ -0,0 +1,130 @@
+package io.cameleer.server.app.config;
+
+import io.cameleer.server.app.license.LicenseRepository;
+import io.cameleer.server.app.license.LicenseService;
+import io.cameleer.server.core.admin.AuditService;
+import io.cameleer.server.core.license.LicenseGate;
+import io.cameleer.license.LicenseInfo;
+import io.cameleer.license.LicenseValidator;
+import jakarta.annotation.PostConstruct;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyPair;
+import java.security.KeyPairGenerator;
+import java.util.Base64;
+import java.util.Optional;
+
+/**
+ * License bean topology (4 beans, in dependency order):
+ *
+ * <ol>
+ *   <li>{@link LicenseGate} — always present, mutated by {@link LicenseService}.</li>
+ *   <li>{@link LicenseValidator} — always present. When no public key is configured, returns an
+ *       always-failing override so any loaded token routes through {@code install()} and is
+ *       audited as INVALID rather than silently ignored.</li>
+ *   <li>{@link LicenseService} — single mediation point for install / replace / revalidate;
+ *       audits + persists + publishes {@code LicenseChangedEvent}.</li>
+ *   <li>{@link LicenseBootLoader} — {@code @PostConstruct} drives {@code loadInitial} after the
+ *       Spring context is ready. Resolution order: env var &gt; license file &gt; persisted DB row.</li>
+ * </ol>
+ */
+@Configuration
+public class LicenseBeanConfig {
+
+    private static final Logger log = LoggerFactory.getLogger(LicenseBeanConfig.class);
+
+    @Value("${cameleer.server.tenant.id:default}")
+    private String tenantId;
+
+    @Value("${cameleer.server.license.token:}")
+    private String licenseToken;
+
+    @Value("${cameleer.server.license.file:}")
+    private String licenseFile;
+
+    @Value("${cameleer.server.license.publickey:}")
+    private String licensePublicKey;
+
+    @Bean
+    public LicenseGate licenseGate() {
+        return new LicenseGate();
+    }
+
+    @Bean
+    public LicenseValidator licenseValidator() {
+        if (licensePublicKey == null || licensePublicKey.isBlank()) {
+            log.warn("CAMELEER_SERVER_LICENSE_PUBLICKEY not set — all licenses will be rejected as INVALID");
+            // Generate a throwaway, structurally-valid Ed25519 keypair just to satisfy the
+            // parent constructor's X.509 SubjectPublicKeyInfo decode + Ed25519 point validation.
+            // The overridden validate(...) always throws, so the dummy key is never used to
+            // verify anything — it only exists so the bean is constructable in misconfigured
+            // installs and any token that is loaded routes to INVALID via install()'s catch.
+            try {
+                KeyPair throwaway = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();
+                String dummyPub = Base64.getEncoder().encodeToString(throwaway.getPublic().getEncoded());
+                return new LicenseValidator(dummyPub, tenantId) {
+                    @Override
+                    public LicenseInfo validate(String token) {
+                        throw new IllegalStateException("license public key not configured");
+                    }
+                };
+            } catch (Exception e) {
+                throw new IllegalStateException("Failed to construct fallback license validator", e);
+            }
+        }
+        return new LicenseValidator(licensePublicKey, tenantId);
+    }
+
+    @Bean
+    public LicenseService licenseService(LicenseRepository repo,
+                                         LicenseGate gate,
+                                         LicenseValidator validator,
+                                         AuditService audit,
+                                         ApplicationEventPublisher events) {
+        return new LicenseService(tenantId, repo, gate, validator, audit, events);
+    }
+
+    @Bean
+    public LicenseBootLoader licenseBootLoader(LicenseService svc) {
+        return new LicenseBootLoader(svc, licenseToken, licenseFile);
+    }
+
+    /**
+     * {@code @PostConstruct} bridge that converts env-var/file values into the
+     * {@code Optional<String>} pair {@link LicenseService#loadInitial} expects, so
+     * env-var, file, and DB paths share the same audit + event-publish code path.
+     */
+    public static class LicenseBootLoader {
+        private final LicenseService svc;
+        private final String envToken;
+        private final String filePath;
+
+        public LicenseBootLoader(LicenseService svc, String envToken, String filePath) {
+            this.svc = svc;
+            this.envToken = envToken;
+            this.filePath = filePath;
+        }
+
+        @PostConstruct
+        public void load() {
+            Optional<String> env = (envToken != null && !envToken.isBlank())
+                    ? Optional.of(envToken) : Optional.empty();
+            Optional<String> file = Optional.empty();
+            if (filePath != null && !filePath.isBlank()) {
+                try {
+                    file = Optional.of(Files.readString(Path.of(filePath)).trim());
+                } catch (Exception e) {
+                    log.warn("Failed to read license file {}: {}", filePath, e.getMessage());
+                }
+            }
+            svc.loadInitial(env, file);
+        }
+    }
+}

cameleer-server-app/src/main/java/io/cameleer/server/app/config/OpenApiConfig.java

@@ -1,4 +1,4 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
 import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
 import io.swagger.v3.oas.annotations.security.SecurityScheme;

cameleer-server-app/src/main/java/io/cameleer/server/app/config/RbacBeanConfig.java

@@ -1,8 +1,8 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
-import com.cameleer.server.app.storage.PostgresClaimMappingRepository;
+import io.cameleer.server.app.storage.PostgresClaimMappingRepository;
-import com.cameleer.server.core.rbac.ClaimMappingRepository;
+import io.cameleer.server.core.rbac.ClaimMappingRepository;
-import com.cameleer.server.core.rbac.ClaimMappingService;
+import io.cameleer.server.core.rbac.ClaimMappingService;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.jdbc.core.JdbcTemplate;

cameleer-server-app/src/main/java/io/cameleer/server/app/config/RuntimeBeanConfig.java

@@ -1,16 +1,19 @@
-package com.cameleer.server.app.config;
+package io.cameleer.server.app.config;
 
-import com.cameleer.server.app.storage.PostgresAppRepository;
+import io.cameleer.server.app.storage.FilesystemArtifactStore;
-import com.cameleer.server.app.storage.PostgresAppVersionRepository;
+import io.cameleer.server.app.storage.PostgresAppRepository;
-import com.cameleer.server.app.storage.PostgresDeploymentRepository;
+import io.cameleer.server.app.storage.PostgresAppVersionRepository;
-import com.cameleer.server.app.storage.PostgresEnvironmentRepository;
+import io.cameleer.server.app.storage.PostgresDeploymentRepository;
-import com.cameleer.server.core.runtime.AppRepository;
+import io.cameleer.server.app.storage.PostgresEnvironmentRepository;
-import com.cameleer.server.core.runtime.AppService;
+import io.cameleer.server.core.runtime.AppRepository;
-import com.cameleer.server.core.runtime.AppVersionRepository;
+import io.cameleer.server.core.runtime.AppService;
-import com.cameleer.server.core.runtime.DeploymentRepository;
+import io.cameleer.server.core.runtime.AppVersionRepository;
-import com.cameleer.server.core.runtime.DeploymentService;
+import io.cameleer.server.core.runtime.DeploymentRepository;
-import com.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.DeploymentService;
-import com.cameleer.server.core.runtime.EnvironmentService;
+import io.cameleer.server.core.runtime.DirtyStateCalculator;
+import io.cameleer.server.core.runtime.EnvironmentRepository;
+import io.cameleer.server.core.runtime.EnvironmentService;
+import io.cameleer.server.core.storage.ArtifactStore;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
@@ -49,14 +52,24 @@ public class RuntimeBeanConfig {
     }
 
     @Bean
-    public EnvironmentService environmentService(EnvironmentRepository repo) {
+    public EnvironmentService environmentService(EnvironmentRepository repo,
-        return new EnvironmentService(repo);
+                                                 io.cameleer.server.app.license.LicenseEnforcer enforcer) {
+        return new EnvironmentService(repo, current ->
+                enforcer.assertWithinCap("max_environments", current, 1));
+    }
+
+    @Bean
+    public ArtifactStore artifactStore(@Value("${cameleer.server.runtime.jarstoragepath:/data/jars}") String jarStoragePath) {
+        return new FilesystemArtifactStore(jarStoragePath);
     }
 
     @Bean
     public AppService appService(AppRepository appRepo, AppVersionRepository versionRepo,
-                                  @Value("${cameleer.server.runtime.jarstoragepath:/data/jars}") String jarStoragePath) {
+                                  ArtifactStore artifactStore,
-        return new AppService(appRepo, versionRepo, jarStoragePath);
+                                  @Value("${cameleer.server.tenant.id:default}") String tenantId,
+                                  io.cameleer.server.app.license.LicenseEnforcer enforcer) {
+        return new AppService(appRepo, versionRepo, artifactStore, tenantId,
+                current -> enforcer.assertWithinCap("max_apps", current, 1));
     }
 
     @Bean
@@ -64,6 +77,11 @@ public class RuntimeBeanConfig {
         return new DeploymentService(deployRepo, appService, envService);
     }
 
+    @Bean
+    public DirtyStateCalculator dirtyStateCalculator(ObjectMapper objectMapper) {
+        return new DirtyStateCalculator(objectMapper);
+    }
+
     @Bean(name = "deploymentTaskExecutor")
     public Executor deploymentTaskExecutor() {
         ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();