Trait CardStore 

pub trait CardStore: Send + Sync {
    // Required methods
    fn write_new_card(
        &self,
        pkg: &str,
        card_id: &str,
        toml_text: &str,
    ) -> Result<PathBuf, String>;
    fn overwrite_card(
        &self,
        card_id: &str,
        toml_text: &str,
    ) -> Result<PathBuf, String>;
    fn find_card_locator(
        &self,
        card_id: &str,
    ) -> Result<Option<PathBuf>, String>;
    fn read_card_text(&self, card_id: &str) -> Result<Option<String>, String>;
    fn list_card_locators(
        &self,
        pkg_filter: Option<&str>,
    ) -> Result<Vec<(String, PathBuf)>, String>;
    fn read_locator_text(
        &self,
        locator: &Path,
    ) -> Result<Option<String>, String>;
    fn read_aliases(&self) -> Result<Vec<Alias>, String>;
    fn write_aliases(&self, aliases: &[Alias]) -> Result<(), String>;
    fn samples_exists(&self, card_id: &str) -> Result<bool, String>;
    fn write_samples_text(
        &self,
        card_id: &str,
        jsonl_text: &str,
    ) -> Result<PathBuf, String>;
    fn read_samples_text(&self, card_id: &str) -> Result<Option<String>, String>;
    fn import_from_dir(
        &self,
        source_dir: &Path,
        pkg: &str,
    ) -> Result<(Vec<String>, Vec<String>), String>;
}

Storage backend for Cards.

Implementations must be Send + Sync so that they can be shared across Lua host threads safely. All methods may fail with an error String describing the backend-specific failure.

Required Methods

fn write_new_card( &self, pkg: &str, card_id: &str, toml_text: &str, ) -> Result<PathBuf, String>

Write a new Card (Tier 1 TOML).

The caller has already:

• validated pkg and card_id via [validate_name]
• serialized toml_text with toml::to_string_pretty

Fails if a Card with the same id already exists (immutability). Returns the locator of the written Card.

fn overwrite_card( &self, card_id: &str, toml_text: &str, ) -> Result<PathBuf, String>

Overwrite an existing Card (append flow).

Append is additive-only w.r.t. keys, but the underlying TOML file is rewritten in place; callers must have validated the additive-only constraint before calling this.

fn find_card_locator(&self, card_id: &str) -> Result<Option<PathBuf>, String>

Locate a Card file by id. Returns None if not found.

fn read_card_text(&self, card_id: &str) -> Result<Option<String>, String>

Read a Card’s raw TOML text by id. Returns None if missing.

fn list_card_locators( &self, pkg_filter: Option<&str>, ) -> Result<Vec<(String, PathBuf)>, String>

List (pkg, locator) pairs for every Card file in the store.

When pkg_filter is Some(name), restrict to that pkg subdir. Non-existent pkg subdir yields an empty Vec.

Order is implementation-defined — callers sort explicitly.

fn read_locator_text(&self, locator: &Path) -> Result<Option<String>, String>

Read raw TOML text from a locator returned by Self::list_card_locators. Ok(None) on read failure so scans can skip corrupt files without aborting.

fn read_aliases(&self) -> Result<Vec<Alias>, String>

fn write_aliases(&self, aliases: &[Alias]) -> Result<(), String>

fn samples_exists(&self, card_id: &str) -> Result<bool, String>

Check whether a samples sidecar exists for card_id.

fn write_samples_text( &self, card_id: &str, jsonl_text: &str, ) -> Result<PathBuf, String>

Write a samples sidecar (write-once).

jsonl_text is the complete JSONL payload (one JSON line per sample, \n-terminated). Fails if a sidecar already exists. Returns the locator.

fn read_samples_text(&self, card_id: &str) -> Result<Option<String>, String>

Read a samples sidecar as raw JSONL text. Returns None when no sidecar exists (samples are optional).

fn import_from_dir( &self, source_dir: &Path, pkg: &str, ) -> Result<(Vec<String>, Vec<String>), String>

Import Card files from source_dir into the store under pkg. First-writer wins (existing Cards are skipped). Returns (imported, skipped) card_id lists.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl CardStore for FileCardStore