use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;
use crate::learn::{
canary_admits, surface_for_kind, Candidate, CandidateId, CandidateKind, EnvironmentTag,
SurfaceKey, VersionPointer,
};
use crate::memory::ProvenanceAuthor;
use crate::record::{canonicalize_value, sha256_hex};
pub const MAX_ARTIFACT_NAME_LEN: usize = 128;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ArtifactCommit {
pub candidate_id: CandidateId,
pub committed_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactRecord {
pub surface: SurfaceKey,
pub family: CandidateKind,
pub owner: ProvenanceAuthor,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub commits: Vec<ArtifactCommit>,
pub created_at: DateTime<Utc>,
}
impl ArtifactRecord {
pub fn new(
family: CandidateKind,
name: impl Into<String>,
owner: ProvenanceAuthor,
created_at: DateTime<Utc>,
) -> Result<Self, RegistryError> {
let name = name.into();
validate_artifact_name(&name)?;
Ok(Self {
surface: surface_for_kind(family, &name),
family,
owner,
commits: Vec::new(),
created_at,
})
}
pub fn name(&self) -> &str {
let prefix = surface_for_kind(self.family, "");
self.surface
.as_str()
.strip_prefix(prefix.as_str())
.unwrap_or_else(|| self.surface.as_str())
}
pub fn latest(&self) -> Option<&ArtifactCommit> {
self.commits.last()
}
pub fn find_commit(&self, candidate_id: &CandidateId) -> Option<&ArtifactCommit> {
self.commits
.iter()
.find(|commit| &commit.candidate_id == candidate_id)
}
pub fn admit_commit(
&self,
candidate: &Candidate,
committed_at: DateTime<Utc>,
) -> Result<ArtifactCommit, RegistryError> {
if candidate.kind() != self.family {
return Err(RegistryError::FamilyMismatch {
artifact: self.family,
candidate: candidate.kind(),
});
}
if candidate.surface() != self.surface {
return Err(RegistryError::SurfaceMismatch {
artifact: self.surface.clone(),
candidate: candidate.surface(),
});
}
if self.find_commit(&candidate.candidate_id).is_some() {
return Err(RegistryError::DuplicateCommit {
candidate_id: candidate.candidate_id.clone(),
});
}
Ok(ArtifactCommit {
candidate_id: candidate.candidate_id.clone(),
committed_at,
})
}
}
fn validate_artifact_name(name: &str) -> Result<(), RegistryError> {
let refuse = |reason: &'static str| RegistryError::InvalidName {
name: name.to_owned(),
reason,
};
if name.is_empty() {
return Err(refuse("empty — an artifact exists to be named"));
}
if name.len() > MAX_ARTIFACT_NAME_LEN {
return Err(refuse("over 128 bytes"));
}
if name != name.trim() {
return Err(refuse(
"leading or trailing whitespace — visually identical names would be distinct \
artifacts, which is a misreview waiting to happen",
));
}
if name.chars().any(|c| c.is_control() || c == '@' || c == '/') {
return Err(refuse(
"carries a control character, `@`, or `/` — the tag separator and the tenant \
separator are structural, and control characters have no business in a key",
));
}
Ok(())
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "view", rename_all = "snake_case")]
pub enum RegistryDiff {
Text {
lines: Vec<TextDiffLine>,
},
Structural {
added: Vec<LeafChange>,
removed: Vec<LeafChange>,
changed: Vec<LeafModification>,
},
}
impl RegistryDiff {
pub fn is_empty(&self) -> bool {
match self {
RegistryDiff::Text { lines } => lines
.iter()
.all(|line| matches!(line, TextDiffLine::Context(_))),
RegistryDiff::Structural {
added,
removed,
changed,
} => added.is_empty() && removed.is_empty() && changed.is_empty(),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "op", content = "line", rename_all = "snake_case")]
pub enum TextDiffLine {
Context(String),
Removed(String),
Added(String),
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LeafChange {
pub path: String,
pub value: Value,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LeafModification {
pub path: String,
pub from: Value,
pub to: Value,
}
pub fn diff_candidates(from: &Candidate, to: &Candidate) -> Result<RegistryDiff, RegistryError> {
if from.kind() != to.kind() {
return Err(RegistryError::DiffAcrossKinds {
from: from.kind(),
to: to.kind(),
});
}
if let (
crate::learn::CandidateContent::Prompt { prompt: base, .. },
crate::learn::CandidateContent::Prompt { prompt: target, .. },
) = (&from.content, &to.content)
{
return Ok(RegistryDiff::Text {
lines: diff_lines(base, target),
});
}
let base = canonicalize_value(
&serde_json::to_value(&from.content)
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?,
);
let target = canonicalize_value(
&serde_json::to_value(&to.content)
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?,
);
let mut added = Vec::new();
let mut removed = Vec::new();
let mut changed = Vec::new();
diff_values("", &base, &target, &mut added, &mut removed, &mut changed);
Ok(RegistryDiff::Structural {
added,
removed,
changed,
})
}
fn diff_values(
path: &str,
base: &Value,
target: &Value,
added: &mut Vec<LeafChange>,
removed: &mut Vec<LeafChange>,
changed: &mut Vec<LeafModification>,
) {
match (base, target) {
(Value::Object(base_map), Value::Object(target_map)) => {
for (key, base_value) in base_map {
let child = format!("{path}/{key}");
match target_map.get(key) {
Some(target_value) => {
diff_values(&child, base_value, target_value, added, removed, changed)
}
None => removed.push(LeafChange {
path: child,
value: base_value.clone(),
}),
}
}
for (key, target_value) in target_map {
if !base_map.contains_key(key) {
added.push(LeafChange {
path: format!("{path}/{key}"),
value: target_value.clone(),
});
}
}
}
(Value::Array(base_items), Value::Array(target_items)) => {
let shared = base_items.len().min(target_items.len());
for (index, (base_value, target_value)) in base_items
.iter()
.zip(target_items.iter())
.enumerate()
.take(shared)
{
diff_values(
&format!("{path}/{index}"),
base_value,
target_value,
added,
removed,
changed,
);
}
for (index, base_value) in base_items.iter().enumerate().skip(shared) {
removed.push(LeafChange {
path: format!("{path}/{index}"),
value: base_value.clone(),
});
}
for (index, target_value) in target_items.iter().enumerate().skip(shared) {
added.push(LeafChange {
path: format!("{path}/{index}"),
value: target_value.clone(),
});
}
}
_ => {
if base != target {
changed.push(LeafModification {
path: path.to_owned(),
from: base.clone(),
to: target.clone(),
});
}
}
}
}
fn diff_lines(base: &str, target: &str) -> Vec<TextDiffLine> {
let base: Vec<&str> = base.lines().collect();
let target: Vec<&str> = target.lines().collect();
let mut lcs = vec![vec![0usize; target.len() + 1]; base.len() + 1];
for i in (0..base.len()).rev() {
for j in (0..target.len()).rev() {
lcs[i][j] = if base[i] == target[j] {
lcs[i + 1][j + 1] + 1
} else {
lcs[i + 1][j].max(lcs[i][j + 1])
};
}
}
let mut lines = Vec::new();
let (mut i, mut j) = (0, 0);
while i < base.len() && j < target.len() {
if base[i] == target[j] {
lines.push(TextDiffLine::Context(base[i].to_owned()));
i += 1;
j += 1;
} else if lcs[i + 1][j] >= lcs[i][j + 1] {
lines.push(TextDiffLine::Removed(base[i].to_owned()));
i += 1;
} else {
lines.push(TextDiffLine::Added(target[j].to_owned()));
j += 1;
}
}
lines.extend(
base[i..]
.iter()
.map(|line| TextDiffLine::Removed((*line).to_owned())),
);
lines.extend(
target[j..]
.iter()
.map(|line| TextDiffLine::Added((*line).to_owned())),
);
lines
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PointerBinding {
Active,
Canary,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ConfigResolution {
pub surface: SurfaceKey,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tag: Option<EnvironmentTag>,
pub candidate_id: CandidateId,
pub pointer: PointerBinding,
pub digest: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub model: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub layers: Option<Vec<String>>,
}
pub fn pointer_admission(
pointer: &VersionPointer,
run_id: &str,
) -> Option<(CandidateId, PointerBinding)> {
if let Some(binding) = &pointer.canary {
if canary_admits(binding, &pointer.surface, run_id) {
return Some((binding.candidate_id.clone(), PointerBinding::Canary));
}
}
pointer
.active
.clone()
.map(|candidate_id| (candidate_id, PointerBinding::Active))
}
pub fn resolution_pin(candidate: &Candidate) -> Result<(String, Option<String>), RegistryError> {
match &candidate.content {
crate::learn::CandidateContent::Prompt { prompt, .. } => {
Ok((sha256_hex(prompt.as_bytes()), None))
}
crate::learn::CandidateContent::ToolContract { schema, .. } => {
let bytes = serde_json::to_vec(&canonicalize_value(schema))
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?;
Ok((sha256_hex(&bytes), None))
}
crate::learn::CandidateContent::ModelSettings {
model, parameters, ..
} => {
let bytes = serde_json::to_vec(&canonicalize_value(parameters))
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?;
Ok((sha256_hex(&bytes), Some(model.clone())))
}
crate::learn::CandidateContent::MiddlewareComposition { layers, .. } => {
let value = serde_json::to_value(layers)
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?;
let bytes = serde_json::to_vec(&canonicalize_value(&value))
.map_err(|e| RegistryError::UndiffableContent(e.to_string()))?;
Ok((sha256_hex(&bytes), None))
}
_ => Err(RegistryError::UnresolvableKind {
kind: candidate.kind(),
}),
}
}
#[derive(Debug, Clone, PartialEq, Error)]
pub enum RegistryError {
#[error("invalid artifact name {name:?}: {reason}")]
InvalidName {
name: String,
reason: &'static str,
},
#[error(
"candidate is `{candidate}` but artifact is `{artifact}` — a commit joins the \
artifact of its own family, never another's"
)]
FamilyMismatch {
artifact: CandidateKind,
candidate: CandidateKind,
},
#[error(
"candidate surfaces at `{candidate}` but the artifact is `{artifact}` — a commit \
joins the artifact its own surface names"
)]
SurfaceMismatch {
artifact: SurfaceKey,
candidate: SurfaceKey,
},
#[error(
"candidate `{candidate_id}` is already committed to this artifact — a re-commit is \
the same fact, converged at the route; a second distinct commit needs a distinct \
candidate"
)]
DuplicateCommit {
candidate_id: CandidateId,
},
#[error(
"candidate `{candidate_id}` is not committed to this artifact — a diff views two \
committed versions of one artifact, nothing wider"
)]
NotCommitted {
candidate_id: CandidateId,
},
#[error(
"cannot diff `{from}` against `{to}` — a diff compares two versions of one \
contract; across kinds it compares two different contracts"
)]
DiffAcrossKinds {
from: CandidateKind,
to: CandidateKind,
},
#[error(
"`{kind}` candidates do not resolve into a run manifest at admission — prompts, tool \
contracts, model settings, and middleware compositions bind; the other families pin \
through their own surfaces (the checkpoint header, capsule manifests) or their own waves"
)]
UnresolvableKind {
kind: CandidateKind,
},
#[error("candidate content could not be diffed: {0}")]
UndiffableContent(String),
}