nomograph_workflow/

store.rs

//! Shared Store adapter over `nomograph_claim::Store + View`.
//!
//! Both synthesist and lattice used to own identical copies of this
//! adapter (SynthStore / LattStore). Folded into one type here so the
//! wrapping convention — schema-validated appends, SQLite view synced
//! after each write, session-scoped asserter — has a single source of
//! truth.

use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use nomograph_claim::{Claim, ClaimId, ClaimType, Store as ClaimStore, View};
use serde_json::Value;

use crate::legacy::{find_legacy_v1_db, legacy_migration_error};

/// Directory inside a project that holds the claim substrate.
///
/// Visible name, plural, no nicknames. Matches D3 in
/// `keaton/research/graph-primitive/BUILDING.md`.
pub const CLAIMS_DIR: &str = "claims";

fn local_asserter() -> String {
    let user = std::env::var("USER").unwrap_or_else(|_| "unknown".into());
    format!("user:local:{user}")
}

/// Synthesist / lattice adapter over a project's `claims/` directory.
///
/// Writes go through [`Store::append`]; reads go through
/// [`Store::query`]. Every append syncs the view before returning so
/// follow-up reads see the write.
pub struct Store {
    inner: ClaimStore,
    view: View,
    asserted_by: String,
    root: PathBuf,
}

impl Store {
    /// Open (or initialize) a Store at `<cwd ancestor>/claims/`.
    ///
    /// Walks upward from cwd; initializes in cwd if none found AND no
    /// v1 `.synth/main.db` exists in scope.
    pub fn discover() -> Result<Self> {
        let cwd = std::env::current_dir().context("cwd")?;
        Self::discover_from(&cwd)
    }

    /// Like [`discover`] but starts from a given path.
    ///
    /// Walk-up order:
    ///   1. Any ancestor with a `claims/genesis.amc` → open it.
    ///   2. Otherwise, if any ancestor has a v1 `.synth/main.db`, bail
    ///      with a prescriptive migration error. Silently creating an
    ///      empty v2 estate alongside legacy data orphans the user's
    ///      work; we refuse.
    ///   3. Otherwise, initialize a fresh v2 estate at `start/claims/`.
    pub fn discover_from(start: &Path) -> Result<Self> {
        let mut cur = start.to_path_buf();
        loop {
            let candidate = cur.join(CLAIMS_DIR);
            if candidate.join("genesis.amc").is_file() {
                return Self::open_at(&candidate);
            }
            if !cur.pop() {
                break;
            }
        }
        if let Some(legacy) = find_legacy_v1_db(start) {
            return Err(legacy_migration_error(&legacy));
        }
        Self::init_at(&start.join(CLAIMS_DIR))
    }

    /// Open at an explicit `claims/` directory. The directory must
    /// already contain a `genesis.amc`.
    pub fn open_at(claims_dir: &Path) -> Result<Self> {
        let mut inner = ClaimStore::open(claims_dir)
            .with_context(|| format!("open claim store at {}", claims_dir.display()))?;
        let mut view = View::open(claims_dir)
            .with_context(|| format!("open view at {}", claims_dir.display()))?;
        view.sync(&mut inner).context("sync view on open")?;
        Ok(Self {
            inner,
            view,
            asserted_by: local_asserter(),
            root: claims_dir.to_path_buf(),
        })
    }

    /// Initialize a fresh Store at `claims_dir`.
    pub fn init_at(claims_dir: &Path) -> Result<Self> {
        let inner = ClaimStore::init(claims_dir)
            .with_context(|| format!("init claim store at {}", claims_dir.display()))?;
        let view = View::open(claims_dir)
            .with_context(|| format!("open view at {}", claims_dir.display()))?;
        Ok(Self {
            inner,
            view,
            asserted_by: local_asserter(),
            root: claims_dir.to_path_buf(),
        })
    }

    /// Discover and scope the asserter with an optional session id.
    ///
    /// When a session id is given, subsequent appends assert as
    /// `user:local:<user>:<session>` — giving us attribution without
    /// cryptographic identity (see IDENTITY.md for the v0.2 roadmap).
    pub fn discover_for(session: &Option<String>) -> Result<Self> {
        let mut s = Self::discover()?;
        if let Some(id) = session
            && !id.is_empty()
        {
            s.asserted_by = format!("{}:{}", s.asserted_by, id);
        }
        Ok(s)
    }

    /// Override the asserter prefix. Reserved for tests and for future
    /// callers that set asserter from a parsed Session claim (e.g.
    /// beacon sync, rather than `$USER`).
    #[allow(dead_code)]
    pub fn with_asserter(mut self, asserted_by: impl Into<String>) -> Self {
        self.asserted_by = asserted_by.into();
        self
    }

    /// Append a typed claim. Validates props against the per-type
    /// schema BEFORE the substrate write, so a bad caller gets a
    /// prescriptive error without polluting the claim log. The claim
    /// substrate itself intentionally does not validate (see
    /// claim/src/schema.rs module docs: "validation at the boundary").
    pub fn append(
        &mut self,
        claim_type: ClaimType,
        props: Value,
        supersedes: Option<ClaimId>,
    ) -> Result<ClaimId> {
        let mut claim = Claim::new(claim_type, props, self.asserted_by.clone());
        if let Some(prior) = supersedes {
            claim = claim.with_supersedes(prior);
        }
        nomograph_claim::schema::validate_claim(&claim).context("validate claim before append")?;
        self.inner.append(&claim).context("append claim")?;
        self.view
            .sync(&mut self.inner)
            .context("sync view after append")?;
        Ok(claim.id)
    }

    /// Run a read-only SQL query over the SQLite view.
    pub fn query(&self, sql: &str, params: &[&dyn rusqlite::ToSql]) -> Result<Vec<Value>> {
        self.view.query(sql, params).context("view query")
    }

    /// The `claims/` directory backing this store.
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Force a view rebuild. Most callers don't need this; `append`
    /// syncs automatically.
    #[allow(dead_code)]
    pub fn sync_view(&mut self) -> Result<()> {
        self.view.sync(&mut self.inner).context("sync view")?;
        Ok(())
    }

    /// Access the underlying claim store (for session handles,
    /// compact, merge). Most callers should not need this.
    pub fn inner(&mut self) -> &mut ClaimStore {
        &mut self.inner
    }
}