Merge branch 'worktree-agent-a63474e92b05425a5'

# Conflicts: # Cargo.lock # Cargo.toml
2026-09-05 12:46:45 +01:00
parent 5b1e2fd5af 22647620fa
commit 1d3bc0d0d6
28 changed files with 958 additions and 3 deletions
@@ -233,6 +233,27 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"

+[[package]]
+name = "directories"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16f5094c54661b38d03bd7e50df373292118db60b585c08a411c6d840017fe7d"
+dependencies = [
+ "dirs-sys",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users",
+ "windows-sys",
+]
+
 [[package]]
 name = "errno"
 version = "0.3.14"
@@ -243,6 +264,12 @@ dependencies = [
 "windows-sys",
 ]

+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.12"
@@ -297,6 +324,28 @@ dependencies = [
 "slab",
 ]

+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+]
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -448,6 +497,21 @@ version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"

+[[package]]
+name = "libredox"
+version = "0.1.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d8f1ea3f21fd3405dcaf6c9b5c1630af9afc422d9073ea39c5f6d6c772e08ed"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -523,6 +587,12 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"

+[[package]]
+name = "option-ext"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
+
 [[package]]
 name = "ottyl"
 version = "0.1.0"
@@ -530,12 +600,14 @@ dependencies = [
 "axum",
 "chrono",
 "clap",
+ "directories",
 "humantime",
 "pest",
 "pest_derive",
 "regex",
 "serde",
 "serde_json",
+ "tempfile",
 "tokio",
 "tower-http",
 ]
@@ -635,6 +707,12 @@ dependencies = [
 "proc-macro2",
 ]

+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -644,6 +722,17 @@ dependencies = [
 "bitflags",
 ]

+[[package]]
+name = "redox_users"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
+dependencies = [
+ "getrandom 0.2.17",
+ "libredox",
+ "thiserror",
+]
+
 [[package]]
 name = "regex"
 version = "1.13.1"
@@ -673,6 +762,19 @@ version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"

+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
 [[package]]
 name = "rustversion"
 version = "1.0.23"
@@ -829,6 +931,39 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"

+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+]
+
 [[package]]
 name = "tokio"
 version = "1.53.1"
@@ -15,3 +15,7 @@ pest = "2"
 pest_derive = "2"
 chrono = "0.4"
 humantime = "2"
+directories = "6.0.0"
+
+[dev-dependencies]
+tempfile = "3.27.0"
@@ -192,5 +192,10 @@ Example `node_id` for a cluster test or something.
 Then it may be possible to capture specific events of interest.
 There wouldn't be a relation between nodes, only the sequence of events determines relations in the sequence diagram.

+## Index allocation size
+
+It should be possible to see how much ram is being consumed by the program.
+What should happen if it reaches a limit?
+


@@ -1,5 +1,8 @@
+use std::sync::{Arc, Mutex};
+
 use crate::engine::{EngineHandle, EngineMessage, EngineQuery, EngineResponse};
 use crate::dto::{LogsParams, TimelineParams};
+use crate::settings::Settings;
 use axum::extract::{Query, State};
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Json};
@@ -8,13 +11,20 @@ use axum::Router;
 use tokio::sync::oneshot;
 use tower_http::services::{ServeDir, ServeFile};

+/// Shared, process-wide settings handle. Cheap to clone; lock is only held
+/// briefly since settings changes are rare (unlike the engine's hot path).
+pub type SettingsHandle = Arc<Mutex<Settings>>;
+
 #[derive(Clone)]
 struct ApiState {
    engine: EngineHandle,
+    // TODO(ticket 010/011): wire up settings/CSS/NavMenu endpoints using this.
+    #[allow(dead_code)]
+    settings: SettingsHandle,
 }

