docs: document offset in the spec and check operators are served (#123)

spec.md had no mention of `offset`, so the MPL reference MetricsDB serves
(and MCP's getMetricsSpec returns) never told anyone it exists.

- add an Offset section to spec.md, plus offset and sample examples to
  examples::MPL (sample had no served example either)
- add a language-server test that fails when a pipe operator in KEYWORDS
  is missing from spec.md or from every served example

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: benenharrington

extra/mpl-language-server/Cargo.toml

@@ -32,5 +32,6 @@ examples = ["mpl-lang/examples"]
 lsp-bin = ["dep:eyre", "dep:lsp-server", "dep:lsp-types", "dep:serde_json"]
 
 [dev-dependencies]
+mpl-lang = { path = "../..", default-features = false, features = ["examples"] }
 test-case = "3"
 regex = "1"

extra/mpl-language-server/src/keywords.rs

@@ -178,6 +178,31 @@ mod tests {
         assert!(keyword_info("nonsense").is_none());
     }
 
+    /// MetricsDB serves `SPEC` and `MPL` as the MPL reference, so every operator must appear in both.
+    #[test]
+    fn every_pipe_operator_is_in_the_served_spec() {
+        // `filter` is a deprecated alias for `where`.
+        const EXEMPT: &[&str] = &["filter"];
+        let mut missing = Vec::new();
+        for entry in KEYWORDS {
+            let usage = format!("| {}", entry.label);
+            if EXEMPT.contains(&entry.label) || !entry.syntax.is_some_and(|s| s.starts_with(&usage))
+            {
+                continue;
+            }
+            if !mpl_lang::examples::SPEC.contains(&usage) {
+                missing.push(format!("spec.md does not show `{usage}`"));
+            }
+            if !mpl_lang::examples::MPL
+                .iter()
+                .any(|(_, example)| example.contains(&usage))
+            {
+                missing.push(format!("no example in `examples::MPL` uses `{usage}`"));
+            }
+        }
+        assert!(missing.is_empty(), "{}", missing.join("\n"));
+    }
+
     #[test]
     fn descriptions_are_present() {
         for entry in KEYWORDS {

spec.md

@@ -47,6 +47,40 @@ For example:
 `k8s-metrics-dev`:cpu_usage[2025-03-01T13:00:00Z..+1h]
 ```
 
+## Offset
+
+`offset` reads the source from an earlier time. The query keeps its time range: each value is read from that far back and
+returned at the matching time in the query range. This makes it possible to compare a metric with its own past, for
+example this week with the same time last week:
+
+```mpl
+// read the values from one hour earlier
+| offset -1h
+```
+
+With `offset -1h` and a time range of 10:00 to 11:00, the source reads 09:00 to 10:00, and the value recorded at 09:15
+is returned at 10:15.
+
+- The duration uses the [relative time](#time-range) units and must start with `-`. A negative offset moves back in
+  time, which is the opposite sign of PromQL's `offset`. Moving forward in time is not supported yet.
+- The offset operator is only valid right after the source, before `sample`, and at most once per source.
+- Each source in a [computation](#computation) has its own offset; a source without one reads the query's time range.
+  `offset` cannot follow `compute`.
+
+```mpl
+// requests per second compared with the same time one week earlier
+(
+  `k8s-metrics-dev`:http_requests_total
+  | align to 5m using prom::rate
+  | group using sum,
+  `k8s-metrics-dev`:http_requests_total
+  | offset -1w
+  | align to 5m using prom::rate
+  | group using sum
+)
+| compute week_over_week using /
+```
+
 ## Sampling
 
 Before the filter it is possible to sample the data. This can be helpful when designing more complex queries or get a
@@ -58,7 +92,7 @@ Sampling by 0.9 means that 90% of the series will be kept. The syntax is:
 | sample 0.9
 ```
 
-The sampling operator is only valid right after the source.
+The sampling operator is only valid right after the source, or after its [offset](#offset).
 
 ## Filtering
 

src/lib.rs

@@ -454,7 +454,7 @@ pub mod examples {
     pub const SPEC: &str = include_str!("../spec.md");
 
     /// MPL examples used in tests and documentation
-    pub const MPL: [(&str, &str); 19] = [
+    pub const MPL: [(&str, &str); 21] = [
         example!("align-rate"),
         example!("as"),
         // example!("enrich"),
@@ -469,9 +469,11 @@ pub mod examples {
         example!("map-gt"),
         example!("map-mul"),
         // example!("nested-enrich"),
+        example!("offset"),
         example!("parser-error"),
         example!("rate"),
         // example!("replace_labels"),
+        example!("sample"),
         example!("set"),
         example!("slo"),
         example!("slo-histogram"),

tests/examples/offset.mpl

@@ -0,0 +1,14 @@
+// sum(rate(http_requests_total[5m]))
+// /
+// sum(rate(http_requests_total[5m] offset 1w))
+
+(
+    test:http_requests_total
+    | align to 5m using prom::rate
+    | group using sum,
+    test:http_requests_total
+    | offset -1w
+    | align to 5m using prom::rate
+    | group using sum
+)
+| compute week_over_week using /

tests/examples/sample.mpl

@@ -0,0 +1,5 @@
+// look at a tenth of the series to get a feel for a large metric
+test:http_requests_total
+| sample 0.1
+| align to 5m using prom::rate
+| group by method using sum