reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
//! The rendering vocabulary every redacting `Debug` in this crate shares.
//!
//! ADR-018 fixes what a `Debug` implementation may print about bytes it did not
//! author. Each wrapper below is one row of that vocabulary, and keeping them in
//! one module is what makes the policy auditable: a reviewer reads four
//! implementations rather than forty-five.
//!
//! Nothing here is public. A caller who wants the redacted bytes reaches for the
//! typed accessor that returns them — `part.fields().text()`,
//! `envelope.data()`, `metadata.get(key)` — which is the whole reason ADR-018
//! refuses an escape hatch.

use std::fmt;

// `README.md` is the front page on GitHub and on crates.io, and its example is
// the first code most readers ever run, so it is compiled: under `cfg(doctest)`
// every Rust block in it becomes a doctest, and the front page cannot drift away
// from the API the way an untested snippet does.
//
// It lives in this file rather than in `lib.rs`, which is where it belongs, for
// a mechanical reason. `lib.rs` is one of the files proved to hold declarations
// and nothing else, and that proof is what exempts a file with no executable
// line from needing a coverage record; `scripts/discover-core-files.py` rejects
// a module with an inline body there, so the hook cannot be written in the file
// it is about. Nothing is rendered either way — `cfg(doctest)` is set while
// rustdoc collects doctests and at no other time.
//
// Among the files that *can* host it, this one is an arbitrary choice and the
// doctest's name says so: it reports as `redact::readme`, which has nothing to do
// with redaction. The alternative is a file that exists only to be the hook's
// home, and that would buy a tidier label by adding a production path to the
// coverage denominator and one more name to the declaration-only exemption list —
// a list whose whole point is that it is a liability rather than an allowance.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
mod readme {}

/// Renders how many bytes a payload holds, never which bytes.
pub(crate) struct Bytes(pub(crate) usize);

impl fmt::Debug for Bytes {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "<{} bytes>", self.0)
    }
}

/// Renders how long a sequence is when its elements do not redact themselves.
pub(crate) struct Items(pub(crate) usize);

impl fmt::Debug for Items {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "<{} items>", self.0)
    }
}

/// Renders whether a credential-shaped field is there, not how large it is.
///
/// A length is withheld here because signature lengths are provider-stable, so
/// one would fingerprint the provider and the reasoning mode that produced a
/// transcript while telling a debugger nothing it can act on.
pub(crate) struct Presence(pub(crate) bool);

impl fmt::Debug for Presence {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(if self.0 { "<present>" } else { "<absent>" })
    }
}

/// Renders a lock this `Debug` declined to wait for.
///
/// Formatting never blocks: a `Debug` that takes a lock deadlocks the moment
/// someone prints a value from inside a critical section.
pub(crate) struct Locked;

impl fmt::Debug for Locked {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("<locked>")
    }
}