Struct SessionTargetHandle 

pub struct SessionTargetHandle<'a> { /* private fields */ }

A scoped handle for operations on a specific target within a session.

Created via Session::target(). Carries the target, email, and timestamp from the session so callers never have to pass them.

Example

let session = Session::discover()?;
let handle = session.target(&Target::parse("commit:abc123")?);
handle.set("agent:model", "claude")?;
let val = handle.get_value("agent:model")?;

Implementations

impl<'a> SessionTargetHandle<'a>

pub fn get_value(&self, key: &str) -> Result<Option<MetaValue>>

Get a metadata value by key.

pub fn set(&self, key: &str, value: impl Into<MetaValue>) -> Result<()>

Set a metadata value with convenience conversion.

Accepts anything that converts to MetaValue: &str, String, Vec<ListEntry>, BTreeSet<String>, or MetaValue directly.

handle.set("key", "hello")?;                    // string
handle.set("key", MetaValue::String("hello".into()))?; // explicit

Uses the session’s email and timestamp automatically.

pub fn set_record(&self, prefix: &str, record: impl Serialize) -> Result<()>

Merge string metadata fields under a common key prefix.

The record must serialize to a JSON object. Object field names, including serde renames, become key suffixes. String values are written as prefix:field.

This is a partial update, not a replacement operation. Null fields are skipped and existing keys are left untouched. This makes Option<T> fields useful for patch-style records, but callers that need to clear a field must remove that key explicitly.

#[derive(serde::Serialize)]
#[serde(rename_all = "kebab-case")]
struct Source<'a> {
    agent: &'a str,
    tool_version: Option<&'a str>,
}

handle.set_record("agent-session:abc:source:def", &Source {
    agent: "codex",
    tool_version: Some("1.2.3"),
})?;

// Later updates that serialize `tool_version` as null do not remove the
// existing `agent-session:abc:source:def:tool-version` key.
handle.set_record("agent-session:abc:source:def", &Source {
    agent: "codex",
    tool_version: None,
})?;

pub fn get_record<T>(&self, prefix: &str) -> Result<Option<T>>

where T: DeserializeOwned,

Read string metadata fields under a common key prefix into a record.

This is the read-side pair to set_record. Immediate child keys like prefix:field become JSON object fields before being deserialized into T. Missing records return Ok(None). Nested keys such as prefix:child:field are ignored because they belong to a deeper metadata subtree, not this record.

Because set_record leaves null or omitted fields untouched, get_record reads the current merged field set under the prefix, not the exact last value passed to set_record.

Errors

Returns an error if an immediate child field exists but is not a string, or if the collected fields do not deserialize into T.

pub fn remove(&self, key: &str) -> Result<bool>

Remove a metadata key.

Uses the session’s email and timestamp automatically.

pub fn list_push(&self, key: &str, value: &str) -> Result<()>

Push a value onto a list.

Uses the session’s email and timestamp automatically.

pub fn apply_edits<'b>( &self, edits: impl IntoIterator<Item = MetaEdit<'b>>, ) -> Result<()>

Apply list/set edits in one transaction.

Empty edit batches are no-ops. If any edit fails, none of the batch is committed. The session email and timestamp are used for every edit.

pub fn list_pop(&self, key: &str, value: &str) -> Result<()>

Pop a value from a list.

Uses the session’s email and timestamp automatically.

pub fn list_remove(&self, key: &str, index: usize) -> Result<()>

Remove a list entry by index.

Uses the session’s email and timestamp automatically.

pub fn set_add(&self, key: &str, value: &str) -> Result<()>

Add a member to a set.

Uses the session’s email and timestamp automatically.

pub fn set_remove(&self, key: &str, value: &str) -> Result<()>

Remove a member from a set.

Uses the session’s email and timestamp automatically.

pub fn target(&self) -> &Target

The target this handle is scoped to.

pub fn get_all_values( &self, prefix: Option<&str>, ) -> Result<Vec<(String, MetaValue)>>

Get all metadata for this target as typed (key, value) pairs.

Optionally filters by key prefix (e.g., Some("agent") returns all keys starting with agent or agent:).

Parameters

• prefix: optional key prefix to filter by

Returns

A vector of (key, MetaValue) pairs for matching metadata entries.

Errors

Returns an error if the database read or deserialization fails.

pub fn list_entries(&self, key: &str) -> Result<Vec<ListEntry>>

Get list entries for a key on this target.

Parameters

• key: the metadata key name

Returns

A vector of ListEntry values with resolved content and timestamps.

Errors

Returns an error if the key is missing, the value is not a list, or the database read fails.

pub fn get_authorship(&self, key: &str) -> Result<Option<Authorship>>

Get authorship info (last author email and timestamp) for a key on this target.

Parameters

• key: the metadata key name

Returns

Some(Authorship) if the key has been modified at least once, None otherwise.

Errors

Returns an error if the database read fails.