Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(second-brain): make the graph memory layer real — API half + stream reconciliation

xerj-orgb0f209e569cc
diff --git a/engine/Cargo.lock b/engine/Cargo.lock
index 96990a0e6..1ecdf9aee 100644
--- a/engine/Cargo.lock
+++ b/engine/Cargo.lock
@@ -6249,6 +6249,7 @@ dependencies = [
"xerj-engine",
"xerj-query",
"xerj-wasm",
+ "xxhash-rust",
]
[[package]]
diff --git a/engine/crates/xerj-api/Cargo.toml b/engine/crates/xerj-api/Cargo.toml
index 70bbb79ab..42176a3d1 100644
--- a/engine/crates/xerj-api/Cargo.toml
+++ b/engine/crates/xerj-api/Cargo.toml
@@ -31,6 +31,8 @@ bytes = { workspace = true }
prometheus = { workspace = true }
dashmap = { workspace = true }
tracing-subscriber = { workspace = true }
+# Second-brain graph API: edge_id identity hashing (SECOND_BRAIN_SPEC §2.3).
+xxhash-rust = { workspace = true }
async-trait = "0.1"
libc = "0.2"
diff --git a/engine/crates/xerj-api/src/graph_api.rs b/engine/crates/xerj-api/src/graph_api.rs
new file mode 100644
index 000000000..3cc9b03c8
--- /dev/null
+++ b/engine/crates/xerj-api/src/graph_api.rs
@@ -0,0 +1,1662 @@
+//! Second-Brain Graph REST API — a relationship layer over documents that
+//! already exist.
+//!
+//! This is not a graph database. There is no query language, no shortest-path,
+//! no PageRank, and no unbounded traversal — by design. Edges are ordinary
+//! documents; expansion is a bounded, batched read (≤2 hops per call).
+//!
+//! Each brain `B` keeps its edges in one reserved index,
+//! `.xerj-memory-{B}-edges` (schema: SECOND_BRAIN_SPEC §2), so edges ride the
+//! existing WAL → memtable → segment → doc-values path with zero
+//! storage-format change. Traversal is [`xerj_engine::graph::Index::graph_expand`]
+//! — a columnar expansion, never a per-node query fan-out. Like
+//! `memory_api.rs`, this module is a thin adapter that composes the proven
+//! ES-compat handlers (`create_index`, `index_doc`, `get_doc`, `search`); it
+//! does NOT re-implement search.
+//!
+//! Endpoints (mounted on the ES-compat router):
+//! ```text
+//! POST /_graph/{brain}/link assert an edge (lazy index create)
+//! DELETE /_graph/{brain}/link/{edge_id} soft-invalidate (bi-temporal; never removes)
+//! GET /_graph/{brain}/ego neighborhood of one node (+ hydration)
+//! GET /_graph/{brain}/overview brain-level stats (dashboard feed)
+//! ```
+//!
+//! Bi-temporality: an edge is never physically removed by this API.
+//! Invalidation re-indexes the same document (same `_id`) with
+//! `invalid_at`/`expired_at` added, so "what did it believe last Tuesday"
+//! stays answerable via `as_of` on every read endpoint.
+//!
+//! Honesty in-band: every read response carries a `not_shown` object counting
+//! what was withheld (clipped edges/frontiers, bi-temporally excluded edges,
+//! segments skipped, dangling node refs, agg tails).
+//!
+//! ## Authorization model
+//!
+//! ⚠️ The `/_graph/*` endpoints are guarded ONLY by the process-wide API-key
+//! auth middleware (the admin key or any key minted via
+//! `POST /_security/api_key`). There is **no per-brain authorization**: any
+//! credential that can reach the node can read, write, and invalidate edges
+//! in **every** brain. Brains isolate data *by name*, NOT by credential — do
+//! not treat a brain as a security boundary between mutually-distrusting
+//! tenants. Per-brain access control depends on the deferred RBAC enforcement
+//! (see `xerj_engine::rbac`).
+
+use axum::{
+ extract::{Path, Query, State},
+ http::StatusCode,
+ response::{IntoResponse, Response},
+ Json,
+};
+use serde::Deserialize;
+use serde_json::{json, Map, Value};
+use std::collections::{HashMap, HashSet};
+
+use crate::es_compat::{
+ self, EsSearchBody, EsSearchJson, EsSearchQueryParams, GetDocParams, IndexDocParams,
+};
+use crate::extract::OptionalJson;
+use crate::state::AppState;
+use xerj_engine::graph::{
+ GraphDirection, GraphEdgeLite, GraphExpandRequest, GRAPH_HOPS_CAP_REASON,
+};
+
+/// Contract version string, returned by every read endpoint.
+pub const GRAPH_CONTRACT: &str = "xerj-second-brain/1";
+
+/// Reserved `_id` of the per-brain meta document (SECOND_BRAIN_SPEC §2.5). It
+/// carries no `src`/`dst`, so the hop path and every edge count (all filter on
+/// `exists src`) never see it.
+const BRAIN_META_ID: &str = "__xerj-brain-meta";
+
+/// Max returned edges for `ego` (`limit` clamp ceiling).
+const MAX_EGO_LIMIT: usize = 1000;
+
+/// Max dangling node ids listed verbatim in `not_shown.dangling_ids`.
+const MAX_DANGLING_LISTED: usize = 50;
+
+/// Edges index name for a brain (SECOND_BRAIN_SPEC §1). The leading dot passes
+/// `IndexName::validate` and is unreachable through user index APIs.
+fn edges_index(brain: &str) -> String {
+ format!(".xerj-memory-{brain}-edges")
+}
+
+/// Default nodes index for a brain: the agent-memory namespace of the same
+/// name. Autoindex brains override this via the §2.5 meta doc.
+fn default_nodes_index(brain: &str) -> String {
+ format!(".xerj-memory-{brain}")
+}
+
+/// Brain-name validation (SECOND_BRAIN_SPEC §1): identical rules to
+/// `memory_api::validate_namespace` (lowercase/digit start, `[a-z0-9._-]`,
+/// ≤200 chars, no `..`) plus the `-edges` suffix rejection — without it a
+/// brain named `kb-edges` would collide with brain `kb`'s edge index.
+/// xerj-autoindex carries a matching copy (`detect::validate_brain`).
+fn validate_brain(brain: &str) -> Result<(), String> {
+ if brain.is_empty() {
+ return Err("brain name must not be empty".into());
+ }
+ if brain.len() > 200 {
+ return Err("brain name too long (max 200 chars)".into());
+ }
+ let first = brain.chars().next().unwrap();
+ if !(first.is_ascii_lowercase() || first.is_ascii_digit()) {
+ return Err("brain name must start with a lowercase letter or digit".into());
+ }
+ for c in brain.chars() {
+ let ok = c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '_' | '-' | '.');
+ if !ok {
+ return Err(format!(
+ "brain name contains illegal character '{c}' (allowed: a-z 0-9 _ - .)"
+ ));
+ }
+ }
+ if brain.contains("..") {
+ return Err("brain name must not contain '..'".into());
+ }
+ if brain.ends_with("-edges") {
+ return Err("namespace suffix '-edges' is reserved for graph edge indices".into());
+ }
+ Ok(())
+}
+
+/// edge_id = xxh3_128("xg1\0" src "\0" type "\0" dst "\0" decimal(valid_at_ms)),
+/// rendered as 32 lowercase hex chars ({:032x}). Byte-identical copy of
+/// `xerj_autoindex::detect::edge_id` (SECOND_BRAIN_SPEC §2.3) — both crates pin
+/// the same test vector so the two writers can never drift apart. Same
+/// (src, type, dst, valid_at) → same `_id` → re-asserts overwrite instead of
+/// duplicating; a DIFFERENT `valid_at` creates a distinct edge (bi-temporal
+/// design, not a bug).
+pub fn edge_id(src: &str, edge_type: &str, dst: &str, valid_at_ms: i64) -> String {
+ use xxhash_rust::xxh3::xxh3_128;
+ let mut input = Vec::with_capacity(16 + src.len() + edge_type.len() + dst.len());
+ input.extend_from_slice(b"xg1\x00");
+ input.extend_from_slice(src.as_bytes());
+ input.push(0);
+ input.extend_from_slice(edge_type.as_bytes());
+ input.push(0);
+ input.extend_from_slice(dst.as_bytes());
+ input.push(0);
+ input.extend_from_slice(valid_at_ms.to_string().as_bytes());
+ format!("{:032x}", xxh3_128(&input))
+}
+
+/// The exact edges-index mapping body (SECOND_BRAIN_SPEC §2.1), byte-identical
+/// to `xerj_autoindex::detect::edge_index_mapping` — the two writers must
+/// agree or the first one to touch a brain decides the column types for
+/// everyone. Timestamps are `epoch_millis` NUMBERS (never ISO strings — a
+/// string would make the doc-values column a KeywordColumn and kill the as-of
+/// compare on the hop path).
+fn edge_index_mapping() -> Value {
+ json!({
+ "mappings": {
+ "properties": {
+ "edge_id": { "type": "keyword" },
+ "src": { "type": "keyword" },
+ "dst": { "type": "keyword" },
+ "type": { "type": "keyword" },
+ "weight": { "type": "float" },
+ "valid_at": { "type": "date", "format": "epoch_millis" },
+ "invalid_at": { "type": "date", "format": "epoch_millis" },
+ "created_at": { "type": "date", "format": "epoch_millis" },
+ "expired_at": { "type": "date", "format": "epoch_millis" },
+ "detector": { "type": "keyword" },
+ "confidence": { "type": "float" },
+ "schema_version": { "type": "integer" },
+ "src_file": { "type": "keyword" },
+ "evidence": {
+ "properties": {
+ "quote": { "type": "text" },
+ "source": { "type": "keyword" },
+ "offset": { "type": "long" }
+ }
+ }
+ }
+ }
+ })
+}
+
+/// Emit a uniform graph error response (same shape as memory_api, typed
+/// `graph_error`).
+fn error_response(status: StatusCode, reason: impl Into<String>) -> Response {
+ (
+ status,
+ Json(json!({
+ "error": { "type": "graph_error", "reason": reason.into() },
+ "status": status.as_u16(),
+ })),
+ )
+ .into_response()
+}
+
+/// Drain an inner handler [`Response`] into `(status, json_body)` so this
+/// module can inspect the reused ES-compat handler's result and re-shape it
+/// into the graph contract. (Private copy of memory_api's helper, per the
+/// adapter discipline: compose, don't widen visibility.)
+async fn drain_json(resp: Response) -> (StatusCode, Value) {
+ let status = resp.status();
+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+ .await
+ .unwrap_or_default();
+ let value = serde_json::from_slice::<Value>(&bytes).unwrap_or(Value::Null);
+ (status, value)
+}
+
+/// Whether an index currently exists.
+fn index_exists(state: &AppState, index: &str) -> bool {
+ state.engine.get_index(index).is_ok()
+}
+
+/// Parse a timestamp that may be an epoch-ms JSON number or an RFC3339 string
+/// (inputs accept both; outputs are always numbers).
+fn parse_ms_value(v: &Value) -> Option<i64> {
+ match v {
+ Value::Number(_) => v.as_i64().or_else(|| v.as_f64().map(|f| f as i64)),
+ Value::String(s) => parse_ms_str(s),
+ _ => None,
+ }
+}
+
+/// Parse a query-string timestamp: decimal epoch-ms first, RFC3339 second.
+fn parse_ms_str(s: &str) -> Option<i64> {
+ if let Ok(n) = s.parse::<i64>() {
+ return Some(n);
+ }
+ chrono::DateTime::parse_from_rfc3339(s)
+ .ok()
+ .map(|dt| dt.timestamp_millis())
+}
+
+/// Server "now" in epoch milliseconds.
+fn now_ms() -> i64 {
+ chrono::Utc::now().timestamp_millis()
+}
+
+/// Ensure the edges index for a brain exists with the §2.1 mapping and its
+/// §2.5 meta doc. Lazy — called on the write path (`link`) only; read
+/// endpoints 404 on an unknown brain instead.
+async fn ensure_edges_index(state: &AppState, brain: &str, index: &str) -> Result<(), Response> {
+ if index_exists(state, index) {
+ return Ok(());
+ }
+ let resp = es_compat::create_index(
+ State(state.clone()),
+ Path(index.to_string()),
+ OptionalJson(Some(edge_index_mapping())),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ // Tolerate a concurrent creator winning the race.
+ if !status.is_success() && !index_exists(state, index) {
+ return Err(error_response(
+ status,
+ format!("failed to create edges index for brain '{brain}': {body}"),
+ ));
+ }
+
+ // §2.5 meta doc, create-if-absent (`op_type=create`): a racing writer's
+ // meta doc must never be clobbered — it may carry a `nodes_index` some
+ // reader already resolved through. A 409 conflict is exactly the state we
+ // want; any other failure is surfaced.
+ let meta = json!({
+ "meta_version": 1,
+ "brain": brain,
+ "nodes_index": default_nodes_index(brain),
+ "created_at": now_ms(),
+ });
+ let params = IndexDocParams {
+ op_type: Some("create".into()),
+ ..Default::default()
+ };
+ let resp = es_compat::index_doc(
+ State(state.clone()),
+ Path((index.to_string(), BRAIN_META_ID.to_string())),
+ Query(params),
+ Json(meta),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if !status.is_success() && status != StatusCode::CONFLICT {
+ return Err(error_response(
+ status,
+ format!("failed to write brain meta doc for '{brain}': {body}"),
+ ));
+ }
+ Ok(())
+}
+
+/// Resolve the nodes index for a brain: explicit request param → meta doc's
+/// `nodes_index` → the `.xerj-memory-{brain}` default.
+async fn resolve_nodes_index(state: &AppState, brain: &str, index: &str) -> String {
+ let resp = es_compat::get_doc(
+ State(state.clone()),
+ Path((index.to_string(), BRAIN_META_ID.to_string())),
+ Query(GetDocParams::default()),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if status.is_success() {
+ if let Some(ni) = body.pointer("/_source/nodes_index").and_then(Value::as_str) {
+ if !ni.is_empty() {
+ return ni.to_string();
+ }
+ }
+ }
+ default_nodes_index(brain)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// POST /_graph/{brain}/link — assert an edge
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Request body for `POST /_graph/{brain}/link` (SECOND_BRAIN_SPEC §4.1).
+/// Unknown fields are rejected with a 400 — a typo'd key must never silently
+/// drop an assertion detail.
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LinkBody {
+ pub src: String,
+ pub dst: String,
+ #[serde(rename = "type")]
+ pub edge_type: String,
+ /// Optional, default 1.0, clamped to [0, 1].
+ #[serde(default)]
+ pub weight: Option<f64>,
+ /// Optional epoch-ms number or RFC3339 string; default = server now.
+ #[serde(default)]
+ pub valid_at: Option<Value>,
+ /// Optional epoch-ms number or RFC3339 string; default = server now
+ /// (fixtures/imports).
+ #[serde(default)]
+ pub created_at: Option<Value>,
+ /// Optional, default 1.0, clamped to [0, 1].
+ #[serde(default)]
+ pub confidence: Option<f64>,
+ /// Optional, default "manual@1".
+ #[serde(default)]
+ pub detector: Option<String>,
+ /// Optional `{quote, source, offset}` object.
+ #[serde(default)]
+ pub evidence: Option<Value>,
+}
+
+/// `POST /_graph/{brain}/link` — assert an edge. Creates the edges index
+/// lazily (§2.1 mapping + §2.5 meta doc). 201 on first assertion, 200 when
+/// the same (src, type, dst, valid_at) is re-asserted (idempotent overwrite).
+pub async fn link(
+ State(state): State<AppState>,
+ Path(brain): Path<String>,
+ body: OptionalJson<LinkBody>,
+) -> Response {
+ if let Err(reason) = validate_brain(&brain) {
+ return error_response(StatusCode::BAD_REQUEST, reason);
+ }
+ let Some(body) = body.0 else {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "link requires a JSON body with `src`, `dst`, and `type`",
+ );
+ };
+ if body.src.is_empty() {
+ return error_response(StatusCode::BAD_REQUEST, "`src` must be a non-empty string");
+ }
+ if body.dst.is_empty() {
+ return error_response(StatusCode::BAD_REQUEST, "`dst` must be a non-empty string");
+ }
+ if body.src == body.dst {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "self-edges are not allowed (src == dst)",
+ );
+ }
+ if body.edge_type.is_empty() {
+ return error_response(StatusCode::BAD_REQUEST, "`type` must be a non-empty string");
+ }
+ let weight = body.weight.unwrap_or(1.0);
+ if !weight.is_finite() {
+ return error_response(StatusCode::BAD_REQUEST, "`weight` must be a finite number");
+ }
+ let weight = weight.clamp(0.0, 1.0);
+ let confidence = body.confidence.unwrap_or(1.0);
+ if !confidence.is_finite() {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`confidence` must be a finite number",
+ );
+ }
+ let confidence = confidence.clamp(0.0, 1.0);
+ let detector = body.detector.unwrap_or_else(|| "manual@1".into());
+ let now = now_ms();
+ let valid_at = match &body.valid_at {
+ None => now,
+ Some(v) => match parse_ms_value(v) {
+ Some(ms) => ms,
+ None => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`valid_at` must be an epoch-ms number or an RFC3339 string",
+ );
+ }
+ },
+ };
+ let created_at = match &body.created_at {
+ None => now,
+ Some(v) => match parse_ms_value(v) {
+ Some(ms) => ms,
+ None => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`created_at` must be an epoch-ms number or an RFC3339 string",
+ );
+ }
+ },
+ };
+ if let Some(ev) = &body.evidence {
+ if !ev.is_object() {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`evidence` must be an object like {quote, source, offset}",
+ );
+ }
+ }
+
+ let index = edges_index(&brain);
+ if let Err(resp) = ensure_edges_index(&state, &brain, &index).await {
+ return resp;
+ }
+
+ // §2.4 stored document. §2.2 type discipline: scalars are plain
+ // strings/numbers; `invalid_at`/`expired_at`/`src_file` are OMITTED when
+ // unset (never null) — omission lands the row in the doc-values
+ // null_bitmap, which is exactly the "still valid" signal the hop reads.
+ let id = edge_id(&body.src, &body.edge_type, &body.dst, valid_at);
+ let mut doc = json!({
+ "edge_id": id,
+ "src": body.src,
+ "dst": body.dst,
+ "type": body.edge_type,
+ "weight": weight,
+ "valid_at": valid_at,
+ "created_at": created_at,
+ "detector": detector,
+ "confidence": confidence,
+ "schema_version": 1,
+ });
+ if let Some(ev) = &body.evidence {
+ // Top-level `src_file` mirrors evidence.source so invalidation-style
+ // queries ride the keyword doc-values prefilter, matching the
+ // autoindex writer's shape.
+ if let Some(src_file) = ev.get("source").and_then(Value::as_str) {
+ doc["src_file"] = json!(src_file);
+ }
+ doc["evidence"] = ev.clone();
+ }
+
+ let resp = es_compat::index_doc(
+ State(state.clone()),
+ Path((index.clone(), id.clone())),
+ Query(IndexDocParams::default()),
+ Json(doc.clone()),
+ )
+ .await
+ .into_response();
+ let (status, result_body) = drain_json(resp).await;
+ if !status.is_success() {
+ return error_response(status, format!("failed to store edge: {result_body}"));
+ }
+ let created = result_body.get("result").and_then(Value::as_str) == Some("created");
+ let status = if created {
+ StatusCode::CREATED
+ } else {
+ StatusCode::OK
+ };
+ (
+ status,
+ Json(json!({
+ "brain": brain,
+ "edge_id": id,
+ "created": created,
+ "edge": doc,
+ })),
+ )
+ .into_response()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DELETE /_graph/{brain}/link/{edge_id} — soft invalidate
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Query params for `DELETE /_graph/{brain}/link/{edge_id}`.
+#[derive(Debug, Default, Deserialize)]
+pub struct UnlinkParams {
+ /// When the fact stopped being true (epoch-ms or RFC3339; default =
+ /// server now). `expired_at` — when the system recorded that — is always
+ /// server now; the two form the bi-temporal pair.
+ #[serde(default)]
+ pub invalid_at: Option<String>,
+}
+
+/// `DELETE /_graph/{brain}/link/{edge_id}` — soft-invalidate an edge. NEVER
+/// removes the document: the same doc is re-indexed under the same `_id` with
+/// `invalid_at`/`expired_at` added, keeping `as_of` time travel answerable.
+pub async fn unlink(
+ State(state): State<AppState>,
+ Path((brain, edge_id)): Path<(String, String)>,
+ Query(params): Query<UnlinkParams>,
+) -> Response {
+ if let Err(reason) = validate_brain(&brain) {
+ return error_response(StatusCode::BAD_REQUEST, reason);
+ }
+ let not_found = || {
+ error_response(
+ StatusCode::NOT_FOUND,
+ format!("edge '{edge_id}' does not exist in brain '{brain}'"),
+ )
+ };
+ let index = edges_index(&brain);
+ if !index_exists(&state, &index) {
+ return not_found();
+ }
+ let resp = es_compat::get_doc(
+ State(state.clone()),
+ Path((index.clone(), edge_id.clone())),
+ Query(GetDocParams::default()),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if status == StatusCode::NOT_FOUND {
+ return not_found();
+ }
+ if !status.is_success() {
+ return error_response(status, format!("failed to read edge: {body}"));
+ }
+ let Some(source) = body.get("_source").cloned() else {
+ return not_found();
+ };
+
+ // Already invalidated → idempotent no-op that reports the standing fact.
+ if let Some(already) = source.get("invalid_at").and_then(parse_ms_value) {
+ return Json(json!({
+ "brain": brain,
+ "edge_id": edge_id,
+ "invalidated": false,
+ "already_invalid_at": already,
+ }))
+ .into_response();
+ }
+
+ let now = now_ms();
+ let invalid_at = match &params.invalid_at {
+ None => now,
+ Some(s) => match parse_ms_str(s) {
+ Some(ms) => ms,
+ None => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`invalid_at` must be an epoch-ms number or an RFC3339 string",
+ );
+ }
+ },
+ };
+ let mut doc = source;
+ doc["invalid_at"] = json!(invalid_at);
+ doc["expired_at"] = json!(now);
+
+ let resp = es_compat::index_doc(
+ State(state.clone()),
+ Path((index, edge_id.clone())),
+ Query(IndexDocParams::default()),
+ Json(doc),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if !status.is_success() {
+ return error_response(status, format!("failed to invalidate edge: {body}"));
+ }
+ Json(json!({
+ "brain": brain,
+ "edge_id": edge_id,
+ "invalidated": true,
+ "invalid_at": invalid_at,
+ "expired_at": now,
+ }))
+ .into_response()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GET /_graph/{brain}/ego — neighborhood of one node
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Query params for `GET /_graph/{brain}/ego` (SECOND_BRAIN_SPEC §4.3).
+#[derive(Debug, Default, Deserialize)]
+pub struct EgoParams {
+ /// REQUIRED — the node to expand from.
+ #[serde(default)]
+ pub node: Option<String>,
+ /// 1 (default) or 2; anything else is a 400 with the not-a-graph-database
+ /// wording.
+ #[serde(default)]
+ pub hops: Option<u64>,
+ /// `out` | `in` | `both` (default).
+ #[serde(default)]
+ pub direction: Option<String>,
+ /// Comma-separated edge-type allowlist; absent = all types.
+ #[serde(default)]
+ pub types: Option<String>,
+ /// Max returned edges, clamped 1..=1000 (default 100).
+ #[serde(default)]
+ pub limit: Option<u64>,
+ /// Bi-temporal cut (epoch-ms or RFC3339; default now).
+ #[serde(default)]
+ pub as_of: Option<String>,
+ /// Return soft-invalidated edges too (default false).
+ #[serde(default)]
+ pub include_expired: Option<bool>,
+ /// Hydrate node summaries from the nodes index (default false).
+ #[serde(default)]
+ pub include_nodes: Option<bool>,
+ /// Nodes index override; default = meta doc's `nodes_index`, else
+ /// `.xerj-memory-{brain}`.
+ #[serde(default)]
+ pub nodes_index: Option<String>,
+ /// Hydrate evidence/envelope for RETURNED edges (default true).
+ #[serde(default)]
+ pub include_evidence: Option<bool>,
+}
+
+/// `GET /_graph/{brain}/ego` — the bounded neighborhood of one node.
+/// Traversal reads doc-values columns only; evidence and node summaries are
+/// hydrated AFTER traversal, on the bounded result set, via `ids` queries.
+pub async fn ego(
+ State(state): State<AppState>,
+ Path(brain): Path<String>,
+ Query(params): Query<EgoParams>,
+) -> Response {
+ if let Err(reason) = validate_brain(&brain) {
+ return error_response(StatusCode::BAD_REQUEST, reason);
+ }
+ let node = match params.node.as_deref() {
+ Some(n) if !n.is_empty() => n.to_string(),
+ _ => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`node` is required: the node id to expand from",
+ );
+ }
+ };
+ let hops = params.hops.unwrap_or(1);
+ if hops == 0 || hops > 2 {
+ return error_response(StatusCode::BAD_REQUEST, GRAPH_HOPS_CAP_REASON);
+ }
+ let direction_str = params.direction.as_deref().unwrap_or("both");
+ let direction = match direction_str {
+ "out" => GraphDirection::Out,
+ "in" => GraphDirection::In,
+ "both" => GraphDirection::Both,
+ other => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ format!("`direction` must be 'out', 'in', or 'both' (got '{other}')"),
+ );
+ }
+ };
+ let types: Option<Vec<String>> = params.types.as_deref().map(|t| {
+ t.split(',')
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+ .map(String::from)
+ .collect()
+ });
+ let types = types.filter(|t| !t.is_empty());
+ let limit = (params.limit.unwrap_or(100) as usize).clamp(1, MAX_EGO_LIMIT);
+ let as_of = match params.as_of.as_deref() {
+ None => now_ms(),
+ Some(s) => match parse_ms_str(s) {
+ Some(ms) => ms,
+ None => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`as_of` must be an epoch-ms number or an RFC3339 string",
+ );
+ }
+ },
+ };
+ let include_expired = params.include_expired.unwrap_or(false);
+ let include_nodes = params.include_nodes.unwrap_or(false);
+ let include_evidence = params.include_evidence.unwrap_or(true);
+
+ let index = edges_index(&brain);
+ let Ok(idx) = state.engine.get_index(&index) else {
+ return error_response(
+ StatusCode::NOT_FOUND,
+ format!("brain '{brain}' does not exist (no edges index)"),
+ );
+ };
+
+ let req = GraphExpandRequest {
+ frontier: vec![node.clone()],
+ hops: hops as u8,
+ direction,
+ types,
+ as_of_ms: as_of,
+ include_expired,
+ max_result_edges: limit,
+ };
+ let result = match idx.graph_expand(&req) {
+ Ok(r) => r,
+ Err(e) => return error_response(StatusCode::BAD_REQUEST, e.to_string()),
+ };
+
+ // Per-edge direction relative to the expansion: an edge discovered at hop
+ // h is "out" iff its src was in hop h's frontier (an edge admitted by both
+ // scans reports "out"). The hop-1 frontier is the ego node; the hop-2
+ // frontier is every endpoint hop 1 discovered.
+ let mut frontier1: HashSet<&str> = HashSet::new();
+ frontier1.insert(node.as_str());
+ let mut frontier2: HashSet<&str> = HashSet::new();
+ for e in result.edges.iter().filter(|e| e.hop == 1) {
+ for id in [e.src.as_str(), e.dst.as_str()] {
+ if !frontier1.contains(id) {
+ frontier2.insert(id);
+ }
+ }
+ }
+ let edge_direction = |e: &GraphEdgeLite| -> &'static str {
+ let frontier = if e.hop == 1 { &frontier1 } else { &frontier2 };
+ if frontier.contains(e.src.as_str()) {
+ "out"
+ } else {
+ "in"
+ }
+ };
+
+ // Post-traversal hydration (bounded ≤ limit ≤ 1000): ONE `ids` search on
+ // the edges index for evidence/envelope fields — rides the ids-prefilter
+ // fast path; the hop itself never touched `_source`.
+ let mut hydrated: HashMap<String, Value> = HashMap::new();
+ if include_evidence && !result.edges.is_empty() {
+ let ids: Vec<&str> = result.edges.iter().map(|e| e.edge_id.as_str()).collect();
+ let search_body = EsSearchBody {
+ query: Some(json!({ "ids": { "values": ids } })),
+ size: ids.len(),
+ ..Default::default()
+ };
+ let resp = es_compat::search(
+ State(state.clone()),
+ Path(index.clone()),
+ Query(EsSearchQueryParams::default()),
+ EsSearchJson(Some(search_body)),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if status.is_success() {
+ if let Some(hits) = body.pointer("/hits/hits").and_then(Value::as_array) {
+ for h in hits {
+ if let (Some(id), Some(src)) =
+ (h.get("_id").and_then(Value::as_str), h.get("_source"))
+ {
+ hydrated.insert(id.to_string(), src.clone());
+ }
+ }
+ }
+ }
+ }
+
+ // Node summaries (`include_nodes=true`): ONE `ids` search on the nodes
+ // index for every reachable id. Ids that resolve nowhere are DANGLING —
+ // the edge is kept, the honesty is counted, and up to 50 ids are listed.
+ let mut nodes_obj = Map::new();
+ let mut dangling_nodes = 0u64;
+ let mut dangling_ids: Vec<String> = Vec::new();
+ if include_nodes {
+ let nodes_index = match params.nodes_index.as_deref() {
+ Some(ni) if !ni.is_empty() => ni.to_string(),
+ _ => resolve_nodes_index(&state, &brain, &index).await,
+ };
+ let mut found: HashSet<String> = HashSet::new();
+ let search_body = EsSearchBody {
+ query: Some(json!({ "ids": { "values": result.reachable } })),
+ size: result.reachable.len(),
+ ..Default::default()
+ };
+ let resp = es_compat::search(
+ State(state.clone()),
+ Path(nodes_index.clone()),
+ Query(EsSearchQueryParams::default()),
+ EsSearchJson(Some(search_body)),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if status.is_success() {
+ if let Some(hits) = body.pointer("/hits/hits").and_then(Value::as_array) {
+ for h in hits {
+ let Some(id) = h.get("_id").and_then(Value::as_str) else {
+ continue;
+ };
+ let src = h.get("_source");
+ let title = src
+ .and_then(|s| s.get("title"))
+ .and_then(Value::as_str)
+ .map(Value::from)
+ .unwrap_or(Value::Null);
+ let preview = src
+ .and_then(|s| {
+ s.get("text")
+ .and_then(Value::as_str)
+ .or_else(|| s.get("body").and_then(Value::as_str))
+ })
+ .map(|t| Value::from(t.chars().take(160).collect::<String>()))
+ .unwrap_or(Value::Null);
+ let hit_index = h
+ .get("_index")
+ .cloned()
+ .unwrap_or_else(|| json!(nodes_index));
+ found.insert(id.to_string());
+ nodes_obj.insert(
+ id.to_string(),
+ json!({ "title": title, "preview": preview, "index": hit_index }),
+ );
+ }
+ }
+ }
+ // A missing/unsearchable nodes index means every reachable id is
+ // dangling — reported, never fabricated.
+ let mut dangling: Vec<&String> = result
+ .reachable
+ .iter()
+ .filter(|id| !found.contains(*id))
+ .collect();
+ dangling.sort();
+ dangling_nodes = dangling.len() as u64;
+ dangling_ids = dangling
+ .into_iter()
+ .take(MAX_DANGLING_LISTED)
+ .cloned()
+ .collect();
+ }
+
+ // Edges in the §3.2 stable order (the engine already sorted), each
+ // annotated with its expansion direction; `invalid_at` is JSON null when
+ // unset (response-side null is fine — the omit-rule binds stored docs).
+ let edges_json: Vec<Value> = result
+ .edges
+ .iter()
+ .map(|e| {
+ let mut obj = json!({
+ "edge_id": e.edge_id,
+ "src": e.src,
+ "dst": e.dst,
+ "type": e.edge_type,
+ "weight": e.weight,
+ "hop": e.hop,
+ "direction": edge_direction(e),
+ "valid_at": e.valid_at_ms,
+ "invalid_at": e.invalid_at_ms.map(Value::from).unwrap_or(Value::Null),
+ });
+ if let Some(src) = hydrated.get(&e.edge_id) {
+ for field in [
+ "created_at",
+ "detector",
+ "confidence",
+ "evidence",
+ "expired_at",
+ ] {
+ if let Some(v) = src.get(field) {
+ obj[field] = v.clone();
+ }
+ }
+ }
+ obj
+ })
+ .collect();
+
+ // Neighbors: first-discovery order following the sorted edge list,
+ // excluding the ego node; `via_edge` is the first sorted edge that
+ // reached each one.
+ let mut neighbors: Vec<Value> = Vec::new();
+ let mut seen: HashSet<&str> = HashSet::new();
+ seen.insert(node.as_str());
+ for e in &result.edges {
+ for id in [e.src.as_str(), e.dst.as_str()] {
+ if seen.insert(id) {
+ neighbors.push(json!({ "id": id, "hop": e.hop, "via_edge": e.edge_id }));
+ }
+ }
+ }
+
+ let mut resp = json!({
+ "brain": brain,
+ "contract": GRAPH_CONTRACT,
+ "node": node,
+ "as_of": as_of,
+ "hops": hops,
+ "direction": direction_str,
+ "edges": edges_json,
+ "neighbors": neighbors,
+ "not_shown": {
+ "edges_clipped": result.stats.edges_clipped,
+ "frontier_clipped": result.stats.frontier_clipped,
+ "expired_excluded": result.stats.expired_excluded,
+ "type_filtered": result.stats.type_filtered,
+ "segments_without_columns": result.stats.segments_without_columns,
+ "memtable_docs_scanned": result.stats.memtable_docs_scanned,
+ "dangling_nodes": dangling_nodes,
+ "dangling_ids": dangling_ids,
+ }
+ });
+ if include_nodes {
+ resp["nodes"] = Value::Object(nodes_obj);
+ }
+ Json(resp).into_response()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GET /_graph/{brain}/overview — brain-level stats (dashboard feed)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Query params for `GET /_graph/{brain}/overview` (SECOND_BRAIN_SPEC §4.4).
+#[derive(Debug, Default, Deserialize)]
+pub struct OverviewParams {
+ /// Bi-temporal cut for the live slice (epoch-ms or RFC3339; default now).
+ #[serde(default)]
+ pub as_of: Option<String>,
+ /// Size of every top-N list, clamped 1..=50 (default 10).
+ #[serde(default)]
+ pub top: Option<u64>,
+ /// `day` (default) | `hour`.
+ #[serde(default)]
+ pub histogram_interval: Option<String>,
+}
+
+/// Run one size-0 search on the edges index and return the drained JSON body
+/// (or an error response). Composes `es_compat::search` — the aggregations are
+/// the same terms/date_histogram machinery every dashboard already uses.
+async fn overview_search(
+ state: &AppState,
+ index: &str,
+ body: EsSearchBody,
+) -> Result<Value, Response> {
+ let resp = es_compat::search(
+ State(state.clone()),
+ Path(index.to_string()),
+ Query(EsSearchQueryParams::default()),
+ EsSearchJson(Some(body)),
+ )
+ .await
+ .into_response();
+ let (status, body) = drain_json(resp).await;
+ if !status.is_success() {
+ return Err(error_response(
+ status,
+ format!("overview search failed: {body}"),
+ ));
+ }
+ Ok(body)
+}
+
+/// Terms-agg buckets → `[{"<key_name>": key, "<count_name>": doc_count}]`,
+/// plus the agg's `sum_other_doc_count` (the not-listed tail, reported
+/// in-band).
+fn terms_list(aggs: &Value, agg: &str, key_name: &str, count_name: &str) -> (Vec<Value>, u64) {
+ let buckets = aggs
+ .pointer(&format!("/{agg}/buckets"))
+ .and_then(Value::as_array);
+ let list = buckets
+ .map(|bs| {
+ bs.iter()
+ .map(|b| {
+ json!({
+ key_name: b.get("key").cloned().unwrap_or(Value::Null),
+ count_name: b.get("doc_count").cloned().unwrap_or(json!(0)),
+ })
+ })
+ .collect()
+ })
+ .unwrap_or_default();
+ let other = aggs
+ .pointer(&format!("/{agg}/sum_other_doc_count"))
+ .and_then(Value::as_u64)
+ .unwrap_or(0);
+ (list, other)
+}
+
+/// The honesty marker for the default embedder (§0 invariant 8): the built-in
+/// embedder is LEXICAL feature-hashing — no surface may imply neural
+/// semantics. When the node backing store is configured with a real external/
+/// neural embedder, its configured id is reported verbatim instead.
+fn embedder_id(state: &AppState) -> String {
+ let emb = &state.config.embedding;
+ match emb.mode.as_str() {
+ "neural" => emb.neural_model.clone(),
+ "proxy" if !emb.default_model.is_empty() => emb.default_model.clone(),
+ "proxy" => "proxy".into(),
+ "auto" if !emb.default_endpoint.is_empty() && !emb.default_model.is_empty() => {
+ emb.default_model.clone()
+ }
+ "auto" if !emb.default_endpoint.is_empty() => "proxy".into(),
+ _ => "lexical-feature-hash".into(),
+ }
+}
+
+/// `GET /_graph/{brain}/overview` — totals, live slice (types/detectors/
+/// hubs), and the created-over-time histogram. Exactly three composed
+/// searches; every top-N tail is reported in `not_shown`.
+pub async fn overview(
+ State(state): State<AppState>,
+ Path(brain): Path<String>,
+ Query(params): Query<OverviewParams>,
+) -> Response {
+ if let Err(reason) = validate_brain(&brain) {
+ return error_response(StatusCode::BAD_REQUEST, reason);
+ }
+ let as_of = match params.as_of.as_deref() {
+ None => now_ms(),
+ Some(s) => match parse_ms_str(s) {
+ Some(ms) => ms,
+ None => {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`as_of` must be an epoch-ms number or an RFC3339 string",
+ );
+ }
+ },
+ };
+ let top = (params.top.unwrap_or(10) as usize).clamp(1, 50);
+ let interval = params.histogram_interval.as_deref().unwrap_or("day");
+ if !matches!(interval, "day" | "hour") {
+ return error_response(
+ StatusCode::BAD_REQUEST,
+ "`histogram_interval` must be 'day' or 'hour'",
+ );
+ }
+
+ let index = edges_index(&brain);
+ if !index_exists(&state, &index) {
+ return (
+ StatusCode::NOT_FOUND,
+ Json(json!({ "brain": brain, "contract": GRAPH_CONTRACT, "exists": false })),
+ )
+ .into_response();
+ }
+
+ // 1. Totals: every edge ever asserted (`exists src` excludes the meta doc).
+ let totals = EsSearchBody {
+ query: Some(json!({ "exists": { "field": "src" } })),
+ size: 0,
+ track_total_hits: Some(json!(true)),
+ ..Default::default()
+ };
+ let totals = match overview_search(&state, &index, totals).await {
+ Ok(v) => v,
+ Err(r) => return r,
+ };
+ let total = totals
+ .pointer("/hits/total/value")
+ .and_then(Value::as_u64)
+ .unwrap_or(0);
+
+ // 2. Live slice at as_of, with the type/detector/hub breakdowns.
+ let live_body = EsSearchBody {
+ query: Some(json!({
+ "bool": {
+ "filter": [
+ { "exists": { "field": "src" } },
+ { "range": { "valid_at": { "lte": as_of } } }
+ ],
+ "must_not": [
+ { "range": { "invalid_at": { "lte": as_of } } }
+ ]
+ }
+ })),
+ size: 0,
+ track_total_hits: Some(json!(true)),
+ aggs: Some(json!({
+ "by_type": { "terms": { "field": "type", "size": top } },
+ "by_detector": { "terms": { "field": "detector", "size": top } },
+ "top_src": { "terms": { "field": "src", "size": top } },
+ "top_dst": { "terms": { "field": "dst", "size": top } },
+ })),
+ ..Default::default()
+ };
+ let live_resp = match overview_search(&state, &index, live_body).await {
+ Ok(v) => v,
+ Err(r) => return r,
+ };
+ let live = live_resp
+ .pointer("/hits/total/value")
+ .and_then(Value::as_u64)
+ .unwrap_or(0);
+ let aggs = live_resp
+ .get("aggregations")
+ .cloned()
+ .unwrap_or(Value::Null);
+ let (types, types_other) = terms_list(&aggs, "by_type", "type", "live");
+ let (detectors, detectors_other) = terms_list(&aggs, "by_detector", "detector", "live");
+ let (hubs_out, hubs_out_other) = terms_list(&aggs, "top_src", "id", "live_edges");
+ let (hubs_in, hubs_in_other) = terms_list(&aggs, "top_dst", "id", "live_edges");
+
+ // 3. Created-over-time histogram (all asserted edges, not just live —
+ // the timeline shows assertion activity, invalidation does not erase it).
+ let timeline_body = EsSearchBody {
+ query: Some(json!({ "exists": { "field": "src" } })),
+ size: 0,
+ aggs: Some(json!({
+ "created": {
+ "date_histogram": { "field": "created_at", "calendar_interval": interval }
+ }
+ })),
+ ..Default::default()
+ };
+ let timeline = match overview_search(&state, &index, timeline_body).await {
+ Ok(v) => v,
+ Err(r) => return r,
+ };
+ let created_over_time: Vec<Value> = timeline
+ .pointer("/aggregations/created/buckets")
+ .and_then(Value::as_array)
+ .map(|bs| {
+ bs.iter()
+ .map(|b| {
+ json!({
+ "t": b.get("key").cloned().unwrap_or(Value::Null),
+ "count": b.get("doc_count").cloned().unwrap_or(json!(0)),
+ })
+ })
+ .collect()
+ })
+ .unwrap_or_default();
+
+ let nodes_index = resolve_nodes_index(&state, &brain, &index).await;
+ Json(json!({
+ "brain": brain,
+ "contract": GRAPH_CONTRACT,
+ "exists": true,
+ "as_of": as_of,
+ "nodes_index": nodes_index,
+ "embedder": embedder_id(&state),
+ "edges": {
+ "total": total,
+ "live": live,
+ "invalidated": total.saturating_sub(live),
+ },
+ "types": types,
+ "detectors": detectors,
+ "hubs": { "out": hubs_out, "in": hubs_in },
+ "created_over_time": created_over_time,
+ "not_shown": {
+ "types_not_listed": types_other,
+ "detectors_not_listed": detectors_other,
+ "hubs_out_not_listed": hubs_out_other,
+ "hubs_in_not_listed": hubs_in_other,
+ }
+ }))
+ .into_response()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests — the SECOND_BRAIN_SPEC §8 fixture, end to end through the handlers
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::collections::BTreeMap;
+ use xerj_common::{config::Config, metrics::Metrics};
+ use xerj_engine::Engine;
+
+ const T0: i64 = 1_753_600_000_000; // fixture valid_at / created_at
+ const AS_OF: i64 = 1_753_700_000_000; // fixture as-of instant
+ const INVALID_AT: i64 = 1_753_650_000_000; // §8.6 invalidation instant
+
+ fn test_state() -> AppState {
+ let dir = tempfile::tempdir().expect("tempdir");
+ // Leak the tempdir so the data directory outlives the test body — the
+ // Engine holds it open; cleanup is the OS's problem at process exit.
+ let path = dir.keep();
+ let mut config = Config::default();
+ config.server.data_dir = path.to_str().unwrap().to_string();
+ let metrics = Metrics::new().expect("metrics");
+ let engine = Engine::new(config.clone()).expect("engine");
+ AppState::new(config, engine, metrics)
+ }
+
+ async fn do_link(state: &AppState, brain: &str, body: Value) -> (StatusCode, Value) {
+ let b: LinkBody = serde_json::from_value(body).unwrap();
+ let resp = link(
+ State(state.clone()),
+ Path(brain.to_string()),
+ OptionalJson(Some(b)),
+ )
+ .await;
+ drain_json(resp).await
+ }
+
+ async fn do_unlink(
+ state: &AppState,
+ brain: &str,
+ edge_id: &str,
+ invalid_at: Option<&str>,
+ ) -> (StatusCode, Value) {
+ let resp = unlink(
+ State(state.clone()),
+ Path((brain.to_string(), edge_id.to_string())),
+ Query(UnlinkParams {
+ invalid_at: invalid_at.map(String::from),
+ }),
+ )
+ .await;
+ drain_json(resp).await
+ }
+
+ async fn do_ego(state: &AppState, brain: &str, params: EgoParams) -> (StatusCode, Value) {
+ let resp = ego(State(state.clone()), Path(brain.to_string()), Query(params)).await;
+ drain_json(resp).await
+ }
+
+ fn ego_params(node: &str, as_of: i64) -> EgoParams {
+ EgoParams {
+ node: Some(node.to_string()),
+ as_of: Some(as_of.to_string()),
+ ..Default::default()
+ }
+ }
+
+ /// The eight §8.3 fixture edges as `link` bodies (explicit timestamps so
+ /// the fixture is reproducible; src_file = evidence.source throughout).
+ fn fixture_links() -> Vec<Value> {
+ let alpha_line = "Alpha is the hub note. It links to [[beta]] and [[gamma]].";
+ let wiki = |src: &str, dst: &str, quote: &str, source: &str, offset: u64| {
+ json!({
+ "src": src, "dst": dst, "type": "wikilink",
+ "weight": 1.0, "confidence": 0.95, "detector": "wikilink@1",
+ "valid_at": T0, "created_at": T0,
+ "evidence": { "quote": quote, "source": source, "offset": offset }
+ })
+ };
+ let dir = |src: &str, dst: &str, quote: &str, source: &str| {
+ json!({
+ "src": src, "dst": dst, "type": "same_dir",
+ "weight": 0.3, "confidence": 0.4, "detector": "samedir@1",
+ "valid_at": T0, "created_at": T0,
+ "evidence": { "quote": quote, "source": source, "offset": 0 }
+ })
+ };
+ vec![
+ wiki("note-alpha", "note-beta", alpha_line, "alpha.md", 35),
+ wiki("note-alpha", "note-gamma", alpha_line, "alpha.md", 48),
+ wiki(
+ "note-beta",
+ "note-gamma",
+ "Beta continues the thread and references [[gamma]].",
+ "beta.md",
+ 41,
+ ),
+ wiki(
+ "note-delta",
+ "note-alpha",
+ "Delta cites [[alpha]] as its source.",
+ "delta.md",
+ 12,
+ ),
+ dir(
+ "note-alpha",
+ "note-beta",
+ "alpha.md and beta.md share directory .",
+ "alpha.md",
+ ),
+ dir(
+ "note-beta",
+ "note-delta",
+ "beta.md and delta.md share directory .",
+ "beta.md",
+ ),
+ dir(
+ "note-delta",
+ "note-epsilon",
+ "delta.md and epsilon.md share directory .",
+ "delta.md",
+ ),
+ dir(
+ "note-epsilon",
+ "note-gamma",
+ "epsilon.md and gamma.md share directory .",
+ "epsilon.md",
+ ),
+ ]
+ }
+
+ /// §8.3 edge ids, in table order.
+ const FIXTURE_IDS: [&str; 8] = [
+ "bef814a75bd3d914c3e561f610154304",
+ "11c2d0ef216cd6e99a3907a0b53c1452",
+ "9bbf7d2068321ac0fa71d95e21fae2fd",
+ "cead55986c364ad5ff6f0894daf61f77",
+ "63b747655365aa16d38188aa49966f40",
+ "a61e6caacb5e485baf6d45184f23ec67",
+ "3efff61b58c978943e6fd2a1e4eeaee8",
+ "7c07cdc441f0a3faa29be8946df3e7a4",
+ ];
+
+ async fn link_fixture(state: &AppState) {
+ for (i, body) in fixture_links().into_iter().enumerate() {
+ let (s, b) = do_link(state, "notes", body).await;
+ assert_eq!(s, StatusCode::CREATED, "fixture edge {i} must create: {b}");
+ assert_eq!(
+ b["edge_id"].as_str().unwrap(),
+ FIXTURE_IDS[i],
+ "fixture edge {i} id must match the §8.3 pin"
+ );
+ }
+ }
+
+ /// §2.3 pin vector — keeps this copy of `edge_id` in lockstep with the
+ /// autoindex copy.
+ #[test]
+ fn edge_id_pin_vector() {
+ assert_eq!(
+ edge_id("note-alpha", "wikilink", "note-beta", 1753600000000),
+ "bef814a75bd3d914c3e561f610154304"
+ );
+ }
+
+ #[test]
+ fn brain_validation_rejects_the_edges_suffix() {
+ assert!(validate_brain("notes").is_ok());
+ assert!(validate_brain("kb-edges").is_err());
+ assert!(validate_brain("").is_err());
+ assert!(validate_brain("Notes").is_err());
+ assert!(validate_brain("a..b").is_err());
+ }
+
+ /// §4.1: link creates (201) with the pinned edge_id; a re-assert of the
+ /// same (src, type, dst, valid_at) overwrites (200, created=false);
+ /// self-edges are a 400 with the normative reason.
+ #[tokio::test]
+ async fn link_pins_edge_ids_and_is_idempotent() {
+ let state = test_state();
+ link_fixture(&state).await;
+
+ // Re-assert edge #1 → overwrite, not duplicate.
+ let (s, b) = do_link(&state, "notes", fixture_links()[0].clone()).await;
+ assert_eq!(s, StatusCode::OK, "re-assert is an overwrite: {b}");
+ assert_eq!(b["created"], json!(false));
+ assert_eq!(b["edge_id"].as_str().unwrap(), FIXTURE_IDS[0]);
+ // The stored doc carries the §2.4 envelope, with src_file mirrored
+ // from evidence.source and NO invalid_at/expired_at keys.
+ let edge = &b["edge"];
+ assert_eq!(edge["src_file"], json!("alpha.md"));
+ assert_eq!(edge["schema_version"], json!(1));
+ assert!(edge.get("invalid_at").is_none());
+ assert!(edge.get("expired_at").is_none());
+
+ let (s, b) = do_link(
+ &state,
+ "notes",
+ json!({ "src": "n1", "dst": "n1", "type": "t" }),
+ )
+ .await;
+ assert_eq!(s, StatusCode::BAD_REQUEST);
+ assert_eq!(
+ b["error"]["reason"],
+ json!("self-edges are not allowed (src == dst)")
+ );
+
+ // The brain named like an edges index is rejected up front.
+ let (s, _) = do_link(
+ &state,
+ "kb-edges",
+ json!({ "src": "a", "dst": "b", "type": "t" }),
+ )
+ .await;
+ assert_eq!(s, StatusCode::BAD_REQUEST);
+ }
+
+ /// §8.5: the ego response is byte-normative (only `memtable_docs_scanned`
+ /// is flush-state-dependent, asserted ≥ 0 and then normalized).
+ #[tokio::test]
+ async fn ego_matches_the_fixture_response() {
+ let state = test_state();
+ link_fixture(&state).await;
+
+ let (s, mut got) = do_ego(&state, "notes", ego_params("note-alpha", AS_OF)).await;
+ assert_eq!(s, StatusCode::OK, "{got}");
+ assert!(
+ got["not_shown"]["memtable_docs_scanned"].as_u64().is_some(),
+ "memtable_docs_scanned must be present (≥0)"
+ );
+ got["not_shown"]["memtable_docs_scanned"] = json!(0);
+
+ let expected = json!({
+ "brain": "notes",
+ "contract": "xerj-second-brain/1",
+ "node": "note-alpha",
+ "as_of": 1753700000000i64,
+ "hops": 1,
+ "direction": "both",
+ "edges": [
+ { "edge_id": "11c2d0ef216cd6e99a3907a0b53c1452", "src": "note-alpha", "dst": "note-gamma",
+ "type": "wikilink", "weight": 1.0, "hop": 1, "direction": "out",
+ "valid_at": 1753600000000i64, "invalid_at": null, "created_at": 1753600000000i64,
+ "detector": "wikilink@1", "confidence": 0.95,
+ "evidence": { "quote": "Alpha is the hub note. It links to [[beta]] and [[gamma]].", "source": "alpha.md", "offset": 48 } },
+ { "edge_id": "bef814a75bd3d914c3e561f610154304", "src": "note-alpha", "dst": "note-beta",
+ "type": "wikilink", "weight": 1.0, "hop": 1, "direction": "out",
+ "valid_at": 1753600000000i64, "invalid_at": null, "created_at": 1753600000000i64,
+ "detector": "wikilink@1", "confidence": 0.95,
+ "evidence": { "quote": "Alpha is the hub note. It links to [[beta]] and [[gamma]].", "source": "alpha.md", "offset": 35 } },
+ { "edge_id": "cead55986c364ad5ff6f0894daf61f77", "src": "note-delta", "dst": "note-alpha",
+ "type": "wikilink", "weight": 1.0, "hop": 1, "direction": "in",
+ "valid_at": 1753600000000i64, "invalid_at": null, "created_at": 1753600000000i64,
+ "detector": "wikilink@1", "confidence": 0.95,
+ "evidence": { "quote": "Delta cites [[alpha]] as its source.", "source": "delta.md", "offset": 12 } },
+ { "edge_id": "63b747655365aa16d38188aa49966f40", "src": "note-alpha", "dst": "note-beta",
+ "type": "same_dir", "weight": 0.3, "hop": 1, "direction": "out",
+ "valid_at": 1753600000000i64, "invalid_at": null, "created_at": 1753600000000i64,
+ "detector": "samedir@1", "confidence": 0.4,
+ "evidence": { "quote": "alpha.md and beta.md share directory .", "source": "alpha.md", "offset": 0 } }
+ ],
+ "neighbors": [
+ { "id": "note-gamma", "hop": 1, "via_edge": "11c2d0ef216cd6e99a3907a0b53c1452" },
+ { "id": "note-beta", "hop": 1, "via_edge": "bef814a75bd3d914c3e561f610154304" },
+ { "id": "note-delta", "hop": 1, "via_edge": "cead55986c364ad5ff6f0894daf61f77" }
+ ],
+ "not_shown": {
+ "edges_clipped": 0, "frontier_clipped": 0, "expired_excluded": 0,
+ "type_filtered": 0, "segments_without_columns": 0,
+ "memtable_docs_scanned": 0, "dangling_nodes": 0, "dangling_ids": []
+ }
+ });
+ assert_eq!(got, expected, "ego response must match §8.5 exactly");
+
+ // Dangling honesty (§8.5 tail): with no node docs stored,
+ // include_nodes=true returns an empty `nodes` object and lists every
+ // reachable id as dangling, sorted.
+ let mut p = ego_params("note-alpha", AS_OF);
+ p.include_nodes = Some(true);
+ let (s, got) = do_ego(&state, "notes", p).await;
+ assert_eq!(s, StatusCode::OK);
+ assert_eq!(got["nodes"], json!({}));
+ assert_eq!(got["not_shown"]["dangling_nodes"], json!(4));
+ assert_eq!(
+ got["not_shown"]["dangling_ids"],
+ json!(["note-alpha", "note-beta", "note-delta", "note-gamma"])
+ );
+ }
+
+ /// §8.6: soft invalidation + as_of time travel + include_expired, and the
+ /// idempotent second DELETE.
+ #[tokio::test]
+ async fn soft_invalidate_time_travel() {
+ let state = test_state();
+ link_fixture(&state).await;
+
+ let (s, b) = do_unlink(
+ &state,
+ "notes",
+ FIXTURE_IDS[0],
+ Some(&INVALID_AT.to_string()),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK, "{b}");
+ assert_eq!(b["invalidated"], json!(true));
+ assert_eq!(b["invalid_at"], json!(INVALID_AT));
+ assert!(b["expired_at"].as_i64().unwrap() > 0);
+
+ // Second DELETE: reports the standing invalidation, changes nothing.
+ let (s, b) = do_unlink(&state, "notes", FIXTURE_IDS[0], None).await;
+ assert_eq!(s, StatusCode::OK);
+ assert_eq!(b["invalidated"], json!(false));
+ assert_eq!(b["already_invalid_at"], json!(INVALID_AT));
+
+ // Belief BEFORE the invalidation instant: all four §8.5 edges.
+ let (_, before) =
+ do_ego(&state, "notes", ego_params("note-alpha", 1_753_640_000_000)).await;
+ assert_eq!(before["edges"].as_array().unwrap().len(), 4);
+ assert_eq!(before["not_shown"]["expired_excluded"], json!(0));
+
+ // Belief AFTER: three edges, the exclusion counted.
+ let (_, after) = do_ego(&state, "notes", ego_params("note-alpha", AS_OF)).await;
+ let ids: Vec<&str> = after["edges"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|e| e["edge_id"].as_str().unwrap())
+ .collect();
+ assert_eq!(
+ ids,
+ vec![FIXTURE_IDS[1], FIXTURE_IDS[3], FIXTURE_IDS[4]],
+ "invalidated edge must disappear at as_of >= invalid_at"
+ );
+ assert_eq!(after["not_shown"]["expired_excluded"], json!(1));
+
+ // include_expired=true: the edge returns, carrying its bi-temporal pair.
+ let mut p = ego_params("note-alpha", AS_OF);
+ p.include_expired = Some(true);
+ let (_, all) = do_ego(&state, "notes", p).await;
+ let edges = all["edges"].as_array().unwrap();
+ assert_eq!(edges.len(), 4);
+ let inv = edges
+ .iter()
+ .find(|e| e["edge_id"] == json!(FIXTURE_IDS[0]))
+ .expect("include_expired returns the invalidated edge");
+ assert_eq!(inv["invalid_at"], json!(INVALID_AT));
+ assert!(inv["expired_at"].as_i64().unwrap() > 0);
+
+ // Unknown edge → 404 with the normative message.
+ let (s, b) = do_unlink(&state, "notes", "deadbeef", None).await;
+ assert_eq!(s, StatusCode::NOT_FOUND);
+ assert!(b["error"]["reason"]
+ .as_str()
+ .unwrap()
+ .contains("does not exist in brain 'notes'"));
+ }
+
+ /// §3.5/§4.6: a 3-hop request is a 400 carrying the not-a-graph-database
+ /// sentence; hops=0 likewise; an unknown brain is a 404.
+ #[tokio::test]
+ async fn ego_bounds_and_unknown_brain() {
+ let state = test_state();
+ link_fixture(&state).await;
+
+ for bad_hops in [0u64, 3] {
+ let mut p = ego_params("note-alpha", AS_OF);
+ p.hops = Some(bad_hops);
+ let (s, b) = do_ego(&state, "notes", p).await;
+ assert_eq!(s, StatusCode::BAD_REQUEST, "hops={bad_hops}");
+ assert!(
+ b["error"]["reason"]
+ .as_str()
+ .unwrap()
+ .contains("not a graph database"),
+ "hops={bad_hops} must carry the §4.6 sentence: {b}"
+ );
+ }
+
+ let (s, _) = do_ego(&state, "nope", ego_params("x", AS_OF)).await;
+ assert_eq!(s, StatusCode::NOT_FOUND);
+
+ // hops=2 composes: the fixture's full 8-edge closure from note-alpha.
+ let mut p = ego_params("note-alpha", AS_OF);
+ p.hops = Some(2);
+ let (s, b) = do_ego(&state, "notes", p).await;
+ assert_eq!(s, StatusCode::OK);
+ assert_eq!(b["edges"].as_array().unwrap().len(), 8);
+ }
+
+ /// §4.4: overview counts for the fixture, before and after one
+ /// invalidation; unknown brain → exists:false 404.
+ #[tokio::test]
+ async fn overview_counts_the_fixture() {
+ let state = test_state();
+ link_fixture(&state).await;
+
+ let ov = |as_of: i64| {
+ let state = state.clone();
+ async move {
+ let resp = overview(
+ State(state.clone()),
+ Path("notes".to_string()),
+ Query(OverviewParams {
+ as_of: Some(as_of.to_string()),
+ ..Default::default()
+ }),
+ )
+ .await;
+ drain_json(resp).await
+ }
+ };
+
+ let (s, b) = ov(AS_OF).await;
+ assert_eq!(s, StatusCode::OK, "{b}");
+ assert_eq!(b["contract"], json!(GRAPH_CONTRACT));
+ assert_eq!(b["exists"], json!(true));
+ assert_eq!(b["nodes_index"], json!(".xerj-memory-notes"));
+ assert_eq!(b["embedder"], json!("lexical-feature-hash"));
+ assert_eq!(
+ b["edges"],
+ json!({ "total": 8, "live": 8, "invalidated": 0 })
+ );
+ let type_counts: BTreeMap<&str, u64> = b["types"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|t| (t["type"].as_str().unwrap(), t["live"].as_u64().unwrap()))
+ .collect();
+ assert_eq!(
+ type_counts,
+ BTreeMap::from([("wikilink", 4), ("same_dir", 4)])
+ );
+ let det_counts: BTreeMap<&str, u64> = b["detectors"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|d| (d["detector"].as_str().unwrap(), d["live"].as_u64().unwrap()))
+ .collect();
+ assert_eq!(
+ det_counts,
+ BTreeMap::from([("wikilink@1", 4), ("samedir@1", 4)])
+ );
+ // Hubs: note-alpha teaches 3 outgoing edges; note-gamma receives 3.
+ assert_eq!(
+ b["hubs"]["out"][0],
+ json!({ "id": "note-alpha", "live_edges": 3 })
+ );
+ assert_eq!(
+ b["hubs"]["in"][0],
+ json!({ "id": "note-gamma", "live_edges": 3 })
+ );
+ // One day bucket holds all 8 assertions (T0 floored to its UTC day).
+ assert_eq!(
+ b["created_over_time"],
+ json!([{ "t": 1753574400000i64, "count": 8 }])
+ );
+ assert_eq!(
+ b["not_shown"],
+ json!({
+ "types_not_listed": 0, "detectors_not_listed": 0,
+ "hubs_out_not_listed": 0, "hubs_in_not_listed": 0
+ })
+ );
+
+ // Invalidate one edge: total stays 8 (nothing is deleted), live drops.
+ let (_, r) = do_unlink(
+ &state,
+ "notes",
+ FIXTURE_IDS[0],
+ Some(&INVALID_AT.to_string()),
+ )
+ .await;
+ assert_eq!(r["invalidated"], json!(true));
+ let (_, b) = ov(AS_OF).await;
+ assert_eq!(
+ b["edges"],
+ json!({ "total": 8, "live": 7, "invalidated": 1 })
+ );
+ // …but the belief BEFORE the invalidation still counts all 8 live.
+ let (_, b) = ov(1_753_640_000_000).await;
+ assert_eq!(
+ b["edges"],
+ json!({ "total": 8, "live": 8, "invalidated": 0 })
+ );
+
+ let resp = overview(
+ State(state.clone()),
+ Path("nope".to_string()),
+ Query(OverviewParams::default()),
+ )
+ .await;
+ let (s, b) = drain_json(resp).await;
+ assert_eq!(s, StatusCode::NOT_FOUND);
+ assert_eq!(
+ b,
+ json!({ "brain": "nope", "contract": GRAPH_CONTRACT, "exists": false })
+ );
+ }
+}
diff --git a/engine/crates/xerj-api/src/lib.rs b/engine/crates/xerj-api/src/lib.rs
index f7dafae11..fd50a0830 100644
--- a/engine/crates/xerj-api/src/lib.rs
+++ b/engine/crates/xerj-api/src/lib.rs
@@ -61,6 +61,7 @@ pub mod binary_protocol;
pub mod error;
pub mod es_compat;
pub mod extract;
+pub mod graph_api;
pub mod memory_api;
pub mod native;
pub mod responses;
diff --git a/engine/crates/xerj-api/src/memory_api.rs b/engine/crates/xerj-api/src/memory_api.rs
index 1fd20497c..828519271 100644
--- a/engine/crates/xerj-api/src/memory_api.rs
+++ b/engine/crates/xerj-api/src/memory_api.rs
@@ -120,6 +120,13 @@ fn validate_namespace(ns: &str) -> Result<(), String> {
if ns.contains("..") {
return Err("namespace must not contain '..'".into());
}
+ // Second-brain collision guard (SECOND_BRAIN_SPEC §1): brain `B` keeps its
+ // graph edges in `.xerj-memory-{B}-edges`, so a namespace ending in
+ // `-edges` would silently write memories into another brain's edge index.
+ // Deliberate breaking change — record in the release notes.
+ if ns.ends_with("-edges") {
+ return Err("namespace suffix '-edges' is reserved for graph edge indices".into());
+ }
Ok(())
}
@@ -424,8 +431,43 @@ pub struct RecallBody {
/// Absent → existing relevance-only behavior is preserved exactly.
#[serde(default)]
pub recency_weight: Option<f32>,
+ /// Optional graph coupling for recall (SECOND_BRAIN_SPEC §5). The
+ /// namespace's brain is the namespace itself: edges live in
+ /// `.xerj-memory-{ns}-edges`. Absent → behavior is bit-identical to a
+ /// graph-less recall.
+ #[serde(default)]
+ pub graph: Option<GraphRecallOpts>,
+}
+
+/// Graph coupling options for `_recall` (SECOND_BRAIN_SPEC §5).
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GraphRecallOpts {
+ /// "restrict" | "blend" (required). `restrict` = recall only within reach
+ /// of the seeds; `blend` = let graph proximity pull related memories up.
+ pub mode: String,
+ /// Seed node ids. REQUIRED for restrict (400 if absent/empty).
+ /// Optional for blend (default: ids of the top-5 base-recall hits).
+ #[serde(default)]
+ pub seeds: Option<Vec<String>>,
+ /// 1 (default) or 2.
+ #[serde(default)]
+ pub hops: Option<u8>,
+ /// Edge-type allowlist.
+ #[serde(default)]
+ pub types: Option<Vec<String>>,
+ /// Blend weight in [0,1], default 0.3. Ignored for restrict.
+ #[serde(default)]
+ pub weight: Option<f32>,
+ /// Bi-temporal cut, default now. Epoch-ms number or RFC3339 string.
+ #[serde(default)]
+ pub as_of: Option<Value>,
}
+/// Hard ceiling on the reachable-id set folded into a `restrict` filter (the
+/// `ids` query stays a bounded doc-values prefilter, not an unbounded OR).
+const MAX_RESTRICT_IDS: usize = 10_000;
+
/// `POST /_memory/{namespace}/_recall` — recall the top-k relevant memories.
pub async fn recall(
State(state): State<AppState>,
@@ -442,7 +484,7 @@ pub async fn recall(
// score 1.0. (Unknown keys are already rejected at deserialization via
// `deny_unknown_fields`.) Recent-memory listing lives at
// `GET /_memory/{namespace}`, which needs no query.
- let Some(body) = body.0 else {
+ let Some(mut body) = body.0 else {
return error_response(
StatusCode::BAD_REQUEST,
"recall requires a JSON body with exactly one of `vector` (query \
@@ -483,15 +525,80 @@ pub async fn recall(
// Recency blending needs a wider candidate pool than the final k so the
// re-rank can actually promote recent-but-slightly-less-relevant memories.
let recency_weight = body.recency_weight.map(|w| w.clamp(0.0, 1.0));
+ // Optional graph coupling (SECOND_BRAIN_SPEC §5): validate up front so a
+ // bad mode / out-of-bounds hops fails fast (with the §4.6 wording), before
+ // any search runs.
+ let graph_ctx = match parse_graph_opts(body.graph.as_ref()) {
+ Ok(g) => g,
+ Err(resp) => return *resp,
+ };
let fetch = match recency_weight {
Some(_) => (k * 4).max(50),
None => k,
};
+ // Graph blend also needs a wider pool than k: proximity can only promote
+ // candidates that were fetched (same over-fetch convention as recency).
+ let fetch = match &graph_ctx {
+ Some(g) if !g.restrict => fetch.max((k * 4).max(50)),
+ _ => fetch,
+ };
let index = backing_index(&namespace);
+ let edges_index_name = format!("{MEMORY_PREFIX}{namespace}-edges");
+ let caller_filter = body.filter.take();
+
+ // Graph restrict: expand the seeds FIRST and fold the reachable set into
+ // the metadata filter as an `ids` clause — recall itself is unchanged, it
+ // just runs over a graph-bounded universe. A missing edges index is NOT
+ // an error: recall proceeds ungated with the honesty flagged in-band (an
+ // agent must be able to opt into graph recall before its first link
+ // exists).
+ let mut restrict_expansion: Option<GraphExpansion> = None;
+ let filter_opt: Option<Value> = match &graph_ctx {
+ Some(g) if g.restrict => {
+ let seeds = g.seeds.clone().unwrap_or_default(); // validated non-empty
+ match expand_graph(&state, &edges_index_name, &seeds, g) {
+ Err(resp) => return *resp,
+ Ok(None) => caller_filter,
+ Ok(Some(exp)) => {
+ let ids = json!({ "ids": { "values": &exp.reachable } });
+ let folded = match caller_filter {
+ Some(f) => json!({ "bool": { "filter": [f, ids] } }),
+ None => json!({ "bool": { "filter": [ids] } }),
+ };
+ restrict_expansion = Some(exp);
+ Some(folded)
+ }
+ }
+ }
+ _ => caller_filter,
+ };
- // Unknown namespace → no memories (also enforces isolation cleanly).
+ // Unknown namespace → no memories (also enforces isolation cleanly). The
+ // graph object stays honest even here: the edges index can exist without
+ // the memory index (a brain linked before its first memory was stored),
+ // so `no_edges_index` is only claimed when the edges index truly is
+ // absent — for blend with explicit seeds that means actually expanding.
if !index_exists(&state, &index) {
- return Json(json!({ "hits": [], "namespace": namespace })).into_response();
+ let mut resp = json!({ "hits": [], "namespace": namespace });
+ if let Some(g) = &graph_ctx {
+ let seeds = g.seeds.clone().unwrap_or_default();
+ let expansion = if g.restrict {
+ restrict_expansion
+ } else if seeds.is_empty() {
+ if index_exists(&state, &edges_index_name) {
+ Some(GraphExpansion::default())
+ } else {
+ None
+ }
+ } else {
+ match expand_graph(&state, &edges_index_name, &seeds, g) {
+ Err(resp) => return *resp,
+ Ok(e) => e,
+ }
+ };
+ resp["graph"] = graph_obj(g, &seeds, expansion.as_ref());
+ }
+ return Json(resp).into_response();
}
// Build the search body, reusing the proven kNN / BM25 / filter paths.
@@ -503,7 +610,7 @@ pub async fn recall(
if let Some(vec) = body.vector {
// (1) Caller-supplied embedding → pure kNN over the stored `vector`.
let knn = json!({ "field": "vector", "query_vector": vec, "k": fetch });
- match body.filter {
+ match filter_opt {
Some(filter) => {
// kNN with a metadata pre-filter: express kNN as a bool `must`
// clause so the `filter` narrows the candidate set.
@@ -535,7 +642,7 @@ pub async fn recall(
// rather than wrapping in a `bool` — a `semantic` node nested in a
// `bool` is not dispatched to the vector path.
let mut semantic = json!({ "field": "text", "query": q, "k": fetch });
- if let Some(filter) = body.filter {
+ if let Some(filter) = filter_opt {
semantic["filter"] = filter;
}
search_body.query = Some(json!({ "semantic": semantic }));
@@ -545,7 +652,7 @@ pub async fn recall(
Some(q) if !q.is_empty() => json!({ "match": { "text": q } }),
_ => json!({ "match_all": {} }),
};
- search_body.query = Some(match body.filter {
+ search_body.query = Some(match filter_opt {
Some(filter) => json!({ "bool": { "must": [ inner ], "filter": [ filter ] } }),
None => inner,
});
@@ -560,16 +667,285 @@ pub async fn recall(
.await
.into_response();
- let (status, body) = drain_json(resp).await;
+ let (status, response) = drain_json(resp).await;
if !status.is_success() {
- return error_response(status, format!("recall failed: {body}"));
+ return error_response(status, format!("recall failed: {response}"));
}
- let hits = match recency_weight {
- Some(w) => blend_recency(&body, w, k),
- None => extract_hits(&body),
+ let (hits, graph_out) = match &graph_ctx {
+ // No graph coupling → bit-identical to the graph-less recall.
+ None => {
+ let hits = match recency_weight {
+ Some(w) => blend_recency(&response, w, k),
+ None => extract_hits(&response),
+ };
+ (hits, None)
+ }
+ // restrict: the search already ran over the graph-bounded universe;
+ // hit shaping is unchanged, the response just gains the graph object.
+ Some(g) if g.restrict => {
+ let hits = match recency_weight {
+ Some(w) => blend_recency(&response, w, k),
+ None => extract_hits(&response),
+ };
+ let seeds = g.seeds.clone().unwrap_or_default();
+ (
+ hits,
+ Some(graph_obj(g, &seeds, restrict_expansion.as_ref())),
+ )
+ }
+ // blend: expand (seeds given, or the top-5 base hits), then re-rank
+ // the fetched candidates by (1-w)·norm_score + w·proximity. The graph
+ // blend applies FIRST, then the existing recency blend over the
+ // graph-blended ordering — each re-rank is order+truncate only, so
+ // they compose.
+ Some(g) => {
+ let raw: Vec<&Value> = response
+ .pointer("/hits/hits")
+ .and_then(Value::as_array)
+ .map(|a| a.iter().collect())
+ .unwrap_or_default();
+ let seeds: Vec<String> = match &g.seeds {
+ Some(s) if !s.is_empty() => s.clone(),
+ _ => raw
+ .iter()
+ .take(5)
+ .filter_map(|h| h.get("_id").and_then(Value::as_str))
+ .map(String::from)
+ .collect(),
+ };
+ let expansion = if seeds.is_empty() {
+ // No seeds derivable (empty base recall): nothing to expand.
+ // Distinguish "no edges index" (flagged) from "no seeds".
+ if index_exists(&state, &edges_index_name) {
+ Some(GraphExpansion::default())
+ } else {
+ None
+ }
+ } else {
+ match expand_graph(&state, &edges_index_name, &seeds, g) {
+ Err(resp) => return *resp,
+ Ok(e) => e,
+ }
+ };
+ let graph_ranked: Vec<&Value> = match &expansion {
+ Some(exp) => rank_by_proximity(&raw, &exp.proximity, g.weight, k),
+ // No edges index → recall proceeds ungated (base order).
+ None => raw.clone(),
+ };
+ let final_ranked: Vec<&Value> = match recency_weight {
+ Some(w) => rank_by_recency(&graph_ranked, f64::from(w), k),
+ None => graph_ranked.into_iter().take(k).collect(),
+ };
+ let hits: Vec<Value> = final_ranked
+ .into_iter()
+ .map(|h| {
+ let mut m = map_hit(h);
+ let id = h.get("_id").and_then(Value::as_str).unwrap_or("");
+ let prox = expansion
+ .as_ref()
+ .and_then(|e| e.proximity.get(id))
+ .copied()
+ .unwrap_or(0.0);
+ m["graph_proximity"] = json!(prox);
+ m
+ })
+ .collect();
+ (hits, Some(graph_obj(g, &seeds, expansion.as_ref())))
+ }
};
- Json(json!({ "hits": hits, "namespace": namespace })).into_response()
+ let mut resp = json!({ "hits": hits, "namespace": namespace });
+ if let Some(gobj) = graph_out {
+ resp["graph"] = gobj;
+ }
+ Json(resp).into_response()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Graph coupling (SECOND_BRAIN_SPEC §5)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Parsed + validated `graph` recall options.
+struct GraphCtx {
+ /// true = restrict, false = blend.
+ restrict: bool,
+ seeds: Option<Vec<String>>,
+ hops: u8,
+ types: Option<Vec<String>>,
+ /// Blend weight in [0,1] (ignored for restrict).
+ weight: f64,
+ as_of_ms: i64,
+}
+
+/// One completed expansion over the namespace's edges index.
+#[derive(Default)]
+struct GraphExpansion {
+ /// Reachable node ids (seeds first), clipped to [`MAX_RESTRICT_IDS`].
+ reachable: Vec<String>,
+ /// node id → graph proximity in [0,1]: seeds = 1.0, a node reached at hop
+ /// h via edge e = max over paths of `0.5^h * clamp(e.weight, 0, 1)`.
+ proximity: std::collections::HashMap<String, f64>,
+ stats: xerj_engine::graph::GraphExpandStats,
+ reachable_clipped: u64,
+}
+
+/// Validate the `graph` options (400s carry the memory_error shape — this
+/// endpoint keeps its existing error type; the hops bound carries the §4.6
+/// not-a-graph-database wording).
+fn parse_graph_opts(opts: Option<&GraphRecallOpts>) -> Result<Option<GraphCtx>, Box<Response>> {
+ let Some(o) = opts else { return Ok(None) };
+ let restrict = match o.mode.as_str() {
+ "restrict" => true,
+ "blend" => false,
+ other => {
+ return Err(Box::new(error_response(
+ StatusCode::BAD_REQUEST,
+ format!("graph.mode must be 'restrict' or 'blend' (got '{other}')"),
+ )));
+ }
+ };
+ if restrict && o.seeds.as_deref().is_none_or(<[String]>::is_empty) {
+ return Err(Box::new(error_response(
+ StatusCode::BAD_REQUEST,
+ "graph.mode 'restrict' requires non-empty graph.seeds",
+ )));
+ }
+ let hops = o.hops.unwrap_or(1);
+ if hops == 0 || hops > 2 {
+ return Err(Box::new(error_response(
+ StatusCode::BAD_REQUEST,
+ xerj_engine::graph::GRAPH_HOPS_CAP_REASON,
+ )));
+ }
+ let as_of_ms = match &o.as_of {
+ None => chrono::Utc::now().timestamp_millis(),
+ Some(v) => match parse_epoch_ms(v) {
+ Some(ms) => ms,
+ None => {
+ return Err(Box::new(error_response(
+ StatusCode::BAD_REQUEST,
+ "graph.as_of must be an epoch-ms number or an RFC3339 string",
+ )));
+ }
+ },
+ };
+ Ok(Some(GraphCtx {
+ restrict,
+ seeds: o.seeds.clone(),
+ hops,
+ types: o.types.clone(),
+ weight: f64::from(o.weight.unwrap_or(0.3)).clamp(0.0, 1.0),
+ as_of_ms,
+ }))
+}
+
+/// Epoch-ms from a JSON number or an RFC3339 string (inputs accept both;
+/// outputs are always numbers).
+fn parse_epoch_ms(v: &Value) -> Option<i64> {
+ match v {
+ Value::Number(_) => v.as_i64().or_else(|| v.as_f64().map(|f| f as i64)),
+ Value::String(s) => {
+ if let Ok(n) = s.parse::<i64>() {
+ return Some(n);
+ }
+ chrono::DateTime::parse_from_rfc3339(s)
+ .ok()
+ .map(|dt| dt.timestamp_millis())
+ }
+ _ => None,
+ }
+}
+
+/// Expand `seeds` over the namespace's edges index (direction Both, no
+/// expired edges). `Ok(None)` = the edges index does not exist — the caller
+/// proceeds ungated with the honesty flagged, per §5.
+fn expand_graph(
+ state: &AppState,
+ edges_index: &str,
+ seeds: &[String],
+ g: &GraphCtx,
+) -> Result<Option<GraphExpansion>, Box<Response>> {
+ use xerj_engine::graph::{GraphDirection, GraphExpandRequest};
+ let Ok(idx) = state.engine.get_index(edges_index) else {
+ return Ok(None);
+ };
+ let req = GraphExpandRequest {
+ frontier: seeds.to_vec(),
+ hops: g.hops,
+ direction: GraphDirection::Both,
+ types: g.types.clone(),
+ as_of_ms: g.as_of_ms,
+ include_expired: false,
+ max_result_edges: MAX_RESTRICT_IDS,
+ };
+ let res = match idx.graph_expand(&req) {
+ Ok(r) => r,
+ Err(e) => {
+ return Err(Box::new(error_response(
+ StatusCode::BAD_REQUEST,
+ e.to_string(),
+ )))
+ }
+ };
+ // Proximity: seeds anchor at 1.0; every edge contributes
+ // `0.5^hop * clamp(weight, 0, 1)` to both endpoints, max over paths
+ // (deterministic; a seed can never be demoted since 0.5^h·w ≤ 0.5 < 1).
+ let mut proximity: std::collections::HashMap<String, f64> =
+ seeds.iter().map(|s| (s.clone(), 1.0)).collect();
+ for e in &res.edges {
+ let p = 0.5f64.powi(i32::from(e.hop)) * e.weight.clamp(0.0, 1.0);
+ for id in [&e.src, &e.dst] {
+ let entry = proximity.entry(id.clone()).or_insert(0.0);
+ if p > *entry {
+ *entry = p;
+ }
+ }
+ }
+ let mut reachable = res.reachable;
+ let mut reachable_clipped = 0u64;
+ if reachable.len() > MAX_RESTRICT_IDS {
+ reachable_clipped = (reachable.len() - MAX_RESTRICT_IDS) as u64;
+ reachable.truncate(MAX_RESTRICT_IDS);
+ }
+ Ok(Some(GraphExpansion {
+ reachable,
+ proximity,
+ stats: res.stats,
+ reachable_clipped,
+ }))
+}
+
+/// The top-level `graph` response object (§5). `exp = None` means the edges
+/// index did not exist — reported in-band as `no_edges_index`, never hidden.
+fn graph_obj(g: &GraphCtx, seeds: &[String], exp: Option<&GraphExpansion>) -> Value {
+ let mode = if g.restrict { "restrict" } else { "blend" };
+ let not_shown = match exp {
+ Some(e) => json!({
+ "frontier_clipped": e.stats.frontier_clipped,
+ "edges_clipped": e.stats.edges_clipped,
+ "expired_excluded": e.stats.expired_excluded,
+ "type_filtered": e.stats.type_filtered,
+ "segments_without_columns": e.stats.segments_without_columns,
+ "reachable_clipped": e.reachable_clipped,
+ }),
+ None => json!({
+ "frontier_clipped": 0,
+ "edges_clipped": 0,
+ "expired_excluded": 0,
+ "type_filtered": 0,
+ "segments_without_columns": 0,
+ "reachable_clipped": 0,
+ "no_edges_index": true,
+ }),
+ };
+ json!({
+ "mode": mode,
+ "seeds": seeds,
+ "hops": g.hops,
+ "as_of": g.as_of_ms,
+ "reachable": exp.map(|e| e.reachable.len()).unwrap_or(0),
+ "not_shown": not_shown,
+ })
}
/// Map a single ES search hit into the agent-memory hit shape.
@@ -611,7 +987,32 @@ fn blend_recency(search_response: &Value, w: f32, k: usize) -> Vec<Value> {
Some(h) if !h.is_empty() => h,
_ => return Vec::new(),
};
+ let refs: Vec<&Value> = hits.iter().collect();
+ rank_by_recency(&refs, f64::from(w), k)
+ .into_iter()
+ .map(map_hit)
+ .collect()
+}
+/// Min-max normalize a value against a range; a uniform range (hi == lo)
+/// normalizes to 0.0 so that dimension contributes nothing to a blend rather
+/// than dividing by zero.
+fn min_max_norm(v: f64, lo: f64, hi: f64) -> f64 {
+ if hi > lo {
+ (v - lo) / (hi - lo)
+ } else {
+ 0.0
+ }
+}
+
+/// Order+truncate re-rank by `blended = (1 - w)·norm_score + w·norm_recency`
+/// (both min-max normalized across the candidate set). Returns raw hit refs
+/// so re-ranks compose — the recall handler applies this AFTER the graph
+/// blend when both are requested.
+fn rank_by_recency<'a>(hits: &[&'a Value], w: f64, k: usize) -> Vec<&'a Value> {
+ if hits.is_empty() {
+ return Vec::new();
+ }
let scores: Vec<f64> = hits
.iter()
.map(|h| h.get("_score").and_then(Value::as_f64).unwrap_or(0.0))
@@ -624,31 +1025,61 @@ fn blend_recency(search_response: &Value, w: f32, k: usize) -> Vec<Value> {
.unwrap_or(0.0)
})
.collect();
-
let smin = scores.iter().copied().fold(f64::INFINITY, f64::min);
let smax = scores.iter().copied().fold(f64::NEG_INFINITY, f64::max);
let tmin = times.iter().copied().fold(f64::INFINITY, f64::min);
let tmax = times.iter().copied().fold(f64::NEG_INFINITY, f64::max);
- // Uniform values (hi == lo) normalize to 0.0 so that dimension contributes
- // nothing to the blend rather than dividing by zero.
- let norm = |v: f64, lo: f64, hi: f64| if hi > lo { (v - lo) / (hi - lo) } else { 0.0 };
- let w = w as f64;
let mut ranked: Vec<(f64, &Value)> = hits
.iter()
.zip(scores.iter().zip(times.iter()))
.map(|(h, (&sc, &tm))| {
- let blended = (1.0 - w) * norm(sc, smin, smax) + w * norm(tm, tmin, tmax);
- (blended, h)
+ let blended =
+ (1.0 - w) * min_max_norm(sc, smin, smax) + w * min_max_norm(tm, tmin, tmax);
+ (blended, *h)
})
.collect();
+ ranked.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
+ ranked.into_iter().take(k).map(|(_, h)| h).collect()
+}
+/// Order+truncate re-rank by `blended = (1 - w)·norm_score + w·proximity`
+/// (SECOND_BRAIN_SPEC §5 blend). `norm_score` uses the same min-max
+/// normalization as [`rank_by_recency`]; proximity is already an absolute
+/// [0,1] quantity (seed = 1.0, hop-decayed otherwise) and is deliberately NOT
+/// re-normalized. Hits absent from the proximity map contribute 0.
+fn rank_by_proximity<'a>(
+ hits: &[&'a Value],
+ proximity: &std::collections::HashMap<String, f64>,
+ w: f64,
+ k: usize,
+) -> Vec<&'a Value> {
+ if hits.is_empty() {
+ return Vec::new();
+ }
+ let scores: Vec<f64> = hits
+ .iter()
+ .map(|h| h.get("_score").and_then(Value::as_f64).unwrap_or(0.0))
+ .collect();
+ let smin = scores.iter().copied().fold(f64::INFINITY, f64::min);
+ let smax = scores.iter().copied().fold(f64::NEG_INFINITY, f64::max);
+
+ let mut ranked: Vec<(f64, &Value)> = hits
+ .iter()
+ .zip(scores.iter())
+ .map(|(h, &sc)| {
+ let prox = h
+ .get("_id")
+ .and_then(Value::as_str)
+ .and_then(|id| proximity.get(id))
+ .copied()
+ .unwrap_or(0.0);
+ let blended = (1.0 - w) * min_max_norm(sc, smin, smax) + w * prox;
+ (blended, *h)
+ })
+ .collect();
ranked.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
- ranked
- .into_iter()
- .take(k)
- .map(|(_, h)| map_hit(h))
- .collect()
+ ranked.into_iter().take(k).map(|(_, h)| h).collect()
}
// ─────────────────────────────────────────────────────────────────────────────
@@ -881,6 +1312,12 @@ mod tests {
assert!(validate_namespace("_x").is_err()); // leading underscore
assert!(validate_namespace("a/b").is_err()); // slash
assert!(validate_namespace("a..b").is_err()); // path traversal
+ // Second-brain collision guard: `POST /_memory/kb-edges` would write
+ // memories into brain `kb`'s edge index.
+ assert_eq!(
+ validate_namespace("kb-edges").unwrap_err(),
+ "namespace suffix '-edges' is reserved for graph edge indices"
+ );
}
#[tokio::test]
@@ -1208,6 +1645,255 @@ mod tests {
);
}
+ /// Link one SECOND_BRAIN_SPEC §8.3 fixture edge through the graph API
+ /// (same brain name as the memory namespace; explicit fixture timestamps
+ /// so the pinned edge_ids and the §8.6 sort order reproduce exactly).
+ async fn link_edge(state: &AppState, src: &str, dst: &str, ty: &str, weight: f64) {
+ let b: crate::graph_api::LinkBody = serde_json::from_value(json!({
+ "src": src, "dst": dst, "type": ty, "weight": weight,
+ "valid_at": 1_753_600_000_000i64, "created_at": 1_753_600_000_000i64,
+ }))
+ .unwrap();
+ let resp = crate::graph_api::link(
+ State(state.clone()),
+ Path("notes".to_string()),
+ OptionalJson(Some(b)),
+ )
+ .await;
+ let (s, body) = drain_json(resp).await;
+ assert!(s.is_success(), "fixture link {src}->{dst} failed: {body}");
+ }
+
+ /// The §8 fixture world: the five notes as memories (fixture node ids)
+ /// plus the eight §8.3 edges in brain `notes`.
+ async fn graph_fixture(state: &AppState) {
+ for (id, text) in [
+ (
+ "note-alpha",
+ "Alpha is the hub note. It links to [[beta]] and [[gamma]].",
+ ),
+ (
+ "note-beta",
+ "Beta continues the thread and references [[gamma]].",
+ ),
+ (
+ "note-gamma",
+ "Gamma is the sink note with no outgoing links.",
+ ),
+ ("note-delta", "Delta cites [[alpha]] as its source."),
+ ("note-epsilon", "Epsilon stands alone."),
+ ] {
+ let (s, _) = store_mem(state, "notes", json!({"text": text, "id": id})).await;
+ assert_eq!(s, StatusCode::CREATED);
+ }
+ for (src, dst, ty, w) in [
+ ("note-alpha", "note-beta", "wikilink", 1.0),
+ ("note-alpha", "note-gamma", "wikilink", 1.0),
+ ("note-beta", "note-gamma", "wikilink", 1.0),
+ ("note-delta", "note-alpha", "wikilink", 1.0),
+ ("note-alpha", "note-beta", "same_dir", 0.3),
+ ("note-beta", "note-delta", "same_dir", 0.3),
+ ("note-delta", "note-epsilon", "same_dir", 0.3),
+ ("note-epsilon", "note-gamma", "same_dir", 0.3),
+ ] {
+ link_edge(state, src, dst, ty, w).await;
+ }
+ }
+
+ /// SECOND_BRAIN_SPEC §5 + §8.6: `graph.mode=restrict` narrows recall to
+ /// the seeds' bounded reach; the graph object reports the expansion
+ /// honestly.
+ #[tokio::test]
+ async fn recall_graph_restrict_bounds_the_universe() {
+ let state = test_state();
+ graph_fixture(&state).await;
+
+ // Sanity: ungated recall for "note" surfaces alpha AND gamma.
+ let (_, b) = recall_mem(&state, "notes", json!({"query": "note", "k": 10})).await;
+ let ids: Vec<&str> = b["hits"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|h| h["id"].as_str().unwrap())
+ .collect();
+ assert!(ids.contains(&"note-alpha") && ids.contains(&"note-gamma"));
+ assert!(b.get("graph").is_none(), "no graph key without graph opts");
+
+ // §8.6: restrict from seed note-delta, hops 1, at the fixture as-of.
+ // 1-hop both-direction reach = {delta, alpha, epsilon, beta} — gamma
+ // is out of reach and must vanish from the hits.
+ let (s, b) = recall_mem(
+ &state,
+ "notes",
+ json!({
+ "query": "note", "k": 10,
+ "graph": {"mode": "restrict", "seeds": ["note-delta"],
+ "hops": 1, "as_of": 1_753_700_000_000i64}
+ }),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK, "{b}");
+ let ids: Vec<&str> = b["hits"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|h| h["id"].as_str().unwrap())
+ .collect();
+ assert_eq!(ids, vec!["note-alpha"], "gamma is outside the 1-hop reach");
+ let graph = &b["graph"];
+ assert_eq!(graph["mode"], json!("restrict"));
+ assert_eq!(graph["seeds"], json!(["note-delta"]));
+ assert_eq!(graph["hops"], json!(1));
+ assert_eq!(graph["as_of"], json!(1_753_700_000_000i64));
+ assert_eq!(graph["reachable"], json!(4), "§8.6: 'reachable': 4");
+ assert_eq!(graph["not_shown"]["reachable_clipped"], json!(0));
+ assert!(
+ graph["not_shown"].get("no_edges_index").is_none(),
+ "the edges index exists — no honesty flag"
+ );
+ }
+
+ /// §5 blend: graph proximity re-ranks the fetched candidates; every hit
+ /// carries `graph_proximity`; seeds derive from the base recall when
+ /// absent.
+ #[tokio::test]
+ async fn recall_graph_blend_reranks_by_proximity() {
+ let state = test_state();
+ graph_fixture(&state).await;
+
+ let (s, b) = recall_mem(
+ &state,
+ "notes",
+ json!({
+ "query": "note", "k": 10,
+ "graph": {"mode": "blend", "seeds": ["note-alpha"],
+ "weight": 0.9, "as_of": 1_753_700_000_000i64}
+ }),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK, "{b}");
+ let hits = b["hits"].as_array().unwrap();
+ assert!(!hits.is_empty());
+ // The seed itself anchors at proximity 1.0 and, at w=0.9, must
+ // outrank gamma (proximity 0.5 via the hop-1 wikilink).
+ assert_eq!(hits[0]["id"], json!("note-alpha"));
+ assert_eq!(hits[0]["graph_proximity"], json!(1.0));
+ let gamma = hits
+ .iter()
+ .find(|h| h["id"] == json!("note-gamma"))
+ .expect("gamma stays recalled (blend re-ranks, never filters)");
+ assert_eq!(gamma["graph_proximity"], json!(0.5));
+ assert_eq!(b["graph"]["mode"], json!("blend"));
+
+ // Seeds absent → derived from the top base hits, echoed back.
+ let (s, b) = recall_mem(
+ &state,
+ "notes",
+ json!({"query": "note", "k": 10, "graph": {"mode": "blend"}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK);
+ let seeds = b["graph"]["seeds"].as_array().unwrap();
+ assert!(!seeds.is_empty(), "blend derives seeds from base recall");
+ assert!(b["graph"]["reachable"].as_u64().unwrap() > 0);
+ }
+
+ /// §5: a namespace with no edges index is NOT an error — recall proceeds
+ /// ungated with `no_edges_index` flagged; malformed graph opts are loud
+ /// 400s (including the not-a-graph-database hops wording).
+ #[tokio::test]
+ async fn recall_graph_no_edges_index_and_errors() {
+ let state = test_state();
+ let (s, _) = store_mem(&state, "lonely", json!({"text": "solo memory", "id": "m1"})).await;
+ assert_eq!(s, StatusCode::CREATED);
+
+ let (s, b) = recall_mem(
+ &state,
+ "lonely",
+ json!({"query": "solo", "graph": {"mode": "restrict", "seeds": ["m1"]}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK, "{b}");
+ let ids: Vec<&str> = b["hits"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|h| h["id"].as_str().unwrap())
+ .collect();
+ assert_eq!(ids, vec!["m1"], "recall proceeds ungated");
+ assert_eq!(b["graph"]["reachable"], json!(0));
+ assert_eq!(b["graph"]["not_shown"]["no_edges_index"], json!(true));
+
+ // Unknown mode.
+ let (s, _) = recall_mem(
+ &state,
+ "lonely",
+ json!({"query": "solo", "graph": {"mode": "pagerank"}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::BAD_REQUEST);
+
+ // restrict without seeds.
+ let (s, b) = recall_mem(
+ &state,
+ "lonely",
+ json!({"query": "solo", "graph": {"mode": "restrict"}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::BAD_REQUEST);
+ assert_eq!(
+ b["error"]["reason"],
+ json!("graph.mode 'restrict' requires non-empty graph.seeds")
+ );
+
+ // hops beyond the cap → the §4.6 sentence.
+ let (s, b) = recall_mem(
+ &state,
+ "lonely",
+ json!({"query": "solo", "graph": {"mode": "blend", "hops": 3}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::BAD_REQUEST);
+ assert!(b["error"]["reason"]
+ .as_str()
+ .unwrap()
+ .contains("not a graph database"));
+
+ // The inverse corner: an edges index CAN exist before the memory
+ // index does (a brain linked before its first memory). The empty
+ // recall must NOT claim no_edges_index — that flag is a statement
+ // about the world, not a shrug.
+ let b: crate::graph_api::LinkBody = serde_json::from_value(json!({
+ "src": "g1", "dst": "g2", "type": "wikilink"
+ }))
+ .unwrap();
+ let resp = crate::graph_api::link(
+ State(state.clone()),
+ Path("ghost".to_string()),
+ OptionalJson(Some(b)),
+ )
+ .await;
+ let (s, _) = drain_json(resp).await;
+ assert_eq!(s, StatusCode::CREATED);
+ let (s, b) = recall_mem(
+ &state,
+ "ghost",
+ json!({"query": "anything", "graph": {"mode": "blend", "seeds": ["g1"]}}),
+ )
+ .await;
+ assert_eq!(s, StatusCode::OK);
+ assert_eq!(b["hits"], json!([]), "no memory index → no hits");
+ assert!(
+ b["graph"]["not_shown"].get("no_edges_index").is_none(),
+ "the edges index exists — the flag would be a lie: {b}"
+ );
+ assert_eq!(
+ b["graph"]["reachable"],
+ json!(2),
+ "expansion still reports the seeds' true reach"
+ );
+ }
+
/// Recency-blended recall: given an older perfect-relevance memory and a
/// newer near-relevance one, `recency_weight=0.9` surfaces the newer memory
/// first, while `recency_weight=0` preserves pure relevance order.
diff --git a/engine/crates/xerj-api/src/router.rs b/engine/crates/xerj-api/src/router.rs
index f6512399c..dbb70488f 100644
--- a/engine/crates/xerj-api/src/router.rs
+++ b/engine/crates/xerj-api/src/router.rs
@@ -27,7 +27,7 @@ use tracing::Level;
use uuid::Uuid;
use xerj_common::config::CorsConfig;
-use crate::{auth::auth_middleware, es_compat, memory_api, native, state::AppState};
+use crate::{auth::auth_middleware, es_compat, graph_api, memory_api, native, state::AppState};
// ─────────────────────────────────────────────────────────────────────────────
// Native xerj router (:8080)
@@ -762,6 +762,14 @@ pub fn build_es_compat_router(state: AppState) -> Router {
)
.route("/_memory/:namespace/_recall", post(memory_api::recall))
.route("/_memory/:namespace/:id", delete(memory_api::forget_one))
+ // ── Second-Brain Graph API ─────────────────────────────────────────────
+ // Edges are ordinary documents in reserved `.xerj-memory-{brain}-edges`
+ // indices; traversal is a bounded columnar expansion
+ // (Index::graph_expand), NOT a graph query language. See graph_api.rs.
+ .route("/_graph/:brain/link", post(graph_api::link))
+ .route("/_graph/:brain/link/:edge_id", delete(graph_api::unlink))
+ .route("/_graph/:brain/ego", get(graph_api::ego))
+ .route("/_graph/:brain/overview", get(graph_api::overview))
// Shared state
.with_state(state.clone())
// Middleware stack (applied outermost-last)
diff --git a/engine/crates/xerj-autoindex/src/detect/e2e.rs b/engine/crates/xerj-autoindex/src/detect/e2e.rs
index 4d8f199b7..dac17f39c 100644
--- a/engine/crates/xerj-autoindex/src/detect/e2e.rs
+++ b/engine/crates/xerj-autoindex/src/detect/e2e.rs
@@ -54,7 +54,12 @@ impl MockEs {
}
fn index(&self, name: &str) -> BTreeMap<String, Value> {
- self.docs.lock().unwrap().get(name).cloned().unwrap_or_default()
+ self.docs
+ .lock()
+ .unwrap()
+ .get(name)
+ .cloned()
+ .unwrap_or_default()
}
/// rel path → anchor node `_id`, straight from the published node docs so
@@ -169,7 +174,9 @@ fn doc_route(path: &str) -> Option<(String, String)> {
return None;
}
let id = segs.next()?;
- segs.next().is_none().then(|| (index.to_string(), id.to_string()))
+ segs.next()
+ .is_none()
+ .then(|| (index.to_string(), id.to_string()))
}
fn bulk(body: &[u8], docs: &Arc<Mutex<Docs>>) -> Value {
@@ -290,8 +297,7 @@ fn journal_graph_summary(state_dir: &Path) -> Value {
journal
.lines()
.filter_map(|l| serde_json::from_str::<Value>(l).ok())
- .filter(|v| v.get("kind").and_then(Value::as_str) == Some("finish"))
- .next_back()
+ .rfind(|v| v.get("kind").and_then(Value::as_str) == Some("finish"))
.and_then(|v| v.pointer("/summary/graph").cloned())
.expect("finish event with graph summary")
}
@@ -397,21 +403,95 @@ fn fixture_folder_end_to_end_matches_the_contract_edge_set() {
let alpha_line = "Alpha is the hub note. It links to [[beta]] and [[gamma]].";
let mut expected = vec![
// §8.2/§8.3 wikilink edges — exact quotes and byte offsets.
- expect(&anchors, "alpha.md", "beta.md", "wikilink", "wikilink@1", "1.0", "0.95", alpha_line, 35),
- expect(&anchors, "alpha.md", "gamma.md", "wikilink", "wikilink@1", "1.0", "0.95", alpha_line, 48),
- expect(&anchors, "beta.md", "gamma.md", "wikilink", "wikilink@1", "1.0", "0.95",
- "Beta continues the thread and references [[gamma]].", 41),
- expect(&anchors, "delta.md", "alpha.md", "wikilink", "wikilink@1", "1.0", "0.95",
- "Delta cites [[alpha]] as its source.", 12),
+ expect(
+ &anchors,
+ "alpha.md",
+ "beta.md",
+ "wikilink",
+ "wikilink@1",
+ "1.0",
+ "0.95",
+ alpha_line,
+ 35,
+ ),
+ expect(
+ &anchors,
+ "alpha.md",
+ "gamma.md",
+ "wikilink",
+ "wikilink@1",
+ "1.0",
+ "0.95",
+ alpha_line,
+ 48,
+ ),
+ expect(
+ &anchors,
+ "beta.md",
+ "gamma.md",
+ "wikilink",
+ "wikilink@1",
+ "1.0",
+ "0.95",
+ "Beta continues the thread and references [[gamma]].",
+ 41,
+ ),
+ expect(
+ &anchors,
+ "delta.md",
+ "alpha.md",
+ "wikilink",
+ "wikilink@1",
+ "1.0",
+ "0.95",
+ "Delta cites [[alpha]] as its source.",
+ 12,
+ ),
// §8.3 samedir chain over rel-sorted files — 4 edges, not a clique.
- expect(&anchors, "alpha.md", "beta.md", "same_dir", "samedir@1", "0.3", "0.4",
- "alpha.md and beta.md share directory .", 0),
- expect(&anchors, "beta.md", "delta.md", "same_dir", "samedir@1", "0.3", "0.4",
- "beta.md and delta.md share directory .", 0),
- expect(&anchors, "delta.md", "epsilon.md", "same_dir", "samedir@1", "0.3", "0.4",
- "delta.md and epsilon.md share directory .", 0),
- expect(&anchors, "epsilon.md", "gamma.md", "same_dir", "samedir@1", "0.3", "0.4",
- "epsilon.md and gamma.md share directory .", 0),
+ expect(
+ &anchors,
+ "alpha.md",
+ "beta.md",
+ "same_dir",
+ "samedir@1",
+ "0.3",
+ "0.4",
+ "alpha.md and beta.md share directory .",
+ 0,
+ ),
+ expect(
+ &anchors,
+ "beta.md",
+ "delta.md",
+ "same_dir",
+ "samedir@1",
+ "0.3",
+ "0.4",
+ "beta.md and delta.md share directory .",
+ 0,
+ ),
+ expect(
+ &anchors,
+ "delta.md",
+ "epsilon.md",
+ "same_dir",
+ "samedir@1",
+ "0.3",
+ "0.4",
+ "delta.md and epsilon.md share directory .",
+ 0,
+ ),
+ expect(
+ &anchors,
+ "epsilon.md",
+ "gamma.md",
+ "same_dir",
+ "samedir@1",
+ "0.3",
+ "0.4",
+ "epsilon.md and gamma.md share directory .",
+ 0,
+ ),
];
expected.sort();
assert_eq!(edge_keys(&edges), expected, "the exact §8.3 edge set");
@@ -490,7 +570,11 @@ fn dangling_wikilink_is_counted_not_silently_dropped() {
fn replaced_file_soft_invalidates_its_prior_edges() {
let corpus = tempfile::tempdir().unwrap();
let state = tempfile::tempdir().unwrap();
- fs::write(corpus.path().join("alpha.md"), "Alpha cites [[beta]] today.").unwrap();
+ fs::write(
+ corpus.path().join("alpha.md"),
+ "Alpha cites [[beta]] today.",
+ )
+ .unwrap();
fs::write(corpus.path().join("beta.md"), "Beta stands alone.").unwrap();
let es = MockEs::start();
assert_eq!(
diff --git a/engine/crates/xerj-autoindex/src/detect/href.rs b/engine/crates/xerj-autoindex/src/detect/href.rs
index 8c561df4b..ef9a44026 100644
--- a/engine/crates/xerj-autoindex/src/detect/href.rs
+++ b/engine/crates/xerj-autoindex/src/detect/href.rs
@@ -49,10 +49,7 @@ fn anchor_re() -> &'static regex::Regex {
fn scan_anchors(text: &str, mut hit: impl FnMut(usize, &str)) {
for caps in anchor_re().captures_iter(text) {
- let m = caps
- .get(1)
- .or_else(|| caps.get(2))
- .or_else(|| caps.get(3));
+ let m = caps.get(1).or_else(|| caps.get(2)).or_else(|| caps.get(3));
if let Some(m) = m {
hit(m.start(), m.as_str());
}
diff --git a/engine/crates/xerj-autoindex/src/detect/mod.rs b/engine/crates/xerj-autoindex/src/detect/mod.rs
index 201f8d35f..79fc9f87d 100644
--- a/engine/crates/xerj-autoindex/src/detect/mod.rs
+++ b/engine/crates/xerj-autoindex/src/detect/mod.rs
@@ -170,7 +170,10 @@ pub fn corpus_file(
dataset_slug: dataset_slug.to_string(),
anchor_doc_id: crate::ids::doc_id(dataset_slug, file_key, "s0"),
mtime_ms,
- dir: rel.rsplit_once('/').map(|(d, _)| d.to_string()).unwrap_or_default(),
+ dir: rel
+ .rsplit_once('/')
+ .map(|(d, _)| d.to_string())
+ .unwrap_or_default(),
family: family.to_string(),
}
}
@@ -537,12 +540,7 @@ pub fn ensure_brain_meta(
/// Each pass re-indexes its hits with `invalid_at = expired_at = now` and
/// refreshes, so repeat-until-empty converges; the pass bound turns a broken
/// endpoint into an error instead of an infinite loop.
-pub fn invalidate_prior_edges(
- es: &Es,
- edges_index: &str,
- rel: &str,
- now_ms: i64,
-) -> Result<u64> {
+pub fn invalidate_prior_edges(es: &Es, edges_index: &str, rel: &str, now_ms: i64) -> Result<u64> {
const MAX_PASSES: usize = 1_000;
let query = json!({
"query": {"bool": {
@@ -678,7 +676,10 @@ mod tests {
assert_eq!(doc["schema_version"], json!(1));
assert_eq!(doc["created_at"], json!(99));
assert_eq!(doc["evidence"]["source"], json!("a.md"));
- assert!(doc.get("invalid_at").is_none(), "unset keys must be omitted");
+ assert!(
+ doc.get("invalid_at").is_none(),
+ "unset keys must be omitted"
+ );
assert_eq!(doc["edge_id"], json!(out.edges[0].edge_id));
}
@@ -730,7 +731,10 @@ mod tests {
resolve_local(&corpus, "", "//cdn.example.com/x"),
LinkTarget::External
));
- assert!(matches!(resolve_local(&corpus, "", "#anchor"), LinkTarget::Empty));
+ assert!(matches!(
+ resolve_local(&corpus, "", "#anchor"),
+ LinkTarget::Empty
+ ));
assert!(matches!(
resolve_local(&corpus, "", "../../escape.md"),
LinkTarget::Miss
diff --git a/engine/crates/xerj-autoindex/src/detect/samedir.rs b/engine/crates/xerj-autoindex/src/detect/samedir.rs
index 6cc00624e..69ea155a4 100644
--- a/engine/crates/xerj-autoindex/src/detect/samedir.rs
+++ b/engine/crates/xerj-autoindex/src/detect/samedir.rs
@@ -49,10 +49,7 @@ impl EdgeDetector for SameDir {
confidence: CONFIDENCE,
valid_at_ms: left.mtime_ms,
src_file: left.rel.clone(),
- quote: format!(
- "{} and {} share directory {shown_dir}",
- left.rel, right.rel
- ),
+ quote: format!("{} and {} share directory {shown_dir}", left.rel, right.rel),
offset: 0,
});
}
@@ -69,7 +66,9 @@ mod tests {
let corpus = CorpusIndex::build(
rels.iter()
.enumerate()
- .map(|(i, rel)| corpus_file(rel, &format!("k{i}"), "notes", "txt-prose", 100 + i as i64))
+ .map(|(i, rel)| {
+ corpus_file(rel, &format!("k{i}"), "notes", "txt-prose", 100 + i as i64)
+ })
.collect(),
);
let mut out = Vec::new();
diff --git a/engine/crates/xerj-autoindex/src/detect/wikilink.rs b/engine/crates/xerj-autoindex/src/detect/wikilink.rs
index 34e1d4aca..06dd9f35e 100644
--- a/engine/crates/xerj-autoindex/src/detect/wikilink.rs
+++ b/engine/crates/xerj-autoindex/src/detect/wikilink.rs
@@ -147,9 +147,14 @@ mod tests {
#[test]
fn fixture_offsets_and_targets() {
let corpus = corpus();
- let (out, c) = run(&corpus, "Alpha is the hub note. It links to [[beta]] and [[gamma]].");
- // beta resolves ambiguously (beta.md vs sub/beta.txt) to the smallest
- // rel; gamma is dangling and must be counted, not emitted.
+ let (out, c) = run(
+ &corpus,
+ "Alpha is the hub note. It links to [[beta]] and [[gamma]].",
+ );
+ // §6.5 resolution order: `[[beta]]` is an exact rel-path match minus
+ // extension (beta.md) — ONE candidate, so it is NOT ambiguous; the
+ // stem table (where sub/beta.txt would compete) is never consulted.
+ // gamma is dangling and must be counted, not emitted.
assert_eq!(out.len(), 1);
assert_eq!(out[0].dst, corpus.files["beta.md"].anchor_doc_id);
assert_eq!(out[0].offset, 35);
@@ -158,7 +163,10 @@ mod tests {
"Alpha is the hub note. It links to [[beta]] and [[gamma]]."
);
assert_eq!(c.unresolved, 1);
- assert_eq!(c.ambiguous, 1);
+ assert_eq!(
+ c.ambiguous, 0,
+ "exact rel-without-extension wins outright (ambiguity is a stem-table concept)"
+ );
}
#[test]
diff --git a/engine/crates/xerj-autoindex/src/lib.rs b/engine/crates/xerj-autoindex/src/lib.rs
index a441146f4..91831ffd9 100644
--- a/engine/crates/xerj-autoindex/src/lib.rs
+++ b/engine/crates/xerj-autoindex/src/lib.rs
@@ -28,6 +28,9 @@ use std::sync::Mutex;
use std::time::Instant;
use cli::{Cmd, IndexCfg, MapCfg, StatusCfg};
+// Trait must be in scope for `href_raw.counters()` (a concrete `Href`, not a
+// `Box<dyn EdgeDetector>` like the registry entries).
+use detect::EdgeDetector as _;
use esclient::Es;
use sniff::{Family, Sniffed};
use state::{FileAssignment, FileDone, JunkFile, Plan, PlanDataset};
@@ -876,10 +879,7 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
let brain = match &cfg.brain {
Some(b) => b.clone(),
None => {
- let base = cfg
- .root
- .canonicalize()
- .unwrap_or_else(|_| cfg.root.clone());
+ let base = cfg.root.canonicalize().unwrap_or_else(|_| cfg.root.clone());
let name = base
.file_name()
.map(|s| s.to_string_lossy().to_string())
@@ -924,7 +924,9 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
.and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
.map(|d| d.as_millis() as i64)
.unwrap_or(0);
- corpus_files.push(detect::corpus_file(&f.rel, key, &slug, &fa.family, mtime_ms));
+ corpus_files.push(detect::corpus_file(
+ &f.rel, key, &slug, &fa.family, mtime_ms,
+ ));
}
let corpus = detect::CorpusIndex::build(corpus_files);
let detectors = detect::default_detectors();
@@ -957,8 +959,9 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
replaced_rels.sort_unstable();
replaced_rels.dedup();
for rel in replaced_rels {
- invalidated += detect::invalidate_prior_edges(&es, &edges_index, rel, created_at_ms)
- .with_context(|| format!("invalidate prior edges taught by {rel}"))?;
+ invalidated +=
+ detect::invalidate_prior_edges(&es, &edges_index, rel, created_at_ms)
+ .with_context(|| format!("invalidate prior edges taught by {rel}"))?;
}
}
@@ -1205,11 +1208,8 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
// content::verify below still covers this re-read.
if send_err.is_none() {
if let Some(gr) = graph.as_ref() {
- if let Some(cf) = gr
- .corpus
- .files
- .get(&f.rel)
- .filter(|cf| cf.family == "html")
+ if let Some(cf) =
+ gr.corpus.files.get(&f.rel).filter(|cf| cf.family == "html")
{
if let Ok(Some(bytes)) =
extract::read_whole(&f.path, sn.gzip, extract::MAX_WHOLE_FILE)
@@ -1338,7 +1338,8 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
if let Some(gr) = graph.as_ref() {
let out =
detect::assemble(&edge_drafts, &gr.edges_index, gr.created_at_ms);
- gr.self_dropped.fetch_add(out.self_dropped, Ordering::Relaxed);
+ gr.self_dropped
+ .fetch_add(out.self_dropped, Ordering::Relaxed);
let mut ebuf: Vec<u8> = Vec::new();
for edge in &out.edges {
ebuf.extend_from_slice(&edge.ndjson);
@@ -1772,11 +1773,7 @@ fn run_index(cfg: IndexCfg) -> Result<i32> {
if let Some(g) = &graph_summary {
let by: Vec<String> = g["by_detector"]
.as_object()
- .map(|m| {
- m.iter()
- .map(|(tag, n)| format!("{tag} {n}"))
- .collect()
- })
+ .map(|m| m.iter().map(|(tag, n)| format!("{tag} {n}")).collect())
.unwrap_or_default();
println!(
"graph: {} edges → {} ({}); {} unresolved, {} ambiguous, {} self-dropped, {} invalidated",
@@ -1949,7 +1946,9 @@ fn run_map(cfg: MapCfg) -> Result<i32> {
.and_then(|v| v.pointer("/hits/total/value").and_then(Value::as_u64));
match live {
Some(n) => println!("\ngraph: {n} live edges in {edges_index} (brain {brain})"),
- None => println!("\ngraph: brain {brain} — edges index {edges_index} unreachable"),
+ None => {
+ println!("\ngraph: brain {brain} — edges index {edges_index} unreachable")
+ }
}
}
}
diff --git a/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs b/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs
index ce305316f..9e5b9271f 100644
--- a/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs
+++ b/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs
@@ -1,4 +1,4 @@
-//! Dashboards: rich panel schema round-trip, first-launch seeding of the 13
+//! Dashboards: rich panel schema round-trip, first-launch seeding of the 14
//! built-ins as editable backend data, managed-default edit/delete rules, and
//! the bulk endpoint.
//!
@@ -143,7 +143,7 @@ async fn list_dash(app: &TestApp) -> Value {
// ─────────────────────────────────────────────────────────────────────────────
#[tokio::test]
-async fn seeds_thirteen_editable_defaults_on_first_boot() {
+async fn seeds_fourteen_editable_defaults_on_first_boot() {
let app = boot().await;
let body = list_dash(&app).await;
let arr = body["data"]["dashboards"].as_array().unwrap();
@@ -152,7 +152,7 @@ async fn seeds_thirteen_editable_defaults_on_first_boot() {
.iter()
.filter(|d| d["id"].as_str().unwrap_or("").starts_with("default-"))
.collect();
- assert_eq!(defaults.len(), 13, "must seed exactly 13 defaults: {body}");
+ assert_eq!(defaults.len(), 14, "must seed exactly 14 defaults: {body}");
// Every registry dashboard is present by its stable id.
for id in [
@@ -160,6 +160,7 @@ async fn seeds_thirteen_editable_defaults_on_first_boot() {
"default-rag-quality",
"default-vector-index",
"default-agent-memory",
+ "default-second-brain",
"default-logs-overview",
"default-anomaly-detect",
"default-ingest-pipeline",
@@ -251,7 +252,7 @@ async fn seeding_is_idempotent_and_preserves_edits() {
.iter()
.filter(|d| d["id"].as_str().unwrap_or("").starts_with("default-"))
.collect();
- assert_eq!(defaults.len(), 13, "re-seed must not duplicate defaults");
+ assert_eq!(defaults.len(), 14, "re-seed must not duplicate defaults");
// The edit survived the re-seed.
let (_, sys) = get_dash(&app, "default-system").await;
diff --git a/engine/crates/xerj-engine/src/graph.rs b/engine/crates/xerj-engine/src/graph.rs
index 9d193f07a..386ed7c8e 100644
--- a/engine/crates/xerj-engine/src/graph.rs
+++ b/engine/crates/xerj-engine/src/graph.rs
@@ -390,11 +390,10 @@ impl Index {
// processed exactly once.
let doc_count = k_src.doc_count;
for pos in 0..doc_count {
- let via_src = scan_src
- && k_src.ord_for(pos).is_some_and(|o| src_ords.contains(&o));
+ let via_src =
+ scan_src && k_src.ord_for(pos).is_some_and(|o| src_ords.contains(&o));
let admitted = via_src
- || (scan_dst
- && k_dst.ord_for(pos).is_some_and(|o| dst_ords.contains(&o)));
+ || (scan_dst && k_dst.ord_for(pos).is_some_and(|o| dst_ords.contains(&o)));
if !admitted {
continue;
}
@@ -419,8 +418,7 @@ impl Index {
// Bi-temporal cut (counted). A null valid_at is a
// schema-corrupt row (writers always emit it); such a row
// cannot be placed on the timeline, so it is skipped.
- let Some(valid_at_ms) = n_valid.get(pos).map(|v| bits_to_f64(v) as i64)
- else {
+ let Some(valid_at_ms) = n_valid.get(pos).map(|v| bits_to_f64(v) as i64) else {
continue;
};
let invalid_at_ms = n_invalid
@@ -490,19 +488,14 @@ impl Index {
for (id, source) in self.memtable.all_docs_with_sources_arc() {
stats.memtable_docs_scanned += 1;
// Tombstoned (deleted-by-API) rows are not edges.
- if self
- .store
- .version_map
- .get(&id)
- .is_some_and(|v| v.deleted)
- {
+ if self.store.version_map.get(&id).is_some_and(|v| v.deleted) {
continue;
}
let src = source.get("src").and_then(Value::as_str);
let dst = source.get("dst").and_then(Value::as_str);
let via_src = scan_src && src.is_some_and(|s| frontier_set.contains(s));
- let admitted = via_src
- || (scan_dst && dst.is_some_and(|d| frontier_set.contains(d)));
+ let admitted =
+ via_src || (scan_dst && dst.is_some_and(|d| frontier_set.contains(d)));
if !admitted {
continue;
}
@@ -616,8 +609,7 @@ impl Index {
}
// ── Final order + reachable ──────────────────────────────────────────
- let mut edges: Vec<GraphEdgeLite> =
- collected.into_values().map(|c| c.edge).collect();
+ let mut edges: Vec<GraphEdgeLite> = collected.into_values().map(|c| c.edge).collect();
edges.sort_by(|a, b| {
a.hop
.cmp(&b.hop)
diff --git a/engine/crates/xerj-engine/tests/graph_expand.rs b/engine/crates/xerj-engine/tests/graph_expand.rs
index 8aab3b6e3..7bd385238 100644
--- a/engine/crates/xerj-engine/tests/graph_expand.rs
+++ b/engine/crates/xerj-engine/tests/graph_expand.rs
@@ -77,22 +77,102 @@ fn edge_doc(
fn fixture_edges() -> Vec<Value> {
let alpha_line = "Alpha is the hub note. It links to [[beta]] and [[gamma]].";
vec![
- edge_doc(E_ALPHA_BETA_WIKI, "note-alpha", "note-beta", "wikilink", 1.0, 0.95,
- "wikilink@1", alpha_line, "alpha.md", 35),
- edge_doc(E_ALPHA_GAMMA_WIKI, "note-alpha", "note-gamma", "wikilink", 1.0, 0.95,
- "wikilink@1", alpha_line, "alpha.md", 48),
- edge_doc(E_BETA_GAMMA_WIKI, "note-beta", "note-gamma", "wikilink", 1.0, 0.95,
- "wikilink@1", "Beta continues the thread and references [[gamma]].", "beta.md", 41),
- edge_doc(E_DELTA_ALPHA_WIKI, "note-delta", "note-alpha", "wikilink", 1.0, 0.95,
- "wikilink@1", "Delta cites [[alpha]] as its source.", "delta.md", 12),
- edge_doc(E_ALPHA_BETA_DIR, "note-alpha", "note-beta", "same_dir", 0.3, 0.4,
- "samedir@1", "alpha.md and beta.md share directory .", "alpha.md", 0),
- edge_doc(E_BETA_DELTA_DIR, "note-beta", "note-delta", "same_dir", 0.3, 0.4,
- "samedir@1", "beta.md and delta.md share directory .", "beta.md", 0),
- edge_doc(E_DELTA_EPSILON_DIR, "note-delta", "note-epsilon", "same_dir", 0.3, 0.4,
- "samedir@1", "delta.md and epsilon.md share directory .", "delta.md", 0),
- edge_doc(E_EPSILON_GAMMA_DIR, "note-epsilon", "note-gamma", "same_dir", 0.3, 0.4,
- "samedir@1", "epsilon.md and gamma.md share directory .", "epsilon.md", 0),
+ edge_doc(
+ E_ALPHA_BETA_WIKI,
+ "note-alpha",
+ "note-beta",
+ "wikilink",
+ 1.0,
+ 0.95,
+ "wikilink@1",
+ alpha_line,
+ "alpha.md",
+ 35,
+ ),
+ edge_doc(
+ E_ALPHA_GAMMA_WIKI,
+ "note-alpha",
+ "note-gamma",
+ "wikilink",
+ 1.0,
+ 0.95,
+ "wikilink@1",
+ alpha_line,
+ "alpha.md",
+ 48,
+ ),
+ edge_doc(
+ E_BETA_GAMMA_WIKI,
+ "note-beta",
+ "note-gamma",
+ "wikilink",
+ 1.0,
+ 0.95,
+ "wikilink@1",
+ "Beta continues the thread and references [[gamma]].",
+ "beta.md",
+ 41,
+ ),
+ edge_doc(
+ E_DELTA_ALPHA_WIKI,
+ "note-delta",
+ "note-alpha",
+ "wikilink",
+ 1.0,
+ 0.95,
+ "wikilink@1",
+ "Delta cites [[alpha]] as its source.",
+ "delta.md",
+ 12,
+ ),
+ edge_doc(
+ E_ALPHA_BETA_DIR,
+ "note-alpha",
+ "note-beta",
+ "same_dir",
+ 0.3,
+ 0.4,
+ "samedir@1",
+ "alpha.md and beta.md share directory .",
+ "alpha.md",
+ 0,
+ ),
+ edge_doc(
+ E_BETA_DELTA_DIR,
+ "note-beta",
+ "note-delta",
+ "same_dir",
+ 0.3,
+ 0.4,
+ "samedir@1",
+ "beta.md and delta.md share directory .",
+ "beta.md",
+ 0,
+ ),
+ edge_doc(
+ E_DELTA_EPSILON_DIR,
+ "note-delta",
+ "note-epsilon",
+ "same_dir",
+ 0.3,
+ 0.4,
+ "samedir@1",
+ "delta.md and epsilon.md share directory .",
+ "delta.md",
+ 0,
+ ),
+ edge_doc(
+ E_EPSILON_GAMMA_DIR,
+ "note-epsilon",
+ "note-gamma",
+ "same_dir",
+ 0.3,
+ 0.4,
+ "samedir@1",
+ "epsilon.md and gamma.md share directory .",
+ "epsilon.md",
+ 0,
+ ),
]
}
@@ -141,10 +221,38 @@ fn assert_hop1_fixture(res: &GraphExpandResult) {
// §8.4: EXACTLY this order (hop asc, weight desc, edge_id asc).
let got = tuples(res);
let want = vec![
- (E_ALPHA_GAMMA_WIKI.into(), "note-alpha".into(), "note-gamma".into(), "wikilink".into(), 1.0, 1u8),
- (E_ALPHA_BETA_WIKI.into(), "note-alpha".into(), "note-beta".into(), "wikilink".into(), 1.0, 1u8),
- (E_DELTA_ALPHA_WIKI.into(), "note-delta".into(), "note-alpha".into(), "wikilink".into(), 1.0, 1u8),
- (E_ALPHA_BETA_DIR.into(), "note-alpha".into(), "note-beta".into(), "same_dir".into(), 0.3, 1u8),
+ (
+ E_ALPHA_GAMMA_WIKI.into(),
+ "note-alpha".into(),
+ "note-gamma".into(),
+ "wikilink".into(),
+ 1.0,
+ 1u8,
+ ),
+ (
+ E_ALPHA_BETA_WIKI.into(),
+ "note-alpha".into(),
+ "note-beta".into(),
+ "wikilink".into(),
+ 1.0,
+ 1u8,
+ ),
+ (
+ E_DELTA_ALPHA_WIKI.into(),
+ "note-delta".into(),
+ "note-alpha".into(),
+ "wikilink".into(),
+ 1.0,
+ 1u8,
+ ),
+ (
+ E_ALPHA_BETA_DIR.into(),
+ "note-alpha".into(),
+ "note-beta".into(),
+ "same_dir".into(),
+ 0.3,
+ 1u8,
+ ),
];
assert_eq!(got, want, "hop-1 edge list must match §8.4 exactly");
assert_eq!(
@@ -314,7 +422,11 @@ async fn graph_expand_caps_and_bounds() {
let mut req = expand_req(&["note-alpha"], 2);
req.max_result_edges = 2;
let res = idx.graph_expand(&req).expect("capped expand");
- assert_eq!(res.edges.len(), 2, "cap bounds the result (flushed={flushed})");
+ assert_eq!(
+ res.edges.len(),
+ 2,
+ "cap bounds the result (flushed={flushed})"
+ );
assert!(
res.stats.edges_clipped > 0,
"overflow must be counted, never silent (flushed={flushed})"
@@ -360,7 +472,11 @@ async fn graph_expand_direction_and_type_filter() {
req.direction = GraphDirection::In;
let inn = idx.graph_expand(&req).expect("in expand");
let ids: Vec<&str> = inn.edges.iter().map(|e| e.edge_id.as_str()).collect();
- assert_eq!(ids, vec![E_DELTA_ALPHA_WIKI], "direction=in follows dst → src only");
+ assert_eq!(
+ ids,
+ vec![E_DELTA_ALPHA_WIKI],
+ "direction=in follows dst → src only"
+ );
req.direction = GraphDirection::Both;
req.types = Some(vec!["wikilink".to_string()]);