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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
feat(second-brain): make the graph memory layer real — API half + stream reconciliation
xerj-orgb0f209e569cc
diff --git a/engine/Cargo.lock b/engine/Cargo.lockindex 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.tomlindex 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.rsnew file mode 100644index 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 ¶ms.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.rsindex 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.rsindex 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 underscoreassert!(validate_namespace("a/b").is_err()); // slashassert!(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.rsindex 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.rsindex 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.rsindex 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.rsindex 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::Missdiff --git a/engine/crates/xerj-autoindex/src/detect/samedir.rs b/engine/crates/xerj-autoindex/src/detect/samedir.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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()]);