Skip to content

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.md
index 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, which
covers PowerShell pipelines on Windows. Other malformed payloads are dropped
before 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.rs
index 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.rs
index 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.md
index 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"
}
```