Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Page-level domain types.
//!
//! A *page* is the unit of long-term memory — one markdown file under
//! `<data_dir>/wiki/`. Pages live in tiers (working/episodic/semantic/
//! procedural) and are versioned in place via supersession (an old
//! `is_latest=false` row links to the new `is_latest=true` row through
//! [`Page::supersedes`]).
use std::str::FromStr;
use jiff::Timestamp;
use serde::{Deserialize, Serialize};
use crate::ids::{PageId, PagePath, ProjectId, WorkspaceId};
/// Lifetime classification for a page.
///
/// Adopted from agentmemory's four-tier model, simplified. See
/// [`docs/design-decisions.md`](../../docs/design-decisions.md) §7.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum Tier {
/// Current session: last N observations, current files.
Working,
/// Per-session summaries with concept tags and files touched.
Episodic,
/// Distilled facts/preferences/architecture notes — wiki pages proper.
Semantic,
/// Repeated patterns extracted from episodic clusters.
Procedural,
}
/// Input for upserting a page. Generated by the wiki layer, consumed by
/// the store's writer actor.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct NewPage {
/// Owning workspace.
pub workspace_id: WorkspaceId,
/// Owning project.
pub project_id: ProjectId,
/// Relative path within the wiki tree.
pub path: PagePath,
/// Page title (rendered from frontmatter or the first H1).
pub title: String,
/// Markdown body excluding the YAML frontmatter.
pub body: String,
/// Tier classification.
pub tier: Tier,
/// Frontmatter, stored as JSON for cheap querying.
pub frontmatter_json: serde_json::Value,
/// `true` to mark the page as user-pinned (never decay).
pub pinned: bool,
/// Outgoing links discovered in the page body.
///
/// The store resolves these against the latest page rows in the target
/// project (the source's own project for bare links, or the named
/// project for a cross-project `[[project:path]]` link) and keeps
/// unresolved forward links as `to_page_id = NULL`.
pub links: Vec<LinkTarget>,
/// Multi-user attribution: the registered user (v0.8 `users` table)
/// that made this write, when resolved by the auth middleware.
/// `None` for rung-0 (anonymous) and rung-1 (root token — root
/// isn't a `users` row; the human-readable identity goes into the
/// frontmatter `last_modified_by` block instead). `Some` for
/// rung-2 (DB user) writes; persists to `pages.author_id`
/// via V15. Defaults to `None` for backward compat — every existing
/// call site that constructs `NewPage` without filling this field
/// gets the pre-multi-user behaviour.
#[serde(default)]
pub author_id: Option<crate::UserId>,
/// TTL derived from the frontmatter `expires_at:` key (markdown is
/// the source of truth; the wiki layer parses and validates it).
/// `None` = never expires. Expired pages are hidden from
/// search/recent/briefing and hard-deleted by the retention sweep.
#[serde(default)]
pub expires_at: Option<Timestamp>,
/// Salient nouns for this page, from the frontmatter `entities:`
/// list the consolidator writes. Normalised by
/// [`normalize_entity`] before it reaches the store, which indexes
/// them as a retrieval stream (V38). Empty for hand-written pages
/// that don't declare any.
#[serde(default)]
pub entities: Vec<String>,
/// Evidence sources backing this write (P2,
/// docs/design-hindsight-borrowings.md §3): what produced or
/// reaffirmed this page version. The store inserts one
/// `page_evidence` row per entry, in the same transaction as the
/// page upsert (V63), `INSERT OR IGNORE` so re-citing the same
/// source is a no-op. Empty for hand-written pages and every
/// pre-2.2 caller — inert data this release, not fed into ranking
/// or [`crate::PageAuthority`].
#[serde(default)]
pub evidence: Vec<PageEvidence>,
}
/// One piece of evidence supporting a page write (P2,
/// docs/design-hindsight-borrowings.md §3). Additive substrate only this
/// release: recorded and surfaced via `SearchExplain::evidence_count`,
/// never consulted by ranking.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct PageEvidence {
/// What kind of source this is.
pub kind: PageEvidenceKind,
/// The source's own identifier (a session id, observation id,
/// feedback row id, or reconsolidation run id) — opaque to the
/// store, unique within `kind` for this page.
pub source_id: String,
}
/// The closed vocabulary of evidence sources a page write can cite.
/// Matches the `page_evidence.source_kind` CHECK constraint (V63).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum PageEvidenceKind {
/// A consolidated session that produced or touched this page.
Session,
/// A raw observation cited directly (bypassing session-grain
/// consolidation).
Observation,
/// User/agent feedback that reaffirmed the page.
Feedback,
/// A reconsolidation pass that rewrote or re-confirmed the page.
Reconsolidation,
}
impl PageEvidenceKind {
/// Canonical short string for storage. Matches the
/// `page_evidence.source_kind` CHECK constraint (V63).
#[must_use]
pub const fn as_str(&self) -> &'static str {
match self {
Self::Session => "session",
Self::Observation => "observation",
Self::Feedback => "feedback",
Self::Reconsolidation => "reconsolidation",
}
}
}
impl FromStr for PageEvidenceKind {
type Err = crate::MemoryError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"session" => Ok(Self::Session),
"observation" => Ok(Self::Observation),
"feedback" => Ok(Self::Feedback),
"reconsolidation" => Ok(Self::Reconsolidation),
other => Err(crate::MemoryError::MalformedRecord(format!(
"unknown page evidence kind: {other}"
))),
}
}
}
/// Longest accepted entity name; longer values are rejected rather than
/// truncated (a 100-char "entity" is a sentence, not a noun).
pub const MAX_ENTITY_LEN: usize = 64;
/// Cap on entities indexed per page. Beyond this the list stops being a
/// salience signal and starts being a second copy of the body.
pub const MAX_ENTITIES_PER_PAGE: usize = 10;
/// Maximum raw characters in the new MCP kind field; admin uses its legacy adapter.
pub const MAX_PAGE_KIND_LEN: usize = 64;
/// Maximum raw characters in a public L0 abstract, before trimming.
pub const MAX_PAGE_ABSTRACT_LEN: usize = 1024;
/// Maximum relation targets across all relation kinds in one write.
pub const MAX_PAGE_RELATIONS: usize = 32;
/// Maximum raw characters in one relation target, including its scope qualifier.
pub const MAX_PAGE_RELATION_TARGET_LEN: usize = 1024;
/// Maximum `applies_to` tags in one write.
pub const MAX_PAGE_APPLIES_TO: usize = 16;
/// Maximum raw characters in one `applies_to` tag, before trimming.
pub const MAX_PAGE_APPLIES_TO_TAG_LEN: usize = 32;
/// Maximum raw characters in `enforced_by`, before trimming.
pub const MAX_PAGE_ENFORCED_BY_LEN: usize = 256;
/// Editable metadata shared by public page-write surfaces.
///
/// Flattened into their existing request JSON. This is a full replacement,
/// not a patch: omitted fields do not inherit previous frontmatter. Scope,
/// attribution and admission controls cannot be supplied through this type.
/// Admin consumes its existing `kind` field through a legacy adapter; MCP kind
/// and the other shared fields are bounded before trimming or normalization.
#[derive(Clone, Debug, Default, Serialize, Deserialize, schemars::JsonSchema)]
pub struct PageWriteMetadata {
/// MCP semantic kind, at most 64 raw characters, then trimmed. Empty means absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(length(max = 64))]
pub kind: Option<String>,
/// Up to 10 input names, each at most 64 raw characters; validation precedes
/// whitespace normalization, lowercasing and deduplication.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[schemars(length(max = 10))]
pub entities: Vec<String>,
/// L0 summary, at most 1024 raw characters, then trimmed. Empty means absent.
#[serde(default, rename = "abstract", skip_serializing_if = "Option::is_none")]
#[schemars(length(max = 1024))]
pub abstract_text: Option<String>,
/// Existing typed relations, up to 32 input targets total and 1024 raw
/// characters each. Wikilink syntax (`path`, `project:path`,
/// `workspace/project:path`) requires already-trimmed scope components.
#[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
pub relations: std::collections::BTreeMap<Relation, Vec<String>>,
/// Profile entries only: stack tags (`rust`, `typescript`, ...) that limit
/// the entry to projects on that stack. Up to 16, each a tag the profile
/// detects; lowercased and deduplicated.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[schemars(length(max = 16))]
pub applies_to: Vec<String>,
/// Profile entries only: what already enforces the entry (`pre-push
/// hook`), which keeps it out of the session-start digest. At most 256 raw
/// characters, then trimmed. Empty means absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(length(max = 256))]
pub enforced_by: Option<String>,
}
impl PageWriteMetadata {
/// Validate public input and produce only the supported frontmatter keys.
///
/// # Errors
/// Rejects malformed names/targets, control characters and exceeded bounds.
pub fn into_frontmatter(
self,
) -> Result<serde_json::Map<String, serde_json::Value>, crate::MemoryError> {
fn invalid(field: &str) -> crate::MemoryError {
crate::MemoryError::MalformedRecord(format!(
"invalid or oversized page metadata: {field}"
))
}
fn valid_text(raw: &str, max: usize) -> bool {
raw.chars().take(max + 1).count() <= max
&& !raw.chars().any(|c| c.is_control() && !c.is_whitespace())
}
let mut fm = serde_json::Map::new();
for (key, value, max) in [
("kind", self.kind, MAX_PAGE_KIND_LEN),
("abstract", self.abstract_text, MAX_PAGE_ABSTRACT_LEN),
("enforced_by", self.enforced_by, MAX_PAGE_ENFORCED_BY_LEN),
] {
if let Some(value) = value {
if !valid_text(&value, max) {
return Err(invalid(key));
}
if !value.trim().is_empty() {
fm.insert(key.into(), serde_json::json!(value.trim()));
}
}
}
if self.entities.len() > MAX_ENTITIES_PER_PAGE
|| self
.entities
.iter()
.any(|e| !valid_text(e, MAX_ENTITY_LEN) || normalize_entity(e).is_none())
{
return Err(invalid("entities"));
}
if !self.entities.is_empty() {
fm.insert(
"entities".into(),
serde_json::json!(normalize_entities(self.entities)),
);
}
if self.relations.values().map(Vec::len).sum::<usize>() > MAX_PAGE_RELATIONS {
return Err(invalid("relations"));
}
for targets in self.relations.values() {
for target in targets {
if !valid_text(target, MAX_PAGE_RELATION_TARGET_LEN)
|| target.chars().any(char::is_control)
{
return Err(invalid("relations"));
}
let raw_path = match target.split_once(':') {
None => target.as_str(),
Some((scope, path)) => {
let parts: Vec<_> = scope.split('/').collect();
// `ai_memory_wiki::split_scope` only recognises a
// scope built from alphanumerics and `-_/.`; on a
// scope holding anything else it returns no scope at
// all and leaves the colon inside the page path. That
// path is one `PagePath::new` accepts but
// `ensure_portable` refuses, so the write would mint a
// `links` row no page write could ever repoint. The
// write boundary has to agree with the reader on what
// a scope is, so the character class is shared.
if parts.len() > 2
|| !scope
.chars()
.all(|c| c.is_alphanumeric() || matches!(c, '-' | '_' | '/' | '.'))
|| parts.iter().any(|s| {
s.trim().is_empty() || *s != s.trim() || matches!(*s, "." | "..")
})
{
return Err(invalid("relations"));
}
path
}
}
.trim();
let last = raw_path.rsplit('/').next().unwrap_or("");
if last.is_empty()
|| last == ".md"
|| (last.contains('.') && !raw_path.ends_with(".md"))
{
return Err(invalid("relations"));
}
let normalized = if last.contains('.') {
raw_path.to_owned()
} else {
format!("{raw_path}.md")
};
PagePath::new(normalized)
.and_then(|p| p.ensure_portable())
.map_err(|_| invalid("relations"))?;
}
}
if !self.relations.is_empty() {
fm.insert("relations".into(), serde_json::json!(self.relations));
}
if self.applies_to.len() > MAX_PAGE_APPLIES_TO
|| self
.applies_to
.iter()
.any(|tag| !valid_text(tag, MAX_PAGE_APPLIES_TO_TAG_LEN))
{
return Err(invalid("applies_to"));
}
// The same normalization `ProfileEntry::from_page` applies on read,
// plus a check the reader cannot make: a tag no project can be
// detected with would hide the entry from every project with activity.
let known = crate::profile::detectable_stack_tags();
let mut applies_to = std::collections::BTreeSet::new();
for tag in &self.applies_to {
let tag = tag.trim().to_ascii_lowercase();
if tag.is_empty() {
continue;
}
if !known.contains(tag.as_str()) {
return Err(crate::MemoryError::MalformedRecord(format!(
"unknown applies_to tag '{tag}'; known stack tags: {}",
known.into_iter().collect::<Vec<_>>().join(", ")
)));
}
applies_to.insert(tag);
}
if !applies_to.is_empty() {
fm.insert("applies_to".into(), serde_json::json!(applies_to));
}
Ok(fm)
}
}
/// Refuse the profile-only keys (`applies_to`, `enforced_by`) on a page the
/// digest never reads, where the caller's intent would silently do nothing:
/// one outside `profile/`, or one written to a project that cannot hold a
/// profile. `profile_scope` says whether the write targets the profile
/// (`scope: "profile"` or `"global"`, or `_global` or a reserved profile
/// project by name); the caller decides it from the request, before any
/// scope is created. It looks at the project name only, not the workspace
/// or share mode, so it errs lenient.
///
/// # Errors
/// Returns `MalformedRecord` naming the first such key.
pub fn ensure_profile_metadata_placement(
frontmatter: &serde_json::Map<String, serde_json::Value>,
path: &PagePath,
profile_scope: bool,
) -> Result<(), crate::MemoryError> {
if profile_scope
&& path
.as_str()
.starts_with(crate::profile::PROFILE_PATH_PREFIX)
{
return Ok(());
}
match ["applies_to", "enforced_by"]
.into_iter()
.find(|key| frontmatter.contains_key(*key))
{
Some(key) => Err(crate::MemoryError::MalformedRecord(format!(
"{key} applies only to profile entries: write with scope \"profile\", \
or under a `profile/` path in `_global` or a profile project"
))),
None => Ok(()),
}
}
/// Normalise one entity name for storage and matching: trim, collapse
/// internal whitespace, lowercase. Returns `None` when the result is
/// empty, contains control characters, or is longer than
/// [`MAX_ENTITY_LEN`]. Processing stops as soon as the input crosses the
/// bound, so an oversized untrusted value cannot cause a proportional
/// allocation.
///
/// Lowercasing is what makes query-time matching lexical rather than a
/// second LLM call: `Postgres`, `postgres`, and `POSTGRES` all index and
/// match as one entity.
#[must_use]
pub fn normalize_entity(raw: &str) -> Option<String> {
let mut collapsed = String::new();
let mut chars = 0;
for word in raw.split_whitespace() {
if !collapsed.is_empty() {
collapsed.push(' ');
chars += 1;
}
for ch in word.chars() {
if ch.is_control() {
return None;
}
chars += 1;
if chars > MAX_ENTITY_LEN {
return None;
}
collapsed.push(ch);
}
}
let normalized = collapsed.to_lowercase();
if normalized.is_empty() || normalized.chars().count() > MAX_ENTITY_LEN {
return None;
}
Some(normalized)
}
/// Normalise a whole entity list: drop invalid entries, de-duplicate
/// while preserving order, and cap at [`MAX_ENTITIES_PER_PAGE`].
#[must_use]
pub fn normalize_entities<I, S>(raw: I) -> Vec<String>
where
I: IntoIterator<Item = S>,
S: AsRef<str>,
{
let mut seen = std::collections::BTreeSet::new();
let mut out = Vec::new();
for item in raw {
let Some(name) = normalize_entity(item.as_ref()) else {
continue;
};
if seen.insert(name.clone()) {
out.push(name);
if out.len() >= MAX_ENTITIES_PER_PAGE {
break;
}
}
}
out
}
/// Derive a page's indexed entity names from its frontmatter: the
/// explicit `entities` list an LLM consolidator may emit, plus the
/// `tags` list nearly every page carries. Both are arrays of strings
/// meaning "what this page is about"; merging them populates the entity
/// retrieval stream and `as_of` timelines deterministically, without
/// depending on an LLM pass that a mature store's pages never received.
///
/// Explicit entities come first so they win the per-page cap. Lenient by
/// design — a missing or non-array field simply contributes nothing, so
/// this never fails on hand-edited frontmatter; the strict structural
/// check for the write path lives in the wiki layer.
#[must_use]
pub fn frontmatter_entity_names(frontmatter: &serde_json::Value) -> Vec<String> {
fn strings(frontmatter: &serde_json::Value, key: &str) -> Vec<String> {
frontmatter
.get(key)
.and_then(serde_json::Value::as_array)
.into_iter()
.flatten()
.filter_map(|v| v.as_str().map(str::to_owned))
.collect()
}
let mut merged = strings(frontmatter, "entities");
merged.extend(strings(frontmatter, "tags"));
normalize_entities(merged)
}
/// The instant a frontmatter `expires_at` value names: an RFC 3339
/// timestamp, or a bare `YYYY-MM-DD` meaning the end of that day in UTC.
/// `None` when the value is neither. The wiki's TTL validation and the
/// OKF `stale_after` derivation both read it, so the two cannot disagree
/// on when a page expires.
#[must_use]
pub fn parse_expires_at_instant(raw: &str) -> Option<Timestamp> {
let raw = raw.trim();
if let Ok(ts) = raw.parse::<Timestamp>() {
return Some(ts);
}
let date = raw.parse::<jiff::civil::Date>().ok()?;
date.at(23, 59, 59, 999_999_000)
.to_zoned(jiff::tz::TimeZone::UTC)
.ok()
.map(|zoned| zoned.timestamp())
}
/// A link target discovered in a page body.
///
/// A bare `[[path]]` / `[label](path)` resolves within the source page's
/// own project (`workspace`/`project` both `None`). A `[[project:path]]`
/// link names a sibling project in the same workspace; a
/// `[[workspace/project:path]]` link crosses workspaces. Making
/// cross-project dependencies explicit edges is what turns the per-project
/// wikis into one graph.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
pub struct LinkTarget {
/// Cross-workspace qualifier. `None` = same workspace as the source.
pub workspace: Option<String>,
/// Cross-project qualifier. `None` = same project as the source.
pub project: Option<String>,
/// Wiki path within the target project (root-relative).
pub path: PagePath,
/// Typed relation carried by this edge; `None` = a plain reference.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub relation: Option<Relation>,
}
/// The closed typed-edge vocabulary (2.0 item 3). Declared in a page's
/// `relations:` frontmatter; anything outside this set stays a plain
/// reference. Closed on purpose: a free-text relation column becomes an
/// unqueryable folksonomy, and `contradicts` feeds the lint pass.
#[derive(
Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, schemars::JsonSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum Relation {
/// The source page describes a cause of the target.
Causes,
/// The source page fixes the problem the target describes.
Fixes,
/// The source page contradicts the target (lint surfaces these).
Contradicts,
}
impl Relation {
/// Stored `links.link_type` value.
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Self::Causes => "causes",
Self::Fixes => "fixes",
Self::Contradicts => "contradicts",
}
}
/// Parse a frontmatter `relations:` key. Unknown names → `None`.
#[must_use]
pub fn parse(s: &str) -> Option<Self> {
match s {
"causes" => Some(Self::Causes),
"fixes" => Some(Self::Fixes),
"contradicts" => Some(Self::Contradicts),
_ => None,
}
}
/// Every relation, for schema/docs enumeration.
pub const ALL: [Self; 3] = [Self::Causes, Self::Fixes, Self::Contradicts];
}
impl LinkTarget {
/// A link resolving within the source page's own project.
#[must_use]
pub fn local(path: PagePath) -> Self {
Self {
workspace: None,
project: None,
path,
relation: None,
}
}
/// Whether this link names a different project than its source.
#[must_use]
pub fn is_cross_project(&self) -> bool {
self.project.is_some()
}
}
impl From<PagePath> for LinkTarget {
fn from(path: PagePath) -> Self {
Self::local(path)
}
}
/// Materialised view of a page row.
#[derive(Clone, Debug)]
pub struct Page {
/// Stable identifier for this page *version*.
pub id: PageId,
/// Owning workspace.
pub workspace_id: WorkspaceId,
/// Owning project.
pub project_id: ProjectId,
/// Relative path within the wiki tree.
pub path: PagePath,
/// Page title.
pub title: String,
/// Markdown body.
pub body: String,
/// SHA-256 of [`Self::body`].
pub body_sha256: [u8; 32],
/// Tier classification.
pub tier: Tier,
/// Frontmatter as JSON.
pub frontmatter: serde_json::Value,
/// `true` if this row is the current visible version.
pub is_latest: bool,
/// Previous version of this page, if any.
pub supersedes: Option<PageId>,
/// `true` if the user has pinned this page (decay sweep skips it).
pub pinned: bool,
/// Wall-clock creation time of *this version*.
pub created_at: Timestamp,
/// Wall-clock last-update time of *this version*.
pub updated_at: Timestamp,
/// TTL instant, if the page carries a frontmatter `expires_at:`.
pub expires_at: Option<Timestamp>,
}
impl Tier {
/// Every tier, in declaration order.
pub const ALL: [Self; 4] = [
Self::Working,
Self::Episodic,
Self::Semantic,
Self::Procedural,
];
/// Canonical short string for storage and serialisation.
#[must_use]
pub const fn as_str(&self) -> &'static str {
match self {
Self::Working => "working",
Self::Episodic => "episodic",
Self::Semantic => "semantic",
Self::Procedural => "procedural",
}
}
}
/// An explicit judgement on how useful a recalled page was.
///
/// The M8 decay formula's only reinforcement signal is the access
/// counter every search hit bumps, which cannot distinguish "this page
/// answered the question" from "this page surfaced and wasted a read".
/// These four signals close that gap: `Helpful` / `NotHelpful` nudge the
/// page's salience (bounded, see the store's feedback op), while `Stale`
/// / `Wrong` additionally route the page into the next `memory_lint`
/// report rather than deleting anything — an agent's judgement lowers
/// confidence, it does not destroy memory.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, schemars::JsonSchema)]
#[schemars(extend("type" = "string"))]
#[serde(rename_all = "snake_case")]
pub enum FeedbackKind {
/// The page answered the question it surfaced for.
Helpful,
/// The page surfaced but did not help.
NotHelpful,
/// The content is outdated — the page needs a refresh.
Stale,
/// The content is factually wrong, not merely dated.
Wrong,
}
impl FeedbackKind {
/// Canonical short string for storage and serialisation. Matches the
/// `page_feedback.kind` CHECK constraint (V37).
#[must_use]
pub const fn as_str(&self) -> &'static str {
match self {
Self::Helpful => "helpful",
Self::NotHelpful => "not_helpful",
Self::Stale => "stale",
Self::Wrong => "wrong",
}
}
/// Whether this signal should surface as a `memory_lint` finding.
#[must_use]
pub const fn routes_to_lint(&self) -> bool {
matches!(self, Self::Stale | Self::Wrong)
}
}
impl FromStr for FeedbackKind {
type Err = crate::MemoryError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"helpful" => Ok(Self::Helpful),
"not_helpful" => Ok(Self::NotHelpful),
"stale" => Ok(Self::Stale),
"wrong" => Ok(Self::Wrong),
other => Err(crate::MemoryError::MalformedRecord(format!(
"unknown feedback kind: {other} (want helpful|not_helpful|stale|wrong)"
))),
}
}
}
impl FromStr for Tier {
type Err = crate::MemoryError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"working" => Ok(Self::Working),
"episodic" => Ok(Self::Episodic),
"semantic" => Ok(Self::Semantic),
"procedural" => Ok(Self::Procedural),
other => Err(crate::MemoryError::MalformedRecord(format!(
"unknown tier: {other}"
))),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A relation target's scope must be one `ai_memory_wiki::split_scope`
/// recognises. It accepts only alphanumerics and `-_/.`, and on anything
/// else it returns no scope and leaves the colon inside the page path —
/// a path `PagePath::new` accepts but `ensure_portable` refuses, so no
/// page write could ever create it and the `links` row stays unresolved
/// forever. A space is the realistic case: project names come from folder
/// basenames.
#[test]
fn page_write_metadata_refuses_a_scope_the_link_reader_cannot_parse() {
let metadata = |target: &str| -> PageWriteMetadata {
serde_json::from_value(serde_json::json!({
"relations": {"fixes": [target]}
}))
.unwrap()
};
for target in ["my project:notes/x", "a+b:notes/x", "ws/my project:notes/x"] {
assert!(
metadata(target).into_frontmatter().is_err(),
"{target} must be refused"
);
}
// Control: a scope the reader does parse still writes.
for target in ["other:notes/x", "workspace/other:notes/x"] {
assert!(
metadata(target).into_frontmatter().is_ok(),
"{target} must stay accepted"
);
}
}
#[test]
fn page_write_metadata_scope_components_refuse_surrounding_whitespace() {
for target in ["other:notes/x", "workspace/other:notes/x"] {
let metadata: PageWriteMetadata = serde_json::from_value(serde_json::json!({
"relations": {"fixes": [target]}
}))
.unwrap();
assert!(metadata.into_frontmatter().is_ok(), "{target}");
}
for target in [
"other :notes/x",
" other:notes/x",
"workspace /other:notes/x",
"workspace/ other:notes/x",
"workspace/other :notes/x",
] {
let metadata: PageWriteMetadata = serde_json::from_value(serde_json::json!({
"relations": {"fixes": [target]}
}))
.unwrap();
assert!(metadata.into_frontmatter().is_err(), "{target}");
}
}
#[test]
fn page_write_metadata_limits_apply_before_trimming_and_normalization() {
let raw = format!("{} ", "x".repeat(60));
assert_eq!(normalize_entity(&raw), Some("x".repeat(60)));
for payload in [
serde_json::json!({"kind": raw}),
serde_json::json!({"entities": [raw]}),
serde_json::json!({"abstract": format!("{} ", "x".repeat(1020))}),
] {
let metadata: PageWriteMetadata = serde_json::from_value(payload.clone()).unwrap();
assert!(metadata.into_frontmatter().is_err(), "{payload}");
}
}
#[test]
fn page_write_metadata_bounds_and_legacy_defaults() {
let empty: PageWriteMetadata = serde_json::from_value(serde_json::json!({})).unwrap();
assert!(empty.into_frontmatter().unwrap().is_empty());
let at_limit: PageWriteMetadata = serde_json::from_value(serde_json::json!({
"kind": "é".repeat(MAX_PAGE_KIND_LEN),
"abstract": "é".repeat(MAX_PAGE_ABSTRACT_LEN),
"entities": (0..MAX_ENTITIES_PER_PAGE).map(|i| format!("Entity {i}")).collect::<Vec<_>>(),
"relations": {"contradicts": vec!["notes/target"; MAX_PAGE_RELATIONS]},
})).unwrap();
let fm = at_limit.into_frontmatter().unwrap();
assert_eq!(fm["entities"][0], "entity 0");
assert_eq!(
fm["relations"]["contradicts"].as_array().unwrap().len(),
MAX_PAGE_RELATIONS
);
for bad in [
serde_json::json!({"kind": "bad\0kind"}),
serde_json::json!({"abstract": "bad\u{7}summary"}),
serde_json::json!({"entities": ["bad\0entity"]}),
serde_json::json!({"entities": [""]}),
serde_json::json!({"relations": {"fixes": ["scope\n:notes/target"]}}),
serde_json::json!({"relations": {"causes": ["/notes/target.md"]}}),
serde_json::json!({"relations": {"causes": ["notes/.git/config.md"]}}),
serde_json::json!({"relations": {"causes": ["notes/file.txt"]}}),
serde_json::json!({"relations": {"causes": ["/target"]}}),
serde_json::json!({"relations": {"causes": ["ws/:target"]}}),
serde_json::json!({"relations": {"causes": ["a/b/c:target"]}}),
serde_json::json!({"relations": {"causes": ["x".repeat(MAX_PAGE_RELATION_TARGET_LEN + 1)]}}),
serde_json::json!({"relations": {"causes": vec!["target"; 16], "fixes": vec!["target"; 17]}}),
] {
let metadata: PageWriteMetadata = serde_json::from_value(bad.clone()).unwrap();
assert!(metadata.into_frontmatter().is_err(), "{bad}");
}
for bad in [
serde_json::json!({"kind": 42}),
serde_json::json!({"abstract": []}),
serde_json::json!({"entities": [42]}),
serde_json::json!({"relations": {"depends_on": ["target"]}}),
serde_json::json!({"relations": {"fixes": "target"}}),
] {
assert!(
serde_json::from_value::<PageWriteMetadata>(bad.clone()).is_err(),
"{bad}"
);
}
}
#[test]
fn page_write_metadata_profile_fields_normalize_like_the_digest_reads_them() {
let metadata: PageWriteMetadata = serde_json::from_value(serde_json::json!({
"applies_to": [" TypeScript ", "rust", "typescript", ""],
"enforced_by": " pre-push hook ",
}))
.unwrap();
let fm = metadata.into_frontmatter().unwrap();
assert_eq!(fm["applies_to"], serde_json::json!(["rust", "typescript"]));
assert_eq!(fm["enforced_by"], "pre-push hook");
// What the write stores, the digest reads back unchanged.
let entry = crate::profile::ProfileEntry::from_page(
"profile/style/types.md",
"Types",
"Never cast.",
&serde_json::Value::Object(fm),
)
.unwrap();
assert_eq!(entry.applies_to, ["rust", "typescript"]);
assert!(entry.enforced_by);
let blank: PageWriteMetadata = serde_json::from_value(serde_json::json!({
"applies_to": [" "], "enforced_by": " ",
}))
.unwrap();
assert!(blank.into_frontmatter().unwrap().is_empty());
}
#[test]
fn page_write_metadata_profile_fields_refuse_unknown_and_oversized_input() {
for bad in [
serde_json::json!({"applies_to": ["rsut"]}),
serde_json::json!({"applies_to": ["rust", "react"]}),
serde_json::json!({"applies_to": ["x".repeat(MAX_PAGE_APPLIES_TO_TAG_LEN + 1)]}),
serde_json::json!({"applies_to": vec!["rust"; MAX_PAGE_APPLIES_TO + 1]}),
serde_json::json!({"applies_to": ["ru\0st"]}),
serde_json::json!({"enforced_by": "x".repeat(MAX_PAGE_ENFORCED_BY_LEN + 1)}),
serde_json::json!({"enforced_by": "hook\u{7}"}),
] {
let metadata: PageWriteMetadata = serde_json::from_value(bad.clone()).unwrap();
assert!(metadata.into_frontmatter().is_err(), "{bad}");
}
for bad in [
serde_json::json!({"applies_to": "rust"}),
serde_json::json!({"enforced_by": true}),
] {
assert!(
serde_json::from_value::<PageWriteMetadata>(bad.clone()).is_err(),
"{bad}"
);
}
}
#[test]
fn profile_metadata_is_refused_outside_profile_pages() {
let fm = serde_json::from_value::<PageWriteMetadata>(serde_json::json!({
"applies_to": ["rust"]
}))
.unwrap()
.into_frontmatter()
.unwrap();
let profile = PagePath::new("profile/tools/cargo.md").unwrap();
let note = PagePath::new("notes/cargo.md").unwrap();
assert!(ensure_profile_metadata_placement(&fm, &profile, true).is_ok());
assert!(ensure_profile_metadata_placement(&fm, ¬e, true).is_err());
// A `profile/` path in an ordinary project is never read either.
assert!(ensure_profile_metadata_placement(&fm, &profile, false).is_err());
let enforced = serde_json::from_value::<PageWriteMetadata>(serde_json::json!({
"enforced_by": "hook"
}))
.unwrap()
.into_frontmatter()
.unwrap();
assert!(ensure_profile_metadata_placement(&enforced, ¬e, true).is_err());
// Ordinary metadata stays allowed everywhere.
let plain = serde_json::from_value::<PageWriteMetadata>(serde_json::json!({
"kind": "rule"
}))
.unwrap()
.into_frontmatter()
.unwrap();
assert!(ensure_profile_metadata_placement(&plain, ¬e, false).is_ok());
}
#[test]
fn tier_round_trips() {
for t in [
Tier::Working,
Tier::Episodic,
Tier::Semantic,
Tier::Procedural,
] {
assert_eq!(t.as_str().parse::<Tier>().unwrap(), t);
}
}
#[test]
fn tier_all_lists_every_variant() {
// An exhaustive match: a new variant fails to compile here until it is
// added to `ALL`, which the web search's tier filter offers.
for (index, tier) in Tier::ALL.into_iter().enumerate() {
let expected = match tier {
Tier::Working => 0,
Tier::Episodic => 1,
Tier::Semantic => 2,
Tier::Procedural => 3,
};
assert_eq!(index, expected);
}
}
#[test]
fn tier_rejects_unknown() {
assert!("nope".parse::<Tier>().is_err());
}
#[test]
fn tier_serde() {
assert_eq!(
serde_json::to_string(&Tier::Procedural).unwrap(),
"\"procedural\""
);
}
#[test]
fn feedback_kind_round_trips_and_flags_lint_routing() {
for k in [
FeedbackKind::Helpful,
FeedbackKind::NotHelpful,
FeedbackKind::Stale,
FeedbackKind::Wrong,
] {
assert_eq!(k.as_str().parse::<FeedbackKind>().unwrap(), k);
}
assert!("nope".parse::<FeedbackKind>().is_err());
assert!(!FeedbackKind::Helpful.routes_to_lint());
assert!(!FeedbackKind::NotHelpful.routes_to_lint());
assert!(FeedbackKind::Stale.routes_to_lint());
assert!(FeedbackKind::Wrong.routes_to_lint());
}
#[test]
fn normalize_entity_lowercases_trims_and_collapses() {
assert_eq!(
normalize_entity(" Postgres ").as_deref(),
Some("postgres")
);
assert_eq!(
normalize_entity("Writer\n\tActor").as_deref(),
Some("writer actor")
);
assert_eq!(normalize_entity(" ").as_deref(), None);
assert_eq!(normalize_entity("").as_deref(), None);
assert_eq!(
normalize_entity(&"x".repeat(MAX_ENTITY_LEN)).as_deref(),
Some("x".repeat(MAX_ENTITY_LEN).as_str()),
);
assert_eq!(normalize_entity(&"x".repeat(MAX_ENTITY_LEN + 1)), None);
assert_eq!(normalize_entity("writer\0actor"), None);
assert_eq!(normalize_entity(&"x".repeat(1_000_000)), None);
}
#[test]
fn normalize_entities_dedupes_preserves_order_and_caps() {
assert_eq!(
normalize_entities(["SQLite", "sqlite", " FTS5 ", ""]),
vec!["sqlite".to_string(), "fts5".to_string()],
);
let many: Vec<String> = (0..MAX_ENTITIES_PER_PAGE + 5)
.map(|i| format!("entity{i}"))
.collect();
assert_eq!(normalize_entities(&many).len(), MAX_ENTITIES_PER_PAGE);
}
#[test]
fn page_evidence_kind_round_trips() {
for k in [
PageEvidenceKind::Session,
PageEvidenceKind::Observation,
PageEvidenceKind::Feedback,
PageEvidenceKind::Reconsolidation,
] {
assert_eq!(k.as_str().parse::<PageEvidenceKind>().unwrap(), k);
}
assert!("nope".parse::<PageEvidenceKind>().is_err());
}
#[test]
fn frontmatter_entity_names_merges_entities_and_tags_leniently() {
// Explicit entities first (they win the cap), then tags; dupes drop.
assert_eq!(
frontmatter_entity_names(&serde_json::json!({
"entities": ["FTS5"],
"tags": ["fts5", "Search"],
})),
vec!["fts5".to_string(), "search".to_string()],
);
// Tags alone are enough — the common case on a mature store.
assert_eq!(
frontmatter_entity_names(&serde_json::json!({"tags": ["Storage"]})),
vec!["storage".to_string()],
);
// Missing or malformed fields contribute nothing, never panic.
assert!(frontmatter_entity_names(&serde_json::json!({})).is_empty());
assert!(
frontmatter_entity_names(&serde_json::json!({"tags": "not-a-list", "entities": 7}))
.is_empty(),
);
}
}