@feltdb/core 0.12.0 → 0.12.2

package/dist/create/server-source/crates/feltdb-server/tests/fixtures/query-shape-trace.expected.json

@@ -0,0 +1,300 @@
+{
+  "capacity": 4,
+  "evicted_executions": 3,
+  "evictions": 3,
+  "excluded": 3,
+  "memory_bound_bytes": 16544,
+  "memory_estimate_bytes": 2402,
+  "observer_failures": 0,
+  "reserved": 2,
+  "retained_shapes": 4,
+  "shape_version": 1,
+  "shapes": [
+    {
+      "first_seen_sequence": 0,
+      "id": "6ee623172a0af6b9",
+      "shape": {
+        "collection": "orders",
+        "limit": "11-100",
+        "order_by": [
+          [
+            "createdAt",
+            "desc"
+          ]
+        ],
+        "predicates": [
+          [
+            "status",
+            "eq"
+          ],
+          [
+            "tenant",
+            "eq"
+          ]
+        ],
+        "version": 1
+      },
+      "stats": {
+        "continuations": 1,
+        "errors": 0,
+        "executions": 3,
+        "indexed": 3,
+        "latency": {
+          "count": 0,
+          "log2_micros": [
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0
+          ],
+          "max_nanos": 0,
+          "sum_nanos": 0
+        },
+        "matched_max": 20,
+        "matched_sum": 35,
+        "ok": 3,
+        "returned_sum": 38,
+        "scans": 0
+      }
+    },
+    {
+      "first_seen_sequence": 4,
+      "id": "298753584fa85596",
+      "shape": {
+        "collection": "events",
+        "limit": "11-100",
+        "order_by": [
+          [
+            "at",
+            "desc"
+          ]
+        ],
+        "predicates": [
+          [
+            "kind",
+            "eq"
+          ]
+        ],
+        "version": 1
+      },
+      "stats": {
+        "continuations": 0,
+        "errors": 0,
+        "executions": 2,
+        "indexed": 2,
+        "latency": {
+          "count": 0,
+          "log2_micros": [
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0
+          ],
+          "max_nanos": 0,
+          "sum_nanos": 0
+        },
+        "matched_max": 5,
+        "matched_sum": 10,
+        "ok": 2,
+        "returned_sum": 10,
+        "scans": 0
+      }
+    },
+    {
+      "first_seen_sequence": 1,
+      "id": "b10342945f3d8cbc",
+      "shape": {
+        "collection": "orders",
+        "limit": "2-10",
+        "order_by": [
+          [
+            "total",
+            "asc"
+          ]
+        ],
+        "predicates": [
+          [
+            "total",
+            "gt"
+          ]
+        ],
+        "version": 1
+      },
+      "stats": {
+        "continuations": 0,
+        "errors": 1,
+        "executions": 2,
+        "indexed": 0,
+        "latency": {
+          "count": 0,
+          "log2_micros": [
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0
+          ],
+          "max_nanos": 0,
+          "sum_nanos": 0
+        },
+        "matched_max": 400,
+        "matched_sum": 400,
+        "ok": 1,
+        "returned_sum": 10,
+        "scans": 1
+      }
+    },
+    {
+      "first_seen_sequence": 6,
+      "id": "8562ada66d0e7dd2",
+      "shape": {
+        "collection": "tasks",
+        "limit": "11-100",
+        "order_by": [
+          [
+            "at",
+            "desc"
+          ]
+        ],
+        "predicates": [
+          [
+            "done",
+            "eq"
+          ]
+        ],
+        "version": 1
+      },
+      "stats": {
+        "continuations": 0,
+        "errors": 0,
+        "executions": 1,
+        "indexed": 0,
+        "latency": {
+          "count": 0,
+          "log2_micros": [
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0
+          ],
+          "max_nanos": 0,
+          "sum_nanos": 0
+        },
+        "matched_max": 1,
+        "matched_sum": 1,
+        "ok": 1,
+        "returned_sum": 1,
+        "scans": 1
+      }
+    }
+  ],
+  "unsupported": [
+    [
+      "semantic_clause",
+      1
+    ],
+    [
+      "unknown_operator",
+      1
+    ],
+    [
+      "unknown_direction",
+      0
+    ],
+    [
+      "limit_out_of_range",
+      0
+    ],
+    [
+      "too_many_predicates",
+      0
+    ],
+    [
+      "too_many_order_fields",
+      0
+    ],
+    [
+      "identifier_too_long",
+      0
+    ]
+  ]
+}

