use serde::{Deserialize, Serialize};
use crate::unit::{Insight, KnowledgeUnit, SCHEMA_VERSION};
pub const EMBED_CHAR_BUDGET: usize = 2_000;
pub const SUMMARY_CHAR_MAX: usize = 200;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct Limits {
pub embed_char_budget: usize,
pub summary_char_max: usize,
pub min_domain_tags: usize,
}
impl Default for Limits {
fn default() -> Self {
Self {
embed_char_budget: EMBED_CHAR_BUDGET,
summary_char_max: SUMMARY_CHAR_MAX,
min_domain_tags: 1,
}
}
}
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum Invalid {
#[error("the summary is empty")]
EmptySummary,
#[error("the action is empty: a unit must say what to do, not only what happened")]
EmptyAction,
#[error("the summary is {chars} characters; the limit is {max}")]
SummaryTooLong {
chars: usize,
max: usize,
},
#[error(
"the insight is {chars} characters and only the first {budget} reach the embedding model; \
front-load the searchable facts and carry the remaining {overflow} characters in a linked \
continuation unit"
)]
InsightExceedsEmbeddingWindow {
chars: usize,
budget: usize,
overflow: usize,
},
#[error("the unit carries {have} domain tags; at least {need} is required")]
NotEnoughDomainTags {
have: usize,
need: usize,
},
#[error("the id does not match the unit's content: expected {expected}, found {found}")]
IdNotContentAddressed {
expected: String,
found: String,
},
#[error("unsupported schema version {found}; this build reads {supported}")]
UnsupportedVersion {
found: String,
supported: &'static str,
},
#[error("confidence {0} is not in 0.0..=1.0")]
ConfidenceOutOfRange(f64),
}
impl Eq for Invalid {}
pub fn overflow_chars(insight: &Insight, limits: &Limits) -> usize {
insight
.embedded_len()
.saturating_sub(limits.embed_char_budget)
}
pub fn validate(unit: &KnowledgeUnit, limits: &Limits) -> Result<(), Vec<Invalid>> {
let mut errs = Vec::new();
if unit.insight.summary.is_empty() {
errs.push(Invalid::EmptySummary);
}
if unit.insight.action.is_empty() {
errs.push(Invalid::EmptyAction);
}
let summary_chars = unit.insight.summary.chars().count();
if summary_chars > limits.summary_char_max {
errs.push(Invalid::SummaryTooLong {
chars: summary_chars,
max: limits.summary_char_max,
});
}
let overflow = overflow_chars(&unit.insight, limits);
if overflow > 0 {
errs.push(Invalid::InsightExceedsEmbeddingWindow {
chars: unit.insight.embedded_len(),
budget: limits.embed_char_budget,
overflow,
});
}
if unit.domain.len() < limits.min_domain_tags {
errs.push(Invalid::NotEnoughDomainTags {
have: unit.domain.len(),
need: limits.min_domain_tags,
});
}
if unit.version != SCHEMA_VERSION {
errs.push(Invalid::UnsupportedVersion {
found: unit.version.clone(),
supported: SCHEMA_VERSION,
});
}
if !(0.0..=1.0).contains(&unit.evidence.confidence) || unit.evidence.confidence.is_nan() {
errs.push(Invalid::ConfidenceOutOfRange(unit.evidence.confidence));
}
let expected = crate::id::UnitId::mint(
&unit.provenance.proposer_did,
&unit.domain,
&unit.insight.summary,
&unit.insight.detail,
&unit.insight.action,
);
if expected != unit.id {
errs.push(Invalid::IdNotContentAddressed {
expected: expected.to_string(),
found: unit.id.to_string(),
});
}
if errs.is_empty() {
Ok(())
} else {
Err(errs)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::kind::UnitKind;
use crate::time::Timestamp;
use crate::unit::Insight;
fn unit(summary: &str, detail: &str, action: &str) -> KnowledgeUnit {
KnowledgeUnit::propose(
"did:nostr:a",
UnitKind::Pitfall,
["api"],
Insight::new(summary, detail, action),
Timestamp::from_secs(0),
)
}
#[test]
fn a_well_formed_unit_passes() {
assert!(validate(&unit("s", "d", "a"), &Limits::default()).is_ok());
}
#[test]
fn the_embedding_budget_is_enforced_with_the_remedy_in_the_message() {
let u = unit("s", &"x".repeat(3_000), "a");
let errs = validate(&u, &Limits::default()).unwrap_err();
let msg = errs.iter().map(ToString::to_string).collect::<String>();
assert!(msg.contains("continuation unit"), "{msg}");
assert!(msg.contains("1002"), "overflow must be quantified: {msg}");
}
#[test]
fn overflow_is_zero_for_a_unit_that_fits() {
let i = Insight::new("s", "d", "a");
assert_eq!(overflow_chars(&i, &Limits::default()), 0);
}
#[test]
fn multibyte_text_is_counted_in_characters_not_bytes() {
let detail = "日".repeat(1_900);
let u = unit("s", &detail, "a");
assert!(validate(&u, &Limits::default()).is_ok());
}
#[test]
fn every_problem_is_reported_at_once() {
let mut u = unit("", "d", "");
u.domain.clear();
u.version = "9.9.9".into();
u.evidence.confidence = 2.0;
let errs = validate(&u, &Limits::default()).unwrap_err();
assert!(errs.contains(&Invalid::EmptySummary));
assert!(errs.contains(&Invalid::EmptyAction));
assert!(errs
.iter()
.any(|e| matches!(e, Invalid::NotEnoughDomainTags { .. })));
assert!(errs
.iter()
.any(|e| matches!(e, Invalid::UnsupportedVersion { .. })));
assert!(errs.contains(&Invalid::ConfidenceOutOfRange(2.0)));
}
#[test]
fn a_tampered_insight_breaks_the_content_address() {
let mut u = unit("s", "d", "a");
u.insight.detail = "something else entirely".into();
let errs = validate(&u, &Limits::default()).unwrap_err();
assert!(errs
.iter()
.any(|e| matches!(e, Invalid::IdNotContentAddressed { .. })));
}
}