Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
40.5 KB
Raw Blame
//! 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, &note, 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, &note, 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, &note, 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(),
        );
    }
}