Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: derive reader page kinds consistently
AkitaOnRails6376ecbf9c21
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c8ee956f..ae9587fc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Fixed+- Reader APIs now derive absent page kinds consistently from canonical path+ families. Session, concept, procedure, note, and slot pages no longer surface+ as generic facts, while an explicit frontmatter `kind` still takes precedence+ ([#198]).- Native lifecycle hooks now accept one leading UTF-8 BOM on JSON stdin, whichcovers PowerShell pipelines on Windows. Other malformed payloads are droppedbefore spool or network delivery with a bounded content-free stderr warning;diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex f53fe6ac..aac0d1df 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -3006,6 +3006,169 @@ mod tests {assert!(paths.contains(&"y.md"));}+ #[tokio::test]+ async fn reader_page_kinds_follow_canonical_paths_across_surfaces() {+ const CASES: [(&str, &str); 9] = [+ ("_rules/rule.md", "rule"),+ ("_slots/focus.md", "slot"),+ ("sessions/session.md", "session"),+ ("decisions/decision.md", "decision"),+ ("gotchas/gotcha.md", "gotcha"),+ ("concepts/concept.md", "concept"),+ ("procedures/procedure.md", "procedure"),+ ("notes/note.md", "note"),+ ("misc/fallback.md", "fact"),+ ];++ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "kind-test", None)+ .await+ .unwrap();++ let mut session_id = None;+ for (path, _) in CASES {+ let id = store+ .writer+ .upsert_page(sample_page(ws, proj, path, "body"))+ .await+ .unwrap();+ if path == "sessions/session.md" {+ session_id = Some(id);+ }+ }++ let mut override_page = sample_page(ws, proj, "sessions/override.md", "override");+ override_page.frontmatter_json = serde_json::json!({"kind": "note"});+ store.writer.upsert_page(override_page).await.unwrap();++ let mut source = sample_page(ws, proj, "notes/source.md", "linked source");+ source.links = vec![PagePath::new("sessions/session.md").unwrap().into()];+ store.writer.upsert_page(source).await.unwrap();++ let assert_briefing_kinds = |pages: &[BriefingPage]| {+ for (path, expected) in CASES {+ let page = pages.iter().find(|page| page.path == path).unwrap();+ assert_eq!(page.kind, expected, "wrong briefing kind for {path}");+ }+ let override_page = pages+ .iter()+ .find(|page| page.path == "sessions/override.md")+ .unwrap();+ assert_eq!(override_page.kind, "note", "explicit kind must win");+ };++ let listed = store+ .reader+ .list_pages("default", "kind-test")+ .await+ .unwrap();+ for (path, expected) in CASES {+ let page = listed.iter().find(|page| page.path == path).unwrap();+ assert_eq!(page.kind, expected, "wrong list kind for {path}");+ }+ assert_eq!(+ listed+ .iter()+ .find(|page| page.path == "sessions/override.md")+ .unwrap()+ .kind,+ "note",+ "explicit kind must win"+ );++ assert_briefing_kinds(&store.reader.briefing(100).await.unwrap().recent_pages);+ assert_briefing_kinds(+ &store+ .reader+ .briefing_for_workspace(ws, 100)+ .await+ .unwrap()+ .recent_pages,+ );+ let project_briefing = store+ .reader+ .briefing_for_project(ws, proj, 100)+ .await+ .unwrap();+ assert_briefing_kinds(&project_briefing.recent_pages);+ assert_eq!(project_briefing.rules[0].kind, "rule");+ assert_eq!(project_briefing.slots[0].kind, "slot");+ let (_, session_recent) = store+ .reader+ .session_brief_pages(ws, proj, 100, 100)+ .await+ .unwrap();+ assert_briefing_kinds(&session_recent);++ let session_id = session_id.unwrap();+ assert_eq!(+ store+ .reader+ .page_meta("default", "kind-test", "sessions/session.md")+ .await+ .unwrap()+ .unwrap()+ .kind,+ "session"+ );+ assert_eq!(+ store+ .reader+ .page_meta_by_id(session_id)+ .await+ .unwrap()+ .unwrap()+ .kind,+ "session"+ );+ assert_eq!(+ store+ .reader+ .page_meta_by_path("concepts/concept.md")+ .await+ .unwrap()+ .unwrap()+ .kind,+ "concept"+ );++ let source_links = store+ .reader+ .page_links(ws, proj, "notes/source.md".into())+ .await+ .unwrap();+ assert_eq!(source_links.links[0].kind, "session");+ let target_links = store+ .reader+ .page_links(ws, proj, "sessions/session.md".into())+ .await+ .unwrap();+ assert_eq!(target_links.backlinks[0].kind, "note");++ let health = store+ .reader+ .health_detail_for_project(ws, proj, 100)+ .await+ .unwrap();+ assert_eq!(+ health+ .orphans+ .iter()+ .find(|page| page.path == "procedures/procedure.md")+ .unwrap()+ .kind,+ "procedure"+ );+ }+#[tokio::test]async fn page_meta_returns_metadata_for_existing_page() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 2dd0741f..5aee0304 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -35,6 +35,25 @@ use crate::fts_query::prepare_fts5_query;use crate::maintenance::MaintenanceJob;use crate::users::TOKEN_HASH_LEN;+fn page_kind_expr(path_column: &str, frontmatter_column: &str) -> String {+ format!(+ "COALESCE( \+ json_extract({frontmatter_column}, '$.kind'), \+ CASE \+ WHEN {path_column} LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \+ WHEN {path_column} LIKE '\\_slots/%' ESCAPE '\\' THEN 'slot' \+ WHEN {path_column} LIKE 'sessions/%' THEN 'session' \+ WHEN {path_column} LIKE 'decisions/%' THEN 'decision' \+ WHEN {path_column} LIKE 'gotchas/%' THEN 'gotcha' \+ WHEN {path_column} LIKE 'concepts/%' THEN 'concept' \+ WHEN {path_column} LIKE 'procedures/%' THEN 'procedure' \+ WHEN {path_column} LIKE 'notes/%' THEN 'note' \+ ELSE 'fact' \+ END \+ )"+ )+}+/// One hit returned by [`ReaderPool::search_pages`].#[derive(Debug, Clone, Serialize)]pub struct PageHit {@@ -363,7 +382,8 @@ pub struct BriefingPage {pub path: String,/// Page title (first H1 / frontmatter title).pub title: String,- /// Semantic classification — `decision` / `gotcha` / `rule` / `fact`.+ /// Semantic classification, derived from explicit frontmatter or the+ /// page's canonical path family.pub kind: String,/// ISO-8601 timestamp of the last update.pub updated_at: String,@@ -1962,6 +1982,7 @@ impl ReaderPool {pub async fn briefing(&self, recent_pages_limit: usize) -> StoreResult<BriefingSnapshot> {let recent_limit = recent_pages_limit.clamp(1, 100) as i64;self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("path", "frontmatter_json");let now_us = jiff::Timestamp::now().as_microsecond();let day_us: i64 = 86_400 * 1_000_000;let cutoff_7d = now_us - 7 * day_us;@@ -1993,59 +2014,40 @@ impl ReaderPool {// Rules: any `is_latest = 1` page under `_rules/`.// Routed there automatically by the consolidator when// `kind = "rule"` — see consolidator.rs::slugify_for_rule.- let mut rules_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut rules_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE is_latest = 1 AND path GLOB '_rules/*' \- ORDER BY updated_at DESC",- )?;+ ORDER BY updated_at DESC"+ ))?;let rules: Vec<BriefingPage> = rules_stmt.query_map([], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut slots_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE(json_extract(frontmatter_json, '$.kind'), 'slot') AS kind, \+ let mut slots_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE is_latest = 1 AND path GLOB '_slots/*' \- ORDER BY path ASC",- )?;+ ORDER BY path ASC"+ ))?;let slots: Vec<BriefingPage> = slots_stmt.query_map([], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut recent_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut recent_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE is_latest = 1 \ORDER BY updated_at DESC \- LIMIT ?1",- )?;+ LIMIT ?1"+ ))?;let recent_pages: Vec<BriefingPage> = recent_stmt.query_map(params![recent_limit], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?@@ -2081,6 +2083,7 @@ impl ReaderPool {) -> StoreResult<BriefingSnapshot> {let recent_limit = recent_pages_limit.clamp(1, 100) as i64;self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("path", "frontmatter_json");let now_us = jiff::Timestamp::now().as_microsecond();let day_us: i64 = 86_400 * 1_000_000;let cutoff_7d = now_us - 7 * day_us;@@ -2135,59 +2138,40 @@ impl ReaderPool {project_id,)?;- let mut rules_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut rules_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 AND path GLOB '_rules/*' \- ORDER BY updated_at DESC",- )?;+ ORDER BY updated_at DESC"+ ))?;let rules: Vec<BriefingPage> = rules_stmt.query_map(params![workspace_id.as_bytes(), project_id.as_bytes()], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut slots_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE(json_extract(frontmatter_json, '$.kind'), 'slot') AS kind, \+ let mut slots_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 AND path GLOB '_slots/*' \- ORDER BY path ASC",- )?;+ ORDER BY path ASC"+ ))?;let slots: Vec<BriefingPage> = slots_stmt.query_map(params![workspace_id.as_bytes(), project_id.as_bytes()], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut recent_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut recent_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \ORDER BY updated_at DESC \- LIMIT ?3",- )?;+ LIMIT ?3"+ ))?;let recent_pages: Vec<BriefingPage> = recent_stmt.query_map(params![workspace_id.as_bytes(), project_id.as_bytes(), recent_limit], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?@@ -2235,6 +2219,7 @@ impl ReaderPool {let core_limit = core_pages_limit.clamp(1, 100) as i64;let recent_limit = recent_pages_limit.clamp(1, 100) as i64;self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("path", "frontmatter_json");let mut core_stmt = conn.prepare_cached("SELECT path, title, body, pinned, updated_at \FROM pages \@@ -2276,23 +2261,14 @@ impl ReaderPool {}).collect::<StoreResult<Vec<_>>>()?;- let mut recent_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut recent_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \ORDER BY updated_at DESC \- LIMIT ?3",- )?;+ LIMIT ?3"+ ))?;let recent: Vec<BriefingPage> = recent_stmt.query_map(params![workspace_id.as_bytes(), project_id.as_bytes(), recent_limit],@@ -2399,6 +2375,7 @@ impl ReaderPool {) -> StoreResult<BriefingSnapshot> {let recent_limit = recent_pages_limit.clamp(1, 100) as i64;self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("path", "frontmatter_json");let now_us = jiff::Timestamp::now().as_microsecond();let day_us: i64 = 86_400 * 1_000_000;let cutoff_7d = now_us - 7 * day_us;@@ -2448,59 +2425,40 @@ impl ReaderPool {workspace_id,)?;- let mut rules_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut rules_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND is_latest = 1 AND path GLOB '_rules/*' \- ORDER BY updated_at DESC",- )?;+ ORDER BY updated_at DESC"+ ))?;let rules: Vec<BriefingPage> = rules_stmt.query_map(params![workspace_id.as_bytes()], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut slots_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE(json_extract(frontmatter_json, '$.kind'), 'slot') AS kind, \+ let mut slots_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND is_latest = 1 AND path GLOB '_slots/*' \- ORDER BY path ASC",- )?;+ ORDER BY path ASC"+ ))?;let slots: Vec<BriefingPage> = slots_stmt.query_map(params![workspace_id.as_bytes()], briefing_page_from_row)?.collect::<Result<Vec<_>, _>>()?.into_iter().collect::<Result<Vec<_>, _>>()?;- let mut recent_stmt = conn.prepare_cached(- "SELECT path, title, \- COALESCE( \- json_extract(frontmatter_json, '$.kind'), \- CASE \- WHEN path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN path LIKE 'decisions/%' THEN 'decision' \- WHEN path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let mut recent_stmt = conn.prepare_cached(&format!(+ "SELECT path, title, {kind_expr} AS kind, \updated_at \FROM pages \WHERE workspace_id = ?1 AND is_latest = 1 \ORDER BY updated_at DESC \- LIMIT ?2",- )?;+ LIMIT ?2"+ ))?;let recent_pages: Vec<BriefingPage> = recent_stmt.query_map(params![workspace_id.as_bytes(), recent_limit],@@ -2687,19 +2645,13 @@ impl ReaderPool {};// Shared SELECT prefix: identity + path-inferred `kind`.- let select = "SELECT w.name, p.name, pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) \+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let select = format!(+ "SELECT w.name, p.name, pg.path, pg.title, {kind_expr} \FROM pages pg \JOIN projects p ON p.id = pg.project_id \- JOIN workspaces w ON w.id = pg.workspace_id ";+ JOIN workspaces w ON w.id = pg.workspace_id "+ );// Params follow placeholder order: ws, cutoff, [proj], limit.let stale_sql = format!(@@ -2778,30 +2730,22 @@ impl ReaderPool {/// Propagates any SQL or pool error.pub async fn page_meta_by_id(&self, page_id: PageId) -> StoreResult<Option<PageMeta>> {self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let sql = format!(+ "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \+ {kind_expr}, \+ pg.tier, pg.pinned, pg.created_at, pg.updated_at, \+ sp.path AS supersedes_path, \+ au.username, au.name, au.email \+ FROM pages pg \+ JOIN projects p ON p.id = pg.project_id \+ JOIN workspaces w ON w.id = pg.workspace_id \+ LEFT JOIN pages sp ON sp.id = pg.supersedes \+ LEFT JOIN users au ON au.id = pg.author_id \+ WHERE pg.id = ?1 AND pg.is_latest = 1"+ );let row_opt = conn- .query_row(- "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ), \- pg.tier, pg.pinned, pg.created_at, pg.updated_at, \- sp.path AS supersedes_path, \- au.username, au.name, au.email \- FROM pages pg \- JOIN projects p ON p.id = pg.project_id \- JOIN workspaces w ON w.id = pg.workspace_id \- LEFT JOIN pages sp ON sp.id = pg.supersedes \- LEFT JOIN users au ON au.id = pg.author_id \- WHERE pg.id = ?1 AND pg.is_latest = 1",- params![page_id.as_bytes()],- page_meta_from_row,- )+ .query_row(&sql, params![page_id.as_bytes()], page_meta_from_row).optional()?;row_opt.transpose()})@@ -2819,31 +2763,23 @@ impl ReaderPool {pub async fn page_meta_by_path(&self, path: &str) -> StoreResult<Option<PageMeta>> {let path = path.to_owned();self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let sql = format!(+ "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \+ {kind_expr}, \+ pg.tier, pg.pinned, pg.created_at, pg.updated_at, \+ sp.path AS supersedes_path, \+ au.username, au.name, au.email \+ FROM pages pg \+ JOIN projects p ON p.id = pg.project_id \+ JOIN workspaces w ON w.id = pg.workspace_id \+ LEFT JOIN pages sp ON sp.id = pg.supersedes \+ LEFT JOIN users au ON au.id = pg.author_id \+ WHERE pg.path = ?1 AND pg.is_latest = 1 \+ LIMIT 1"+ );let row_opt = conn- .query_row(- "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ), \- pg.tier, pg.pinned, pg.created_at, pg.updated_at, \- sp.path AS supersedes_path, \- au.username, au.name, au.email \- FROM pages pg \- JOIN projects p ON p.id = pg.project_id \- JOIN workspaces w ON w.id = pg.workspace_id \- LEFT JOIN pages sp ON sp.id = pg.supersedes \- LEFT JOIN users au ON au.id = pg.author_id \- WHERE pg.path = ?1 AND pg.is_latest = 1 \- LIMIT 1",- params![path],- page_meta_from_row,- )+ .query_row(&sql, params![path], page_meta_from_row).optional()?;row_opt.transpose()})@@ -2882,40 +2818,27 @@ impl ReaderPool {// Outgoing: latest pages this page links to. Incoming: latest// pages that link here. Both reuse the path-inference `kind`// fallback so untagged pages still classify.- let outgoing = "SELECT DISTINCT pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ), \+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let outgoing = format!(+ "SELECT DISTINCT pg.path, pg.title, {kind_expr}, \ws.name, pr.name \FROM links l \JOIN pages pg ON pg.id = l.to_page_id \JOIN projects pr ON pr.id = pg.project_id \JOIN workspaces ws ON ws.id = pg.workspace_id \WHERE l.from_page_id = ?1 AND pg.is_latest = 1 \- ORDER BY ws.name, pr.name, pg.path";- let incoming = "SELECT DISTINCT pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ), \+ ORDER BY ws.name, pr.name, pg.path"+ );+ let incoming = format!(+ "SELECT DISTINCT pg.path, pg.title, {kind_expr}, \ws.name, pr.name \FROM links l \JOIN pages pg ON pg.id = l.from_page_id \JOIN projects pr ON pr.id = pg.project_id \JOIN workspaces ws ON ws.id = pg.workspace_id \WHERE l.to_page_id = ?1 AND pg.is_latest = 1 \- ORDER BY ws.name, pr.name, pg.path";+ ORDER BY ws.name, pr.name, pg.path"+ );let collect = |sql: &str| -> StoreResult<Vec<RelatedPage>> {let mut stmt = conn.prepare(sql)?;@@ -2936,8 +2859,8 @@ impl ReaderPool {};Ok(PageLinks {- links: collect(outgoing)?,- backlinks: collect(incoming)?,+ links: collect(&outgoing)?,+ backlinks: collect(&incoming)?,})}).await@@ -3284,24 +3207,16 @@ impl ReaderPool {let workspace = workspace.to_owned();let project = project.to_owned();self.with_conn(move |conn| {- let mut stmt = conn.prepare(- "SELECT pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ) AS kind, \+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let mut stmt = conn.prepare(&format!(+ "SELECT pg.path, pg.title, {kind_expr} AS kind, \pg.tier, pg.updated_at \FROM pages pg \JOIN projects p ON p.id = pg.project_id \JOIN workspaces w ON w.id = pg.workspace_id \WHERE w.name = ?1 AND p.name = ?2 AND pg.is_latest = 1 \- ORDER BY pg.path ASC",- )?;+ ORDER BY pg.path ASC"+ ))?;let rows = stmt.query_map(params![workspace, project], |row| {let path: String = row.get(0)?;let title: String = row.get(1)?;@@ -3345,27 +3260,23 @@ impl ReaderPool {let project = project.to_owned();let page_path = page_path.to_owned();self.with_conn(move |conn| {+ let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");+ let sql = format!(+ "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \+ {kind_expr}, \+ pg.tier, pg.pinned, pg.created_at, pg.updated_at, \+ sp.path AS supersedes_path, \+ au.username, au.name, au.email \+ FROM pages pg \+ JOIN projects p ON p.id = pg.project_id \+ JOIN workspaces w ON w.id = pg.workspace_id \+ LEFT JOIN pages sp ON sp.id = pg.supersedes \+ LEFT JOIN users au ON au.id = pg.author_id \+ WHERE w.name = ?1 AND p.name = ?2 AND pg.path = ?3 AND pg.is_latest = 1"+ );let row_opt = conn.query_row(- "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \- COALESCE( \- json_extract(pg.frontmatter_json, '$.kind'), \- CASE \- WHEN pg.path LIKE '\\_rules/%' ESCAPE '\\' THEN 'rule' \- WHEN pg.path LIKE 'decisions/%' THEN 'decision' \- WHEN pg.path LIKE 'gotchas/%' THEN 'gotcha' \- ELSE 'fact' \- END \- ), \- pg.tier, pg.pinned, pg.created_at, pg.updated_at, \- sp.path AS supersedes_path, \- au.username, au.name, au.email \- FROM pages pg \- JOIN projects p ON p.id = pg.project_id \- JOIN workspaces w ON w.id = pg.workspace_id \- LEFT JOIN pages sp ON sp.id = pg.supersedes \- LEFT JOIN users au ON au.id = pg.author_id \- WHERE w.name = ?1 AND p.name = ?2 AND pg.path = ?3 AND pg.is_latest = 1",+ &sql,params![workspace, project, page_path],page_meta_from_row,)diff --git a/docs/frontend-api.md b/docs/frontend-api.mdindex 52e79593..1e4db8bd 100644--- a/docs/frontend-api.md+++ b/docs/frontend-api.md@@ -170,7 +170,7 @@ links + back-links."frontmatter": { "tags": ["adr"], "pinned": true },"body": "# Standardised on Postgres\n\n…","links": [ { "path": "concepts/db-rules.md", "title": "DB rules", "kind": "rule" } ],- "backlinks": [ { "path": "sessions/2026-05-27.md", "title": "Session 2026-05-27", "kind": "fact" } ]+ "backlinks": [ { "path": "sessions/2026-05-27.md", "title": "Session 2026-05-27", "kind": "session" } ]}```@@ -238,6 +238,12 @@ GET /api/v1/workspaces/{workspace}/projects/{project}/recent?limit=20`is_latest = 1` pages ordered by `updated_at` DESC. `limit` clamped`1..=100`, default `10`.+Every reader surface uses the same `kind` contract. An explicit frontmatter+`kind` wins; otherwise the path families `_rules/`, `_slots/`, `sessions/`,+`decisions/`, `gotchas/`, `concepts/`, `procedures/`, and `notes/` derive+`rule`, `slot`, `session`, `decision`, `gotcha`, `concept`, `procedure`, and+`note`, respectively. Other paths fall back to `fact`.+**Response:** `{ "pages": [BriefingPage, …] }````json@@ -246,7 +252,7 @@ GET /api/v1/workspaces/{workspace}/projects/{project}/recent?limit=20{"path": "sessions/2026-05-28.md","title": "Session 2026-05-28",- "kind": "fact",+ "kind": "session","updated_at": "2026-05-28T14:02:11.123Z"}]@@ -278,9 +284,9 @@ pages. No LLM, deterministic."last_observation_at": "2026-05-28T13:58:02.123Z","pending_handoff_count": 0,"rules": [{ "path": "_rules/postgres.md", "title": "Postgres only", "kind": "rule", "updated_at": "…" }],- "slots": [{ "path": "_slots/focus.md", "title": "Current focus", "kind": "fact", "updated_at": "…" }],+ "slots": [{ "path": "_slots/focus.md", "title": "Current focus", "kind": "slot", "updated_at": "…" }],"recent_pages": [- { "path": "sessions/2026-05-28.md", "title": "Session 2026-05-28", "kind": "fact", "updated_at": "…" }+ { "path": "sessions/2026-05-28.md", "title": "Session 2026-05-28", "kind": "session", "updated_at": "…" }]}```@@ -324,7 +330,7 @@ across all projects in the workspace:"project": "ai-memory","path": "concepts/old-thing.md","title": "Old thing",- "kind": "fact"+ "kind": "concept"}```