package/dist/create/server-source/crates/feltdb-server/tests/fixtures/query-shape-trace.json

@@ -0,0 +1,25 @@
+{
+  "description": "A value-free workload trace. Events carry structure and the outcome the real execution path reported; there is no place for a predicate value, cursor, principal or tenant.",
+  "config": { "capacity": 4, "excludeCollections": ["secrets"], "excludeFields": ["*.ssn", "people.dob"] },
+  "events": [
+    { "collection": "orders", "where": [["status", "eq"], ["tenant", "eq"]], "orderBy": [["createdAt", "desc"]], "limit": 50, "outcome": "indexed", "matched": 12, "returned": 12 },
+    { "collection": "orders", "where": [["tenant", "eq"], ["status", "eq"]], "orderBy": [["createdAt", "desc"]], "limit": 60, "outcome": "indexed", "matched": 3, "returned": 3 },
+    { "collection": "orders", "where": [["tenant", "eq"], ["status", "eq"]], "orderBy": [["createdAt", "desc"]], "limit": 60, "outcome": "continuation", "returned": 3 },
+    { "collection": "orders", "where": [["total", "gt"]], "orderBy": [["total", "asc"]], "limit": 10, "outcome": "scan", "matched": 400, "returned": 10 },
+    { "collection": "orders", "where": [["total", "gt"]], "orderBy": [["total", "asc"]], "limit": 10, "outcome": "error" },
+    { "collection": "orders", "where": [["status", "eq"]], "orderBy": [["createdAt", "asc"]], "limit": 1, "outcome": "indexed", "matched": 1, "returned": 1 },
+    { "collection": "_feltdb.Proposal", "where": [["status", "eq"]], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 2, "returned": 2 },
+    { "collection": "state", "where": [], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 2, "returned": 2 },
+    { "collection": "secrets", "where": [["k", "eq"]], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 0, "returned": 0 },
+    { "collection": "people", "where": [["ssn", "eq"]], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 0, "returned": 0 },
+    { "collection": "people", "where": [["dob", "lt"]], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 0, "returned": 0 },
+    { "collection": "people", "where": [["age", "gte"]], "orderBy": [["id", "asc"]], "limit": 10, "outcome": "scan", "matched": 9, "returned": 9 },
+    { "collection": "orders", "where": [["status", "eq"]], "orderBy": [["createdAt", "desc"]], "limit": 10, "semantic": true, "outcome": "scan", "matched": 1, "returned": 1 },
+    { "collection": "orders", "where": [["status", "like"]], "orderBy": [["createdAt", "desc"]], "limit": 10, "outcome": "scan", "matched": 1, "returned": 1 },
+    { "collection": "events", "where": [["kind", "eq"]], "orderBy": [["at", "desc"]], "limit": 100, "outcome": "indexed", "matched": 5, "returned": 5 },
+    { "collection": "events", "where": [["kind", "eq"]], "orderBy": [["at", "desc"]], "limit": 100, "outcome": "indexed", "matched": 5, "returned": 5 },
+    { "collection": "sessions", "where": [["user", "eq"]], "orderBy": [["at", "desc"]], "limit": 100, "outcome": "scan", "matched": 1, "returned": 1 },
+    { "collection": "tasks", "where": [["done", "eq"]], "orderBy": [["at", "desc"]], "limit": 100, "outcome": "scan", "matched": 1, "returned": 1 },
+    { "collection": "orders", "where": [["status", "eq"], ["tenant", "eq"]], "orderBy": [["createdAt", "desc"]], "limit": 55, "outcome": "indexed", "matched": 20, "returned": 20 }
+  ]
+}

package/dist/create/server-source/crates/feltdb-server/tests/query_shape_trace.rs

