Update claude and tickets

tickets/055-ottyl-reserved-params-in-dashboards.md

@@ -0,0 +1,77 @@
+# 055 — Make `ottyl_*` reserved params usable in dashboard (PromQL) queries, not just filters
+
+## Summary
+
+Three reserved params exist, all hardcoded in the filter compiler:
+`ottyl_seq` (ingest sequence number), `ottyl_ts` (ingest timestamp,
+supports relative/absolute values), and `ottyl_fmt` (auto-detected
+`json`/`logfmt`/`none`) — defined at `src/engine.rs:773-775, 795, 806, 824`,
+grammar comments at `src/filter_parser.pest:7-9`, docs at
+`webapp/src/components/Docs.tsx:105-106, 375` ("reserved metric names
+present on every log line, so they're always filterable without
+declaring anything"). Alert conditions restrict to the same three plus
+`regex()`/`json[field]` (`src/alerts.rs:3, 199-225`).
+
+These already work end-to-end for the filter/query bar syntax used by
+`GET /api/logs`, `GET /api/timeline`, and alert conditions — that part of
+"accessible parameters for queries" is true today. What's missing is
+dashboards: PromQL-style panel queries (`src/promql.rs`,
+`evaluate_promql` in `src/engine.rs:1562-1601`) have no special case for
+`ottyl_*` anywhere. A PromQL query resolves `metric_name` via
+`bucket_values(index, &parsed.metric_name)`
+(`src/engine.rs`, called from `evaluate_promql`), which only returns data
+for names backed by a `DataValue::MetricDeclaration` and bucket entries
+created through `POST /api/metrics`. `ottyl_*` values are computed
+line-locally at filter-compile time and never written into declared-
+metric buckets, so `sum(ottyl_seq)` or similar in a dashboard panel would
+silently return an empty series rather than real data.
+
+Separately, `ottyl_*` never appear in `GET /api/params`
+(`src/api.rs:281-287` → `EngineQuery::ParamDeclarations` →
+`param_declarations_range`, `src/engine.rs:1340-1355`), since that only
+lists explicit `ParamDeclaration` index entries and `ottyl_*` never
+create one. `FilterBar.tsx` (`webapp/src/components/FilterBar.tsx:36-41`)
+has no autocomplete/suggestion list at all today (plain text input), so
+there's nothing currently excluding them from UI suggestions either —
+but if param suggestions are ever added, this gap should be kept in mind.
+
+## Scope
+
+- Add a special case in `evaluate_promql`/`src/promql.rs` (analogous to
+  the filter compiler's handling at `src/engine.rs:773-775`) that
+  synthesizes a virtual bucket series for `ottyl_seq`/`ottyl_ts`/
+  `ottyl_fmt` metric names from the ingested-log index, instead of
+  requiring a `MetricDeclaration`. Decide and document in the PR how
+  `ottyl_fmt`'s categorical string values map onto a numeric time
+  series (e.g. count-by-value, or reject it from PromQL numeric
+  aggregation with a clear error, since `ottyl_seq`/`ottyl_ts` are
+  naturally numeric but `ottyl_fmt` is not).
+- Decide whether `ottyl_*` should appear in `GET /api/params` (or a
+  parallel listing) so dashboard panel builders in the webapp can
+  discover them without prior knowledge of the reserved names; if yes,
+  extend `param_declarations_range` or add a small hardcoded merge at the
+  API layer rather than forcing them into the index as real
+  `ParamDeclaration` entries (they aren't user-declared and shouldn't be
+  deletable via ticket 051's/052's params-removal paths).
+- Update `README.md`/`Docs.tsx` to state whether `ottyl_*` is usable in
+  dashboard queries, once implemented (or explicitly document it as
+  filter-only, if the numeric/categorical mismatch above makes broad
+  PromQL support impractical for `ottyl_fmt`).
+
+## Acceptance criteria
+
+- A dashboard panel using a PromQL query over `ottyl_seq` or `ottyl_ts`
+  (e.g. `count(ottyl_seq)` or a rate over `ottyl_ts`) returns real data
+  from ingested logs, verified with a seeded fixture.
+- The behavior for `ottyl_fmt` in a PromQL query is either implemented
+  (with a stated value-to-series mapping) or explicitly rejected with a
+  clear, documented error — not a silent empty result.
+- `GET /api/params` behavior for `ottyl_*` is decided and documented;
+  if included, they're clearly marked as reserved/non-deletable rather
+  than indistinguishable from user-declared params.
+
+## Depends on
+
+None (independent of the params-removal tickets, but note the
+non-deletable requirement above if `ottyl_*` end up listed alongside
+regular params).