From d40833b96aa9ca25f65bfa107c753cc528a590bb Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Fri, 17 Apr 2026 15:43:25 +0200 Subject: [PATCH] docs(rules): refresh for insert_id UUID cursor + AgentEventPage - LogQueryController: note response shape, sort param, and that the cursor tiebreak is the insert_id UUID column (not exchange/instance) - AgentEventsController: cursor now carries insert_id UUID (was instanceId); order is (timestamp DESC, insert_id DESC) - core-classes: add AgentEventPage record; note that the non-paginated AgentEventRepository.query(...) path has been removed - core-classes: note LogSearchRequest.sources/levels are now List with multi-value OR semantics Keeps the rule files in sync with the cursor-pagination + multi-select filter work on main. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/rules/app-classes.md | 4 ++-- .claude/rules/core-classes.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.claude/rules/app-classes.md b/.claude/rules/app-classes.md index bf48f90b..ef0084a4 100644 --- a/.claude/rules/app-classes.md +++ b/.claude/rules/app-classes.md @@ -43,11 +43,11 @@ ClickHouse is shared across tenants. Every ClickHouse query must filter by `tena - `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. - `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`. -- `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). Cursor-paginated. +- `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`. - `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, instance_id ASC)`; cursor is base64url of `"{timestampIso}|{instanceId}"`). +- `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). diff --git a/.claude/rules/core-classes.md b/.claude/rules/core-classes.md index 433f9b51..3417e841 100644 --- a/.claude/rules/core-classes.md +++ b/.claude/rules/core-classes.md @@ -17,7 +17,8 @@ paths: - `CommandType` — enum for command types (config-update, deep-trace, replay, route-control, etc.) - `CommandStatus` — enum for command acknowledgement states - `CommandReply` — record: command execution result from agent -- `AgentEventRecord`, `AgentEventRepository` — event persistence +- `AgentEventRecord`, `AgentEventRepository` — event persistence. `AgentEventRepository.queryPage(...)` is cursor-paginated (`AgentEventPage{data, nextCursor, hasMore}`); the legacy non-paginated `query(...)` path is gone. +- `AgentEventPage` — record: `(List data, String nextCursor, boolean hasMore)` returned by `AgentEventRepository.queryPage` - `AgentEventListener` — callback interface for agent events - `RouteStateRegistry` — tracks per-agent route states @@ -47,7 +48,7 @@ paths: - `SearchRequest` / `SearchResult` — search DTOs - `ExecutionStats`, `ExecutionSummary` — stats aggregation records - `StatsTimeseries`, `TopError` — timeseries and error DTOs -- `LogSearchRequest` / `LogSearchResponse` — log search DTOs +- `LogSearchRequest` / `LogSearchResponse` — log search DTOs. `LogSearchRequest.sources` / `levels` are `List` (null-normalized, multi-value OR); `cursor` + `limit` + `sort` drive keyset pagination. Response carries `nextCursor` + `hasMore` + per-level `levelCounts`. ## storage/ — Storage abstractions