@@ -0,0 +1,128 @@
+//! Deterministic trace replay for the query-shape observer.
+//!
+//! A trace is value-free structure plus the outcome the real execution path
+//! reported. Replaying it must produce the same aggregate observations every
+//! time, and those aggregates are pinned against a checked-in golden file so a
+//! change to normalization, eviction or accounting is a reviewed diff rather
+//! than an accident. Wall-clock latency is excluded from the comparison; it is
+//! the one input that is not a function of the trace.
+//!
+//! Regenerate deliberately with `UPDATE_QUERY_SHAPE_GOLDEN=1`.
+
+use feltdb_server::query_shape::{
+    Access, ObserverConfig, ObserverSnapshot, QueryShapeObserver, ShapeInput,
+};
+use serde_json::Value;
+use std::path::PathBuf;
+
+fn fixture(name: &str) -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures")
+        .join(name)
+}
+
+fn pairs(value: &Value) -> Vec<(String, String)> {
+    value
+        .as_array()
+        .map(|items| {
+            items
+                .iter()
+                .map(|pair| {
+                    (
+                        pair[0].as_str().unwrap().to_string(),
+                        pair[1].as_str().unwrap().to_string(),
+                    )
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn replay(trace: &Value) -> ObserverSnapshot {
+    let config = &trace["config"];
+    let strings = |key: &str| {
+        config[key].as_array().map(|items| {
+            items
+                .iter()
+                .map(|v| v.as_str().unwrap())
+                .collect::<Vec<_>>()
+                .join(",")
+        })
+    };
+    let observer = QueryShapeObserver::new(
+        ObserverConfig::from_values(
+            Some("1"),
+            Some(&config["capacity"].as_u64().unwrap().to_string()),
+            strings("excludeCollections").as_deref(),
+            strings("excludeFields").as_deref(),
+        )
+        .unwrap()
+        .unwrap(),
+    );
+    for event in trace["events"].as_array().unwrap() {
+        let predicates = pairs(&event["where"]);
+        let order_by = pairs(&event["orderBy"]);
+        let predicates: Vec<(&str, &str)> = predicates
+            .iter()
+            .map(|(a, b)| (a.as_str(), b.as_str()))
+            .collect();
+        let order_by: Vec<(&str, &str)> = order_by
+            .iter()
+            .map(|(a, b)| (a.as_str(), b.as_str()))
+            .collect();
+        let observation = observer.begin(&ShapeInput {
+            collection: event["collection"].as_str().unwrap(),
+            predicates: &predicates,
+            order_by: &order_by,
+            limit: event["limit"].as_u64().unwrap() as usize,
+            has_semantic_clause: event["semantic"].as_bool().unwrap_or(false),
+        });
+        let matched = event["matched"].as_u64().unwrap_or(0) as usize;
+        let returned = event["returned"].as_u64().unwrap_or(0) as usize;
+        match event["outcome"].as_str().unwrap() {
+            "indexed" => observation.finish_executed(Access::Indexed, matched, returned),
+            "scan" => observation.finish_executed(Access::Scan, matched, returned),
+            "continuation" => observation.finish_continuation(returned),
+            "error" => drop(observation),
+            other => panic!("unknown trace outcome {other}"),
+        }
+    }
+    observer.snapshot().without_timing()
+}
+
+fn load() -> Value {
+    serde_json::from_str(&std::fs::read_to_string(fixture("query-shape-trace.json")).unwrap())
+        .unwrap()
+}
+
+#[test]
+fn replaying_a_trace_reproduces_the_same_aggregates() {
+    let trace = load();
+    let first = serde_json::to_value(replay(&trace)).unwrap();
+    let second = serde_json::to_value(replay(&trace)).unwrap();
+    assert_eq!(first, second, "two replays of one trace must agree");
+
+    let golden = fixture("query-shape-trace.expected.json");
+    if std::env::var("UPDATE_QUERY_SHAPE_GOLDEN").as_deref() == Ok("1") {
+        std::fs::write(
+            &golden,
+            serde_json::to_string_pretty(&first).unwrap() + "\n",
+        )
+        .unwrap();
+    }
+    let expected: Value = serde_json::from_str(&std::fs::read_to_string(&golden).unwrap()).unwrap();
+    assert_eq!(first, expected, "aggregates drifted from the golden file");
+}
+
+#[test]
+fn the_trace_and_its_observations_contain_no_values_or_excluded_names() {
+    let trace = load();
+    let rendered = serde_json::to_string(&replay(&trace)).unwrap();
+    for leaked in ["secrets", "ssn", "dob", "_feltdb", "\"state\""] {
+        assert!(!rendered.contains(leaked), "{leaked} retained: {rendered}");
+    }
+    let snapshot = replay(&trace);
+    assert_eq!(snapshot.reserved, 2);
+    assert_eq!(snapshot.excluded, 3);
+    assert!(snapshot.retained_shapes <= 4);
+}