Struct RecallRequest 

pub struct RecallRequest {

    pub context: String,
    pub namespace: Option<String>,
    pub limit: Option<i64>,
    pub tags: Option<String>,
    pub since: Option<String>,
    pub until: Option<String>,
    pub as_agent: Option<String>,
    pub budget_tokens: Option<i64>,
    pub context_tokens: Option<Vec<String>>,
    pub session_default: Option<bool>,
    pub session_id: Option<String>,
    pub include_archived: Option<bool>,
    pub has_citations: Option<bool>,
    pub source_uri_prefix: Option<String>,
    pub kinds: Option<KindsFilter>,
    pub confidence_tier: Option<String>,
    pub verbose_provenance: Option<bool>,
    pub format: Option<String>,
}

v0.7.0 #972 D1.3 (#984) / #967 — canonical recall-request DTO.

Marshalled once per surface (HTTP / MCP / CLI), then handed to the downstream recall pipeline. Adding a new field (Form 6 kinds, Form 4 has_citations, confidence_tier, etc.) lands in one place instead of four positional-arg lists.

Schemars contract. Every doc-comment description and field attribute is byte-equal to the legacy hand-coded entry in crate::mcp::registry::tool_definitions — see the d1_3_984_tests::recall_parity_984 parity test which asserts the derived schema matches byte-for-byte.

Fields

context: String

What to recall

namespace: Option<String>

Namespace filter

limit: Option<i64>

tags: Option<String>

Tag filter

since: Option<String>

RFC3339 lower bound on created_at

until: Option<String>

RFC3339 upper bound on created_at

as_agent: Option<String>

budget_tokens: Option<i64>

P6/R1 cl100k content cap. 0=empty; top kept (meta.budget_overflow=true).

context_tokens: Option<Vec<String>>

Recent conversation tokens; biases query embedding 70/30 (v0.6.0.0).

session_default: Option<bool>

Splice [agents.defaults.recall_scope]. explicit > scope > defaults.

session_id: Option<String>

include_archived: Option<bool>

WT-1-E: include atomised sources alongside atoms.

has_citations: Option<bool>

Form 4 (#757): require non-empty citations array.

source_uri_prefix: Option<String>

Form 4 (#757): restrict by source_uri prefix (e.g. ‘doc:’, ‘uri:https://’).

kinds: Option<KindsFilter>

Form 6 (#759) kind filter. Array/CSV. OR within; AND across.

confidence_tier: Option<String>

Gap 4 (#887) tier filter.

verbose_provenance: Option<bool>

Gap 7 (#890): per-row provenance decoration.

format: Option<String>

Response format. toon_compact saves 79% vs json.

Implementations

impl RecallRequest

pub fn from_mcp_params(params: &Value) -> Result<Self, String>

MCP surface: marshal a params JSON bag (the arguments field of a tools/call request) into a typed RecallRequest.

Returns Err when context is missing — every other field is optional and defaults via #[serde(default)]. The legacy handle_recall body used params["context"].as_str().ok_or(...) to enforce the same invariant; this constructor preserves the exact error string for callers that match on it.

On a deserialise failure (e.g. caller passes limit: "ten"), returns the serde error rendered as a string so the MCP dispatcher can return the corresponding -32602 Invalid params.

Errors

Returns Err when:

• context is missing or not a string (“context is required”)
• a typed field receives the wrong JSON shape

Saturation semantics. Pre-#967 the legacy code used params["limit"].as_u64() + usize::try_from(v).unwrap_or(usize::MAX), which silently saturated u64::MAX rather than erroring. The DTO’s limit: Option<i64> would refuse to deserialize a value beyond i64::MAX, so the constructor clamps limit (and budget_tokens) values that exceed the signed range to i64::MAX BEFORE handing the bag to serde. This preserves the limit_overflow_saturates regression test contract.

pub fn from_http_query(q: &RecallQuery) -> Self

HTTP GET surface: marshal a crate::models::RecallQuery into the canonical DTO. context resolution honours the context > query > q precedence the HTTP handler enforces; callers must reject the empty result before recall.

pub fn from_http_body(body: &RecallBody) -> Self

HTTP POST surface: marshal a crate::models::RecallBody into the canonical DTO. context resolution honours the context > query > q precedence the HTTP handler enforces.

pub fn from_cli_args(args: &RecallArgs) -> Self

CLI surface: marshal a crate::cli::recall::RecallArgs (clap- derived) into the canonical DTO.

pub fn resolved_limit(&self) -> usize

Resolved limit clamped to usize. The recall pipeline caps the returned set at min(50) downstream; this constructor just converts the wire Option<i64> into a usable size with a default of 10 when the caller omitted the field.

pub fn resolved_budget_tokens(&self) -> Option<usize>

Resolved budget-tokens limit clamped to usize. None when the caller did not request a budget cap; Some(0) is preserved per the P6/R1 semantics (zero is a legitimate “return nothing” request distinct from “no budget set”).

Trait Implementations

impl Clone for RecallRequest

fn clone(&self) -> RecallRequest

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RecallRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RecallRequest

fn default() -> RecallRequest

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RecallRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for RecallRequest

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl Serialize for RecallRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.