Struct GoalStore 

pub struct GoalStore { /* private fields */ }

Persistence layer for long-horizon goals.

Thin wrapper around DbPool. All methods are async and return typed errors.

Invariants

• At most one row with status = 'active' may exist at any time (enforced by the idx_zeph_goals_single_active partial unique index + transactional create).
• Stale transitions (wrong expected_updated_at) return GoalError::StaleUpdate.

TODO(critic): cross-process goal cache invalidation; not handled in v1

Implementations

impl GoalStore

pub fn new(pool: Arc<DbPool>) -> Self

Construct a GoalStore backed by the given pool.

pub async fn create( &self, text: &str, token_budget: Option<u64>, max_chars: usize, ) -> Result<Goal, GoalError>

Create a new goal, atomically pausing any existing Active goal in the same transaction.

Uses BEGIN IMMEDIATE on SQLite / BEGIN + SELECT FOR UPDATE on Postgres to prevent a race between two concurrent /goal create calls.

Errors

Returns GoalError::TextTooLong when text exceeds max_chars. Returns GoalError::Db on database failure.

pub async fn get(&self, id: &str) -> Result<Option<Goal>, GoalError>

Fetch a goal by its UUID string.

Errors

Returns GoalError::Db on database failure.

pub async fn active(&self) -> Result<Option<Goal>, GoalError>

Return the currently active goal, if any.

Errors

Returns GoalError::Db on database failure.

pub async fn list(&self, limit: u32) -> Result<Vec<Goal>, GoalError>

Return up to limit goals ordered by created_at DESC.

Errors

Returns GoalError::Db on database failure.

pub async fn transition( &self, id: &str, to: GoalStatus, expected_updated_at: DateTime<Utc>, ) -> Result<Goal, GoalError>

Attempt a CAS-guarded FSM transition.

Returns GoalError::StaleUpdate if the goal was concurrently modified (i.e. the stored updated_at does not match expected_updated_at). The caller should refetch and report the current state without surfacing an error to the user.

Returns GoalError::InvalidTransition for non-FSM-allowed transitions.

Errors

Returns GoalError::NotFound, GoalError::InvalidTransition, GoalError::StaleUpdate, or GoalError::Db.

pub async fn record_turn( &self, id: &str, turn_tokens: u64, ) -> Result<Goal, GoalError>

Increment turns_used by 1 and tokens_used by turn_tokens.

Called once per turn by crate::goal::GoalAccounting::on_turn_complete. Returns the updated goal.

Errors

Returns GoalError::Db on database failure.

Trait Implementations

impl Clone for GoalStore

fn clone(&self) -> GoalStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.