khive_runtime/
context.rs

1//! Optional pack capability for returning owned context slices.
2//!
3//! This module defines the contributor boundary only. Discovery does not run contributors;
4//! composition, timeouts, budget allocation and profile resolution belong to callers.
5
6use async_trait::async_trait;
7use khive_storage::Direction;
8use serde::Serialize;
9use serde_json::Value;
10
11use crate::{NamespaceToken, RuntimeError};
12
13/// Owned input to a context contributor, without parsing, defaults or clamping.
14#[derive(Clone, Debug)]
15pub struct ContextRequest {
16    pub query: Option<String>,
17    pub entity_ids: Vec<String>,
18    pub consumer_kind: String,
19    /// Advisory budget for the total assembly, not an allocation to this contributor.
20    pub budget_hint: usize,
21    pub hops: u8,
22    pub fanout: u8,
23    pub direction: Direction,
24    pub relations: Vec<String>,
25}
26
27/// Meaning of a score within its source partition; scores are not cross-pack comparable.
28#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
29#[serde(rename_all = "snake_case")]
30pub enum ScoreSemantics {
31    DecayWeighted,
32    Rerank,
33    GraphProximity,
34    Relevance,
35    None,
36}
37
38/// An owned context record with static pack attribution and an unnormalized local score.
39#[derive(Clone, Debug, Serialize)]
40pub struct ContextSlice {
41    pub source_pack: &'static str,
42    pub kind: String,
43    pub id: String,
44    pub content: Value,
45    pub score: Option<f64>,
46    pub score_semantics: ScoreSemantics,
47}
48
49/// Optional object-safe context source implemented by a pack.
50///
51/// Implementations must honor the supplied namespace token, return owned records, and release
52/// all read snapshots before returning. `budget_hint` is advisory for the entire assembly;
53/// it is not a per-contributor allocation. Returned scores keep their source-local semantics.
54#[async_trait]
55pub trait ContextContributor: Send + Sync {
56    /// Stable pack metadata used to attribute this source.
57    fn source_pack(&self) -> &'static str;
58
59    async fn contribute(
60        &self,
61        req: &ContextRequest,
62        token: &NamespaceToken,
63    ) -> Result<Vec<ContextSlice>, RuntimeError>;
64}
khive_runtime/context.rs

khive_runtime/
context.rs