-pub fn router(engine: EngineHandle, static_dir: &str) -> Router {
-    let state = ApiState { engine };
+pub fn router(engine: EngineHandle, static_dir: &str, settings: SettingsHandle) -> Router {
+    let state = ApiState { engine, settings };
    let index_html = format!("{static_dir}/index.html");
    let static_service = ServeDir::new(static_dir).fallback(ServeFile::new(index_html));

@@ -7,12 +7,18 @@ mod filter_parser;
 mod index_key;
 mod ingest;
 mod metric_primitive;
+mod settings;
 mod timestamp;

+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+
 use clap::Parser;
 use tokio::net::TcpListener;
 use tokio::sync::mpsc;

+use settings::Settings;
+
 /// Observability dashboard from terminal output.
 #[derive(Parser, Debug)]
 struct Args {
@@ -23,17 +29,28 @@ struct Args {
    /// Directory containing the built webapp (index.html + assets).
    #[arg(long, default_value = "webapp/dist")]
    static_dir: String,
+
+    /// Path to the settings file. Defaults to a per-OS config location
+    /// (e.g. `~/.config/ottyl/settings.json` on Linux).
+    #[arg(long)]
+    settings_path: Option<PathBuf>,
 }

 #[tokio::main]
 async fn main() {
    let args = Args::parse();

+    let settings_path = args.settings_path.clone().unwrap_or_else(|| {
+        settings::default_settings_path()
+            .expect("could not determine a default settings path; pass --settings-path")
+    });
+    let settings = Arc::new(Mutex::new(Settings::load(&settings_path)));
+
    let (engine_tx, engine_rx) = mpsc::channel(1024);
    tokio::spawn(engine::run(engine_rx));
    tokio::spawn(ingest::run(engine_tx.clone()));

-    let app = api::router(engine_tx, &args.static_dir);
+    let app = api::router(engine_tx, &args.static_dir, settings);
    let listener = TcpListener::bind(("0.0.0.0", args.port))
        .await
        .expect("failed to bind listener");
@@ -47,3 +64,23 @@ async fn main() {
        .await
        .expect("server error");
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn settings_path_defaults_to_none() {
+        let args = Args::parse_from(["ottyl"]);
+        assert_eq!(args.settings_path, None);
+    }
+
+    #[test]
+    fn settings_path_flag_overrides_default() {
+        let args = Args::parse_from(["ottyl", "--settings-path", "/tmp/custom-settings.json"]);
+        assert_eq!(
+            args.settings_path,
+            Some(PathBuf::from("/tmp/custom-settings.json"))
+        );
+    }
+}
@@ -0,0 +1,199 @@
+//! Process-wide settings model: colour scheme, CSS entries, and profile
+//! pointers. There is exactly one `Settings` instance at runtime, loaded once
+//! on startup and persisted to disk whenever it changes (see `main.rs`).
+//!
+//! Persistence format is JSON (via `serde_json`, already a dependency) rather
+//! than TOML, to keep the dependency list minimal.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use directories::ProjectDirs;
+use serde::{Deserialize, Serialize};
+
+/// User's preferred colour scheme for the webapp.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum ColorScheme {
+    Light,
+    Dark,
+    #[default]
+    System,
+}
+
+/// A single CSS entry configured for the webapp: either content that ottyl
+/// stores itself ("imported") or a reference to an external path/URL that
+/// the webapp links to directly ("linked", and therefore not deletable via
+/// the settings API since ottyl doesn't own it).
+///
+/// Ticket 010 builds the CSS import/link HTTP API around this shape.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+pub enum CssEntry {
+    Imported { id: String, filename: String },
+    Linked { path_or_url: String },
+}
+
+/// Placeholder shape for profile management (ticket 009 builds CRUD on top
+/// of this). Profiles are expected to live as individual files under a
+/// dedicated directory; this struct only tracks known profile names and
+/// which one is currently active.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct Profiles {
+    /// Names of known profiles. Ticket 009 owns creating/loading the actual
+    /// profile files.
+    pub names: Vec<String>,
+    /// Name of the currently active profile, if any.
+    pub active_profile: Option<String>,
+    /// Directory (relative to the settings file's directory, or absolute)
+    /// where individual profile files are expected to live.
+    pub profiles_dir: String,
+}
+
+/// The single, process-wide settings instance.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Settings {
+    pub color_scheme: ColorScheme,
+    pub css_entries: Vec<CssEntry>,
+    pub profiles: Profiles,
+}
+
+impl Default for Settings {
+    fn default() -> Self {
+        Settings {
+            color_scheme: ColorScheme::default(),
+            css_entries: Vec::new(),
+            profiles: Profiles {
+                names: Vec::new(),
+                active_profile: None,
+                profiles_dir: "profiles".to_string(),
+            },
+        }
+    }
+}
+
+/// Computes the default settings file path using OS-conventional config
+/// directories: `<config_dir>/settings.json`, where `config_dir` comes from
+/// `directories::ProjectDirs::from("", "", "ottyl")`.
+///
+/// Returns `None` if no valid config directory could be determined for the
+/// current OS/user (this mirrors `ProjectDirs::from`'s own fallibility).
+pub fn default_settings_path() -> Option<PathBuf> {
+    ProjectDirs::from("", "", "ottyl").map(|dirs| dirs.config_dir().join("settings.json"))
+}
+
+impl Settings {
+    /// Loads settings from `path`. If the file doesn't exist yet, a default
+    /// `Settings` is created, persisted to `path`, and returned.
+    ///
+    /// Any I/O or parse error while reading an existing file is treated as
+    /// non-fatal: it is logged to stderr and a default `Settings` is
+    /// returned (without overwriting the unreadable file).
+    pub fn load(path: &Path) -> Settings {
+        match fs::read_to_string(path) {
+            Ok(contents) => match serde_json::from_str(&contents) {
+                Ok(settings) => settings,
+                Err(err) => {
+                    eprintln!(
+                        "warning: failed to parse settings file at {}: {err}; using defaults",
+                        path.display()
+                    );
+                    Settings::default()
+                }
+            },
+            Err(err) if err.kind() == io::ErrorKind::NotFound => {
+                let settings = Settings::default();
+                if let Err(save_err) = settings.save(path) {
+                    eprintln!(
+                        "warning: failed to create default settings file at {}: {save_err}",
+                        path.display()
+                    );
+                }
+                settings
+            }
+            Err(err) => {
+                eprintln!(
+                    "warning: failed to read settings file at {}: {err}; using defaults",
+                    path.display()
+                );
+                Settings::default()
+            }
+        }
+    }
+
+    /// Persists these settings to `path` as pretty-printed JSON, creating
+    /// any missing parent directories first.
+    pub fn save(&self, path: &Path) -> io::Result<()> {
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let contents = serde_json::to_string_pretty(self)
+            .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
+        fs::write(path, contents)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_settings_path_ends_with_settings_json() {
+        // We can't assert the exact OS path here without touching real
+        // config dirs, but we can verify the path-computation logic shapes
+        // it as expected.
+        if let Some(path) = default_settings_path() {
+            assert_eq!(path.file_name().unwrap(), "settings.json");
+            assert!(path.parent().is_some());
+        }
+    }
+
+    #[test]
+    fn load_creates_default_when_missing() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("nested").join("settings.json");
+        assert!(!path.exists());
+
+        let settings = Settings::load(&path);
+        assert_eq!(settings, Settings::default());
+        assert!(path.exists(), "load() should persist a default file");
+
+        let reloaded = Settings::load(&path);
+        assert_eq!(reloaded, settings);
+    }
+
+    #[test]
+    fn round_trips_through_save_and_load() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Settings::default();
+        settings.color_scheme = ColorScheme::Dark;
+        settings.css_entries.push(CssEntry::Imported {
+            id: "abc123".to_string(),
+            filename: "theme.css".to_string(),
+        });
+        settings.css_entries.push(CssEntry::Linked {
+            path_or_url: "https://example.com/style.css".to_string(),
+        });
+        settings.profiles.names.push("default".to_string());
+        settings.profiles.active_profile = Some("default".to_string());
+
+        settings.save(&path).unwrap();
+
+        let loaded = Settings::load(&path);
+        assert_eq!(loaded, settings);
+    }
+
+    #[test]
+    fn save_creates_parent_directories() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("a").join("b").join("settings.json");
+
+        let settings = Settings::default();
+        settings.save(&path).unwrap();
+
+        assert!(path.exists());
+    }
+}
@@ -0,0 +1,35 @@
+# 001 — Param declarations
+
+## Summary
+
+Implement the `ParamDeclaration` slice of the primary index: users can declare how a
+named parameter is derived from a log line (e.g. deriving a timestamp different from
+the ingestion timestamp, or a log level), and the engine stores/serves those
+declarations.
+
+## Scope
+
+- `IndexKey::ParamDeclaration { name }` and a matching `DataValue` variant for the
+  declaration body (a regex against the raw log text, plus how the capture maps to a
+  `MetricPrimitive` — reuse `RegexToMetricPrimitiveMatcher` / `MetricPrimitiveKind`
+  from `data_value.rs`, which already exist but are unused).
+- Engine message(s) to add/list/remove a param declaration.
+- Validate declared regexes at declaration time (reject invalid regex / unknown
+  primitive kind up front rather than failing per-log later).
+- No derivation/backfill against existing logs yet — that's
+  [002](002-metric-declarations.md) / [003](003-metric-bucket-derivation.md), since
+  metrics are what actually get indexed into buckets. This ticket is just the
+  declaration storage + validation.
+
+## Acceptance criteria
+
+- Declaring a param with a valid regex + capture group succeeds and is retrievable.
+- Declaring a param with an invalid regex or referencing a non-existent capture group
+  is rejected with a clear error, not silently stored.
+- Declarations sit in their own contiguous range of the BTreeMap
+  (`ParamDeclaration` between `LogParamSplit` and `ParamMetricSplit`), per the
+  `IndexKey` ordering in the README.
+
+## Depends on
+
+None — this is foundational.
@@ -0,0 +1,35 @@
+# 002 — Metric declarations
+
+## Summary
+
+Implement the `MetricDeclaration` slice of the index: a language/API for declaring a
+metric — a regex that matches a log message plus params extracted from it — so that
+matching logs can later be bucketed ([003](003-metric-bucket-derivation.md)).
+
+## Scope
+
+- `IndexKey::MetricDeclaration { name }` paired with `DataValue::MetricDeclaration`
+  (already sketched in `data_value.rs`: `message_match_regex` +
+  `Vec<RegexToMetricPrimitiveMatcher>`).
+- Engine message(s) to add/list/remove a metric declaration.
+- A metric declaration's params may reference params already declared via
+  [001](001-param-declarations.md) (e.g. label a bucket by an existing param) in
+  addition to inline capture groups on the metric's own regex — decide and document
+  which is supported for v1 (README implies inline capture-group derivation is the
+  primary mechanism: "buckets and parameters can be derived" from the metric
+  declaration itself).
+- Validate the regex and capture-group → primitive-kind mapping at declaration time,
+  same as param declarations.
+
+## Acceptance criteria
+
+- Declaring a metric with a valid regex + param matchers succeeds and is retrievable.
+- Invalid regex, or a matcher referencing a capture group the regex doesn't have, is
+  rejected at declaration time.
+- Declarations sit in their own contiguous range of the BTreeMap
+  (`MetricDeclaration` between `ParamMetricSplit` and `MetricBucketSplit`).
+
+## Depends on
+
+- [001 — Param declarations](001-param-declarations.md) (shares matcher/primitive
+  validation code and the "derive a value from a regex capture" concept).
@@ -0,0 +1,37 @@
+# 003 — Metric bucket derivation
+
+## Summary
+
+Apply metric declarations to log lines and populate `IndexKey::Bucket` /
+`DataValue::BucketValue` entries, both retroactively (backfill already-ingested logs
+when a metric is declared) and going forward (index each new log against all current
+metric declarations as it's ingested).
+
+## Scope
+
+- On `MetricDeclaration` add: scan the existing `IngestedLog` range, run the metric's
+  regex against each log's text, and for each match compute the labeled `Bucket` key
+  (`metric_name` + `labels: BTreeMap<String, MetricPrimitive>`) and append
+  `(sequence, timestamp, value)` to that bucket's `BucketValue`.
+- On new log ingest: run all currently-declared metrics' regexes against the line and
+  update buckets incrementally, same as backfill.
+- Decide bucket cardinality behavior: a single log line can match multiple metrics: it
+  should update all matching buckets. Document how differing label sets from the same
+  metric become distinct `Bucket` keys (labels are part of the key, so this falls out
+  naturally from `BTreeMap` — just needs the insert-or-append logic).
+- This is the piece that makes `MetricPrimitive`, `DataValue::BucketValue`, and the
+  `Bucket` index range (currently defined but never populated) actually load-bearing.
+
+## Acceptance criteria
+
+- Declaring a metric against a log stream that already has matching lines populates
+  buckets for those lines without needing new input.
+- Ingesting a new log line after metrics are declared updates the relevant buckets
+  live.
+- A log line matching zero metrics doesn't touch the bucket range.
+- Bucket values preserve insertion order / are queryable by sequence and timestamp
+  range (needed by [004](004-metrics-api.md) and dashboards).
+
+## Depends on
+
+- [002 — Metric declarations](002-metric-declarations.md)
@@ -0,0 +1,31 @@
+# 004 — Metrics API
+
+## Summary
+
+Expose param/metric declarations and bucket data over HTTP so the frontend (and the
+filter/dashboard query engines) can declare metrics and read their values.
+
+## Scope
+
+- `POST /api/params` — declare a param ([001](001-param-declarations.md)).
+- `POST /api/metrics` — declare a metric ([002](002-metric-declarations.md)).
+- `GET /api/metrics` — list declared metrics (+ their declared params/labels).
+- `GET /api/metrics/:name` — query bucket values for a metric, filtered by label
+  selector and time/sequence range, mirroring the existing `LogsParams`/
+  `TimelineParams` pattern in `dto.rs`.
+- Follow the existing engine architecture: new `EngineQuery`/`EngineMessage` variants,
+  handled in `engine.rs`'s single-owner loop, DTOs added to `dto.rs`, routes added to
+  `api.rs`'s router — no new locking or shared state.
+
+## Acceptance criteria
+
+- Declaring a param/metric via the API round-trips through to engine state and shows
+  up in `GET /api/metrics`.
+- Querying a metric's bucket values supports the same start/end and limit-style
+  params as the existing logs/timeline endpoints.
+- Bad declarations (invalid regex etc.) return a 4xx with a useful error body, not a
+  500 or silent no-op.
+
+## Depends on
+
+- [003 — Metric bucket derivation](003-metric-bucket-derivation.md)
@@ -0,0 +1,37 @@
+# 005 — FilterBar query language (pest grammar)
+
+## Summary
+
+Build the syntax-aware search language described in the README's FilterBar section,
+using `pest`, supporting regex searches and metric comparisons combined with
+boolean operators.
+
+## Scope
+
+- Add `pest` + `pest_derive` dependencies.
+- Grammar covering:
+  - `regex("...")` — raw-text regex search over log lines.
+  - `metric_name[param] <op> value` comparisons (`<`, `>`, `<=`, `>=`, `==`, `!=`) —
+    `metric_name[param]<5` per the README example.
+  - `sequence` and `timestamp` as reserved metric names usable the same way
+    (`sequence<5`, `timestamp>12:00`).
+  - Boolean combinators `and` / `or` with standard precedence, e.g.
+    `regex("error") and sequence<5 or timestamp>12:00`.
+- Parse into an AST (not directly into engine queries — that's
+  [007](007-filterbar-integration.md)).
+- Surface parse errors with position info suitable for showing under the FilterBar
+  input.
+
+## Acceptance criteria
+
+- Grammar test cases cover: bare regex, single metric comparison, reserved-metric
+  comparison, `and`/`or` combinations with correct precedence, and at least one
+  malformed-input case producing a located error rather than a panic.
+- Parser is a standalone module with no dependency on the engine/index types, so it
+  can be unit tested in isolation.
+
+## Depends on
+
+None directly, but the metric-comparison side of the grammar is only meaningful once
+[002](002-metric-declarations.md) exists — build/test this ticket against metric
+names as opaque strings.
@@ -0,0 +1,30 @@
+# 006 — FilterBar datetime parsing
+
+## Summary
+
+Support the several datetime formats the README requires for timestamp comparisons
+in the filter language: relative humantime, absolute time, and full dates.
+
+## Scope
+
+- Relative humantime: `5h`, `-3m`, etc. — resolved against "now" (or against the
+  query's reference time, if one is introduced later) at parse/eval time.
+- Absolute time: e.g. `12:00` (time-of-day, as in the README's
+  `timestamp>12:00` example) — needs a defined rule for which day it resolves to.
+- Full date: complete date(+time) literals.
+- Produce a single normalized value (`Timestamp`/millis) regardless of input form, for
+  the filter evaluator ([007](007-filterbar-integration.md)) to compare against.
+- Pick and document a crate (e.g. `humantime` for the relative case) rather than
+  hand-rolling a datetime parser.
+
+## Acceptance criteria
+
+- Each of the three formats parses to the correct absolute millis value in unit
+  tests, including edge cases (negative relative offsets, time-of-day near midnight).
+- Ambiguous/invalid input produces a clear error rather than a silently wrong
+  timestamp.
+
+## Depends on
+
+None — standalone parsing module, consumed by
+[007 — FilterBar integration](007-filterbar-integration.md).
@@ -0,0 +1,36 @@
+# 007 — FilterBar query integration
+
+## Summary
+
+Wire the parsed filter AST into actual log/timeline queries against the engine, so
+FilterBar's syntax (not just a naive substring match) drives what's shown in
+LogPreview and LogTimeline.
+
+## Scope
+
+- Evaluator that walks the AST from [005](005-filterbar-pest-parser.md), resolving
+  `regex(...)` against log text and `metric_name[param] <op> value` against bucket
+  data ([004](004-metrics-api.md)), using datetime literals resolved via
+  [006](006-filterbar-datetime-parsing.md).
+- New/extended `EngineQuery::Logs` (and `Timeline`) filter parameter that accepts the
+  compiled filter, evaluated inside the engine's single-owner loop (per the README's
+  "engine is sole owner of the btreemap" architecture — don't evaluate against a
+  copy).
+- `sequence`/`timestamp` reserved-metric comparisons map directly to the
+  `IngestedLog` key fields rather than a declared metric lookup.
+- API layer: accept the raw filter string, parse it (return 4xx on parse error),
+  compile to whatever the engine query needs, send to engine.
+
+## Acceptance criteria
+
+- `GET /api/logs?filter=...` and the timeline equivalent apply the full filter
+  language, not just substring matching.
+- A filter combining a regex clause and a metric comparison with `and`/`or` returns
+  correct results against a seeded log+metric fixture.
+- Malformed filter strings return a 4xx with the parser's error message.
+
+## Depends on
+
+- [004 — Metrics API](004-metrics-api.md)
+- [005 — FilterBar pest parser](005-filterbar-pest-parser.md)
+- [006 — FilterBar datetime parsing](006-filterbar-datetime-parsing.md)
@@ -0,0 +1,33 @@
+# 008 — Settings model
+
+## Summary
+
+Implement the single, process-wide settings model described in the README's NavMenu
+section: colour scheme, CSS path config, and the settings file location — settable
+via CLI args, persisted at a sensible default OS location.
+
+## Scope
+
+- A `Settings` struct: colour scheme choice, list of imported/linked CSS entries
+  (see [010](010-css-management.md)), and whatever else profiles need to hang off of.
+- Default settings file location using an OS-conventions crate (e.g. `directories`)
+  rather than a hardcoded path.
+- `clap` arg(s) to override the settings file path at runtime (extend the existing
+  `Args` in `main.rs`, which today only has `--port`/`--static-dir`).
+- Load-on-start / save-on-change semantics; "at runtime, there is only 1 settings" —
+  i.e. a single in-memory settings instance, not per-request state, analogous to how
+  the engine owns the index.
+- Settings "owns" the profiles per the README — this ticket only needs to define
+  where profiles live under settings, not implement profile CRUD itself (that's
+  [009](009-presets-profiles.md)).
+
+## Acceptance criteria
+
+- Running with no args creates/reads a settings file at the documented default
+  location.
+- `--settings-path` (or similar) overrides it.
+- Settings persist across restarts (edit, restart, re-read matches).
+
+## Depends on
+
+None.
@@ -0,0 +1,34 @@
+# 009 — Presets / profiles
+
+## Summary
+
+Implement presets ("profiles") that track parsing/indexing rules (param + metric
+declarations) and stored dashboards, so restarting ottyl against a given CLI app
+doesn't lose that configuration.
+
+## Scope
+
+- Profile = a named bundle of: param declarations ([001](001-param-declarations.md)),
+  metric declarations ([002](002-metric-declarations.md)), and saved dashboards
+  ([014](014-dashboards-ui.md), once it exists — can stub the dashboard field until
+  then).
+- Persisted under the settings storage location from
+  [008](008-settings-model.md); settings reference which profile(s) exist / which is
+  active.
+- On startup, load the active profile's param/metric declarations into the engine
+  before ingestion starts (or apply-and-backfill if logs arrive before load
+  completes — define the ordering explicitly).
+- CRUD for profiles, exposed later via NavMenu UI ([011](011-navmenu-ui.md)).
+
+## Acceptance criteria
+
+- Declaring params/metrics through a profile, restarting the process, and re-running
+  the same CLI command reproduces the same bucket derivation without re-declaring
+  anything.
+- Multiple profiles can exist; switching the active profile changes which
+  declarations are loaded on next start.
+
+## Depends on
+
+- [008 — Settings model](008-settings-model.md)
+- [002 — Metric declarations](002-metric-declarations.md)
@@ -0,0 +1,30 @@
+# 010 — CSS import/management
+
+## Summary
+
+Let users import custom CSS (stored alongside settings/profiles, deletable) or link
+to an external CSS path/URL (not deletable, just referenced).
+
+## Scope
+
+- `POST /api/settings/css` (import): accept raw CSS content, store it in the same
+  directory as settings/profiles ([008](008-settings-model.md)), return an id/handle.
+- `DELETE /api/settings/css/:id`: remove an imported CSS file; reject deletion for
+  linked (non-imported) entries.
+- `POST /api/settings/css/link`: register a path/URL reference without copying
+  content; these are never deletable via the delete endpoint (only "unlink"-able,
+  if that distinction matters — clarify in implementation).
+- Settings model tracks the list of CSS entries (imported + linked) with enough
+  metadata to distinguish the two kinds.
+- Serve imported CSS content back so the frontend can `<link>`/inline it.
+
+## Acceptance criteria
+
+- Importing CSS persists content under the settings directory and survives restart.
+- Deleting an imported CSS entry removes the file and the settings reference.
+- Attempting to delete a linked (non-imported) entry is rejected.
+- Linked entries resolve to their original path/URL, not a copy.
+
+## Depends on
+
+- [008 — Settings model](008-settings-model.md)
@@ -0,0 +1,30 @@
+# 011 — NavMenu UI
+
+## Summary
+
+Build out the NavMenu frontend component for managing settings, presets, and CSS,
+per the README's block diagram (NavMenu occupies its own column alongside the rest
+of the dashboard).
+
+## Scope
+
+- Settings panel: colour scheme picker, CSS import (file/text input) + list of
+  imported/linked CSS with delete where applicable.
+- Presets panel: list/create/switch/delete profiles ([009](009-presets-profiles.md)),
+  showing each profile's param/metric declaration counts and saved dashboards.
+- Wire to the settings/profile/CSS APIs from
+  [008](008-settings-model.md)/[009](009-presets-profiles.md)/[010](010-css-management.md).
+- Apply the active colour scheme / imported CSS to the app shell at runtime.
+
+## Acceptance criteria
+
+- Switching active profile in the UI changes engine state (declared params/metrics)
+  without a manual restart, or clearly communicates that a restart is needed if
+  that's the chosen design from [009](009-presets-profiles.md).
+- Importing/deleting CSS in the UI is reflected immediately in the rendered app.
+
+## Depends on
+
+- [008 — Settings model](008-settings-model.md)
+- [009 — Presets / profiles](009-presets-profiles.md)
+- [010 — CSS import/management](010-css-management.md)
@@ -0,0 +1,27 @@
+# 012 — Metrics UI
+
+## Summary
+
+Replace the current "Coming Soon" Metrics placeholder with a real component: declare
+metrics via the metric language, and view their derived values.
+
+## Scope
+
+- A form/editor for declaring a metric (regex + param matchers) that calls
+  `POST /api/metrics` ([004](004-metrics-api.md)), with inline validation errors
+  surfaced from the API's 4xx responses.
+- List of currently-declared metrics with their labels.
+- A view of a selected metric's bucket values over the active time range (reuse the
+  time-range plumbing already in `App.tsx`/`LogTimeline`).
+
+## Acceptance criteria
+
+- Declaring a metric in the UI immediately reflects newly-matching logs (existing
+  and new) in the metric's value view, per the backfill behavior from
+  [003](003-metric-bucket-derivation.md).
+- Invalid metric definitions show the backend's validation error instead of failing
+  silently.
+
+## Depends on
+
+- [004 — Metrics API](004-metrics-api.md)
@@ -0,0 +1,30 @@
+# 013 — Dashboards: PromQL query support
+
+## Summary
+
+Support PromQL-style queries over declared metrics to derive dashboard
+visualizations, per the README's Dashboards section ("There should be support for
+promql queries to derive the visualisation").
+
+## Scope
+
+- Evaluate a useful PromQL subset (instant/range vector selection by metric name +
+  label matchers, at minimum; consider `rate()`/`sum()`/`avg()` aggregations as
+  stretch) against `Bucket` data ([003](003-metric-bucket-derivation.md)).
+- Decide whether to hand-roll the subset or bring in an existing PromQL parser
+  crate — document the choice.
+- New `EngineQuery` variant for PromQL evaluation, following the existing
+  single-owner-evaluates-in-place pattern.
+- API endpoint (e.g. `GET /api/query?promql=...`) returning a chart-ready series
+  format (labels + time-value pairs), shaped for bar/line/pie consumption by
+  [014](014-dashboards-ui.md).
+
+## Acceptance criteria
+
+- A basic instant/range query against a declared metric with a label matcher returns
+  correct series data against a seeded fixture.
+- Malformed PromQL returns a 4xx with a useful error.
+
+## Depends on
+
+- [004 — Metrics API](004-metrics-api.md)
@@ -0,0 +1,30 @@
+# 014 — Dashboards UI
+
+## Summary
+
+Replace the current "Coming Soon" Dashboards placeholder with a Grafana-style
+dashboard builder: bar, line, and pie charts backed by PromQL queries, saved as part
+of a profile.
+
+## Scope
+
+- Chart components for bar/line/pie (pick a charting lib — none is currently in
+  `webapp/package.json`).
+- Dashboard = a named set of panels, each with a PromQL query
+  ([013](013-dashboards-promql.md)) and a chart type.
+- Save/load dashboards as part of the active profile
+  ([009](009-presets-profiles.md)), so they persist across restarts.
+- Dashboard panels respect the app's active time range, same as LogTimeline/
+  LogPreview.
+
+## Acceptance criteria
+
+- Creating a panel with a PromQL query against a real declared metric renders the
+  correct chart type with live data.
+- Dashboards persist across restart via the active profile.
+- Panels re-query and update when the global time range changes.
+
+## Depends on
+
+- [013 — Dashboards: PromQL query support](013-dashboards-promql.md)
+- [009 — Presets / profiles](009-presets-profiles.md)
@@ -0,0 +1,28 @@
+# 015 — LogPreview: selectable parameter columns
+
+## Summary
+
+The README's LogPreview spec says it should be possible to pick which parameters are
+visible as columns, alongside the always-visible sequence/timestamp. Currently
+LogPreview only shows sequence, timestamp, and raw text.
+
+## Scope
+
+- Extend the logs API/DTO ([004](004-metrics-api.md) territory, but specifically the
+  existing `GET /api/logs`) to include derived param values per log line, sourced
+  from [001](001-param-declarations.md)'s declarations applied to that line.
+- Frontend: column picker UI in/near LogPreview; selected columns persist (localStorage
+  is fine for a per-viewer preference, or fold into settings if it should be shared —
+  pick localStorage unless product direction says otherwise).
+
+## Acceptance criteria
+
+- Declared params with a match on a given log line appear as selectable, populated
+  columns in LogPreview.
+- Column selection persists across a page reload.
+
+## Depends on
+
+- [001 — Param declarations](001-param-declarations.md)
+- [004 — Metrics API](004-metrics-api.md) (for the pattern of extending log query
+  responses)
@@ -0,0 +1,26 @@
+# 016 — FilterBar UI integration
+
+## Summary
+
+Wire the FilterBar frontend component to the real filter query language instead of
+the current naive client-side substring match in `App.tsx`
+(`logs.filter((l) => l.text.includes(filter))`).
+
+## Scope
+
+- Send the raw filter string to `GET /api/logs`/`GET /api/timeline` via the new
+  `filter` param from [007](007-filterbar-integration.md), instead of filtering
+  client-side.
+- Surface parse errors from the API (4xx + message) inline under the FilterBar input.
+- Remove the now-dead client-side `visibleLogs` substring filter in `App.tsx`.
+
+## Acceptance criteria
+
+- Typing a valid filter expression (regex + metric comparisons combined with
+  and/or) narrows both LogPreview and LogTimeline via server-side evaluation.
+- An invalid expression shows an inline error and does not clear/break the
+  currently-displayed logs.
+
+## Depends on
+
+- [007 — FilterBar query integration](007-filterbar-integration.md)
@@ -0,0 +1,24 @@
+# 017 — Ntfy.sh alerts (future idea)
+
+> The README lists this under "Ideas... that can be implemented in the future, but
+> not now." Not scoped for current implementation — tracked here so it isn't lost.
+
+## Summary
+
+Let users configure matchers of interest and an ntfy.sh channel, and send a
+notification to that channel when a matching event occurs.
+
+## Scope (sketch, not final)
+
+- Matcher definition, likely reusing the FilterBar query language
+  ([005](005-filterbar-pest-parser.md)) or the metric declaration language
+  ([002](002-metric-declarations.md)) rather than inventing a third syntax.
+- Ntfy channel config, persisted via settings ([008](008-settings-model.md)).
+- Trigger evaluation on log ingest (engine-side, to avoid re-scanning) or on bucket
+  update, sending an HTTP request to the configured ntfy.sh channel.
+
+## Depends on
+
+- [008 — Settings model](008-settings-model.md)
+- [005 — FilterBar pest parser](005-filterbar-pest-parser.md) (likely, for matcher
+  syntax reuse)
@@ -0,0 +1,28 @@
+# 018 — Sequence diagram of events (future idea)
+
+> The README lists this under "Ideas... that can be implemented in the future, but
+> not now." Not scoped for current implementation — tracked here so it isn't lost.
+
+## Summary
+
+Let users declare sequence-diagram participants from params or matchers (e.g.
+`node_id`), then render a sequence diagram of captured events of interest. No
+relation between nodes is modeled — only event sequence/ordering determines the
+diagram.
+
+## Scope (sketch, not final)
+
+- Participant declaration referencing an existing param
+  ([001](001-param-declarations.md)), e.g. "one participant per distinct value of
+  `node_id`".
+- Event-of-interest selection, likely reusing FilterBar syntax
+  ([005](005-filterbar-pest-parser.md)) to define which log lines become diagram
+  events.
+- Rendering: a sequence-diagram view (e.g. mermaid `sequenceDiagram`) driven by
+  ordered matching events per participant.
+
+## Depends on
+
+- [001 — Param declarations](001-param-declarations.md)
+- [005 — FilterBar pest parser](005-filterbar-pest-parser.md) (likely, for
+  event-matcher syntax reuse)