Struct TranscriptWriter 

pub struct TranscriptWriter { /* private fields */ }

Implementations

impl TranscriptWriter

pub fn new(path: &Path) -> Result<Self>

Create (or open) a JSONL transcript file in append mode.

Creates parent directories if they do not already exist. If the file already has content and history-chain verification is configured (see configure_history_integrity), the existing content is scanned and its chain verified before the writer is returned (M3 open-time tail verify/seed) — a writer can never open atop content it hasn’t itself verified, and the running chain state (prev) is seeded from the verified tail so the very next append continues the existing chain rather than restarting it.

Errors

Returns io::Error if the directory cannot be created, the file cannot be opened, or (per NFR-004) the existing content fails chain verification — a broken chain must never be silently opened past.

pub async fn append(&self, seq: u32, message: &Message) -> Result<()>

Append a single message as a JSON line and flush immediately.

MessagePart::Image parts are stripped (via MessagePart::strip_images) from the persisted copy before serialization — they are ephemeral, current-turn-only vision input (spec-072 §4, C1) and must never reach a transcript file on disk, mirroring the strip point already enforced for Agent::persist_message’s SQLite/Qdrant/durable-JSONL writers. The caller’s message is untouched, so callers that hold onto it for the current turn’s provider request keep their Image parts.

When history-chain verification is configured, the chain-link read-modify-write, canonicalization (serialize with chain: None, hash, then serialize again with the computed hash), physical write, and flush all happen inside the same tokio::task::spawn_blocking critical section, under the single lock guarding both the file handle and the running chain state (S2) — so on-disk order always matches chain order even under concurrent append calls from a cloned writer.

Errors

Returns io::Error on serialization, write failure, lock poison, or thread-pool panic.

pub async fn finalize(self) -> Result<()>

Finalize this writer: if a vault-anchor store is configured (issue #6449) and this writer’s lifetime saw at least one chained append, persist an Anchor recording the final (epoch, count, head) — written last, after every append is durably flushed, so a crash before this point leaves the file present with no anchor, which is always benign (never a false tamper signature — see the module-level anchor docs).

A no-op, not an error, when no anchor store is configured or this writer never chained (pure legacy for its whole lifetime): there is nothing to anchor.

Errors

Returns io::Error if the configured anchor store’s put fails (a store-level failure, not an absent anchor). Callers should treat this as best-effort and log rather than fail the whole collection flow — the transcript file itself is already safely written.

pub fn write_meta( dir: &Path, agent_id: &str, meta: &TranscriptMeta, ) -> Result<()>

Write the meta sidecar file for an agent.

Errors

Returns io::Error on serialization or write failure.

pub async fn write_meta_async( dir: &Path, agent_id: &str, meta: &TranscriptMeta, ) -> Result<()>

Async variant of write_meta that offloads the blocking FS write to a spawn_blocking thread so the Tokio executor is not stalled.

Errors

Returns io::Error on serialization, write failure, or thread-pool panic.

Trait Implementations

impl Clone for TranscriptWriter

fn clone(&self) -> TranscriptWriter

Returns a duplicate of the value.

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

Performs copy-assignment from source.