use std::collections::HashMap;
use std::io;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use chrono::{DateTime, Utc};
use rusty_agent_runtime::checkpoint::{Checkpoint, Checkpointer};
use rusty_agent_runtime::error::{Result as RuntimeResult, RustyError};
use rusty_agent_runtime::record::{ExecutorPolicy, PolicyVersion};
use serde::{Deserialize, Serialize};
use crate::server_store::{ServerStore, StoreResult};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "source", rename_all = "snake_case")]
pub(crate) enum PolicySource {
Api,
Candidate {
candidate_id: String,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub(crate) struct PolicyRecord {
pub version: PolicyVersion,
pub policy: ExecutorPolicy,
pub source: PolicySource,
pub registered_at: DateTime<Utc>,
}
pub(crate) fn static_floor_record() -> PolicyRecord {
PolicyRecord {
version: PolicyVersion::default(),
policy: ExecutorPolicy::static_v0(),
source: PolicySource::Api,
registered_at: DateTime::<Utc>::from_timestamp(0, 0).unwrap_or_else(Utc::now),
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub(crate) struct PolicyActivation {
pub version: PolicyVersion,
pub activated_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub(crate) struct PolicyBinding {
pub checkpoint_id: String,
pub thread_id: String,
pub version: PolicyVersion,
pub bound_at: DateTime<Utc>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum PolicyWrite {
Created,
Converged,
Conflict,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub(crate) struct PolicyEpoch {
pub version: PolicyVersion,
pub activated_at: DateTime<Utc>,
pub retired_at: Option<DateTime<Utc>>,
pub bindings: Vec<PolicyBinding>,
}
pub(crate) fn derive_epochs(
activations: Vec<PolicyActivation>,
mut bindings: Vec<PolicyBinding>,
) -> Vec<PolicyEpoch> {
bindings.sort_by(|a, b| {
a.bound_at
.cmp(&b.bound_at)
.then_with(|| a.checkpoint_id.cmp(&b.checkpoint_id))
});
let mut epochs = Vec::new();
if let Some(first) = activations.first() {
let floor_bindings: Vec<PolicyBinding> = bindings
.iter()
.filter(|binding| binding.bound_at < first.activated_at)
.cloned()
.collect();
if !floor_bindings.is_empty() {
epochs.push(PolicyEpoch {
version: PolicyVersion::default(),
activated_at: floor_bindings[0].bound_at,
retired_at: Some(first.activated_at),
bindings: floor_bindings,
});
}
}
for (index, activation) in activations.iter().enumerate() {
let retired_at = activations.get(index + 1).map(|next| next.activated_at);
let window: Vec<PolicyBinding> = bindings
.iter()
.filter(|binding| {
binding.bound_at >= activation.activated_at
&& retired_at.is_none_or(|retired| binding.bound_at < retired)
})
.cloned()
.collect();
epochs.push(PolicyEpoch {
version: activation.version.clone(),
activated_at: activation.activated_at,
retired_at,
bindings: window,
});
}
epochs
}
pub(crate) fn validate_policy_version(version: &str) -> Result<(), String> {
let valid = !version.is_empty()
&& version.len() <= 128
&& version
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.'));
if !valid {
return Err(format!(
"invalid policy version `{version}` (allowed: [A-Za-z0-9._-], 1..=128 chars)"
));
}
if version == PolicyVersion::STATIC_V0 {
return Err(format!(
"policy version `{version}` is reserved: the static floor predates the registry \
and is always resolvable — it is never registered"
));
}
Ok(())
}
pub(crate) async fn active_policy_record(
store: &Arc<dyn ServerStore>,
tenant: &str,
) -> StoreResult<PolicyRecord> {
let activations = store.list_policy_activations(tenant).await?;
let Some(active) = activations.last() else {
return Ok(static_floor_record());
};
if active.version.as_str() == PolicyVersion::STATIC_V0 {
return Ok(static_floor_record());
}
store
.get_policy(tenant, active.version.as_str())
.await?
.ok_or_else(|| {
format!(
"active policy version `{}` is not registered — the registry is corrupt",
active.version.as_str()
)
})
}
fn policy_dir(root: &Path) -> PathBuf {
root.join("policy")
}
pub(crate) fn policies_dir(root: &Path) -> PathBuf {
policy_dir(root).join("versions")
}
pub(crate) fn activations_dir(root: &Path) -> PathBuf {
policy_dir(root).join("activations")
}
pub(crate) fn bindings_dir(root: &Path) -> PathBuf {
policy_dir(root).join("bindings")
}
fn collect_json_files(root: &Path, out: &mut Vec<PathBuf>) {
let Ok(entries) = std::fs::read_dir(root) else {
return;
};
for entry in entries.flatten() {
let path = entry.path();
if path.is_dir() {
collect_json_files(&path, out);
} else if path.extension().and_then(|e| e.to_str()) == Some("json") {
out.push(path);
}
}
}
fn path_scoped_name(dir: &Path, path: &Path) -> Option<String> {
path.strip_prefix(dir)
.ok()
.map(|relative| relative.with_extension(""))
.map(|relative| {
relative
.components()
.map(|component| component.as_os_str().to_string_lossy().into_owned())
.collect::<Vec<_>>()
.join("/")
})
}
async fn persist_record<T: Serialize>(
dir: &Path,
scoped_name: &str,
record: &T,
what: &str,
) -> io::Result<()> {
tokio::fs::create_dir_all(dir).await?;
let bytes = serde_json::to_vec_pretty(record)
.map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
let path = dir.join(format!("{scoped_name}.json"));
if let Some(parent) = path.parent() {
tokio::fs::create_dir_all(parent).await?;
}
let tmp = dir.join(format!("{scoped_name}.{what}.tmp"));
tokio::fs::write(&tmp, bytes).await?;
tokio::fs::rename(&tmp, path).await
}
pub(crate) async fn persist_policy(
root: &Path,
scoped_version: &str,
record: &PolicyRecord,
) -> io::Result<()> {
persist_record(&policies_dir(root), scoped_version, record, "policy").await
}
pub(crate) fn load_policies(root: &Path) -> HashMap<String, PolicyRecord> {
let dir = policies_dir(root);
let mut out = HashMap::new();
let mut files = Vec::new();
collect_json_files(&dir, &mut files);
for path in files {
let scoped = path_scoped_name(&dir, &path);
let parsed = std::fs::read_to_string(&path)
.ok()
.and_then(|raw| serde_json::from_str::<PolicyRecord>(&raw).ok());
match (scoped, parsed) {
(Some(name), Some(record)) => {
out.insert(name, record);
}
_ => {
tracing::warn!(path = %path.display(), "skipping unreadable policy file")
}
}
}
out
}
pub(crate) fn activation_file_name(activation: &PolicyActivation) -> String {
format!(
"{:013}-{}",
activation.activated_at.timestamp_millis(),
activation.version.as_str()
)
}
pub(crate) async fn append_activation(
root: &Path,
tenant: &str,
activation: &PolicyActivation,
) -> io::Result<()> {
let scoped = crate::auth::scope_id(tenant, &activation_file_name(activation));
persist_record(&activations_dir(root), &scoped, activation, "activation").await
}
pub(crate) fn load_activations(root: &Path) -> HashMap<String, PolicyActivation> {
let dir = activations_dir(root);
let mut out = HashMap::new();
let mut files = Vec::new();
collect_json_files(&dir, &mut files);
for path in files {
let scoped = path_scoped_name(&dir, &path);
let parsed = std::fs::read_to_string(&path)
.ok()
.and_then(|raw| serde_json::from_str::<PolicyActivation>(&raw).ok());
match (scoped, parsed) {
(Some(name), Some(activation)) => {
out.insert(name, activation);
}
_ => {
tracing::warn!(path = %path.display(), "skipping unreadable activation file")
}
}
}
out
}
pub(crate) async fn persist_binding(
root: &Path,
tenant: &str,
binding: &PolicyBinding,
) -> io::Result<()> {
let scoped = crate::auth::scope_id(tenant, &binding.checkpoint_id);
persist_record(&bindings_dir(root), &scoped, binding, "binding").await
}
pub(crate) fn load_bindings(root: &Path) -> HashMap<String, PolicyBinding> {
let dir = bindings_dir(root);
let mut out = HashMap::new();
let mut files = Vec::new();
collect_json_files(&dir, &mut files);
for path in files {
let scoped = path_scoped_name(&dir, &path);
let parsed = std::fs::read_to_string(&path)
.ok()
.and_then(|raw| serde_json::from_str::<PolicyBinding>(&raw).ok());
match (scoped, parsed) {
(Some(name), Some(binding)) => {
out.insert(name, binding);
}
_ => {
tracing::warn!(path = %path.display(), "skipping unreadable binding file")
}
}
}
out
}
pub(crate) struct PolicyBindingCheckpointer {
inner: Arc<dyn Checkpointer>,
store: Arc<dyn ServerStore>,
}
impl PolicyBindingCheckpointer {
pub(crate) fn new(inner: Arc<dyn Checkpointer>, store: Arc<dyn ServerStore>) -> Self {
Self { inner, store }
}
async fn active_version(&self, tenant: &str) -> StoreResult<PolicyVersion> {
let activations = self.store.list_policy_activations(tenant).await?;
Ok(activations
.last()
.map(|activation| activation.version.clone())
.unwrap_or_default())
}
}
#[async_trait::async_trait]
impl Checkpointer for PolicyBindingCheckpointer {
async fn put(&self, mut checkpoint: Checkpoint) -> RuntimeResult<()> {
if checkpoint.header.policy_version.as_str() == PolicyVersion::STATIC_V0 {
let latest = self.inner.get_latest(&checkpoint.thread_id).await?;
let admission = match &latest {
None => true,
Some(prev) => checkpoint.step == 0 && prev.step > 0,
};
if admission {
let tenant = crate::auth::tenant_of_internal(&checkpoint.thread_id);
let version = self.active_version(tenant).await.map_err(|e| {
RustyError::Checkpoint(format!(
"resolve the active policy version for admission binding: {e}"
))
})?;
checkpoint.header.policy_version = version.clone();
let binding = PolicyBinding {
checkpoint_id: checkpoint.id.clone(),
thread_id: checkpoint.thread_id.clone(),
version,
bound_at: Utc::now(),
};
if let Err(error) = self.store.put_policy_binding(tenant, &binding).await {
tracing::warn!(
checkpoint_id = %binding.checkpoint_id,
%error,
"policy binding evidence lost; the checkpoint header remains authoritative"
);
}
} else if let Some(prev) = latest {
checkpoint.header.policy_version = prev.header.policy_version;
}
}
self.inner.put(checkpoint).await
}
async fn get_latest(&self, thread_id: &str) -> RuntimeResult<Option<Checkpoint>> {
self.inner.get_latest(thread_id).await
}
async fn list(&self, thread_id: &str) -> RuntimeResult<Vec<Checkpoint>> {
self.inner.list(thread_id).await
}
async fn get_by_id(
&self,
thread_id: &str,
checkpoint_id: &str,
) -> RuntimeResult<Option<Checkpoint>> {
self.inner.get_by_id(thread_id, checkpoint_id).await
}
async fn fork_thread(
&self,
src_thread: &str,
dst_thread: &str,
at_checkpoint_id: Option<&str>,
) -> RuntimeResult<usize> {
self.inner
.fork_thread(src_thread, dst_thread, at_checkpoint_id)
.await
}
}
impl std::fmt::Debug for PolicyBindingCheckpointer {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PolicyBindingCheckpointer").finish()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn ts(millis: i64) -> DateTime<Utc> {
DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
}
fn activation(version: &str, millis: i64) -> PolicyActivation {
PolicyActivation {
version: PolicyVersion::new(version),
activated_at: ts(millis),
}
}
fn binding(checkpoint: &str, version: &str, millis: i64) -> PolicyBinding {
PolicyBinding {
checkpoint_id: checkpoint.into(),
thread_id: "t-1".into(),
version: PolicyVersion::new(version),
bound_at: ts(millis),
}
}
#[test]
fn epochs_fold_activations_and_bindings_into_windows() {
let activations = vec![activation("policy-a", 1_000), activation("policy-b", 2_000)];
let bindings = vec![
binding("c-pre", PolicyVersion::STATIC_V0, 500),
binding("c-a1", "policy-a", 1_200),
binding("c-a2", "policy-a", 1_800),
binding("c-b1", "policy-b", 2_500),
];
let epochs = derive_epochs(activations, bindings);
assert_eq!(epochs.len(), 3);
assert_eq!(epochs[0].version.as_str(), PolicyVersion::STATIC_V0);
assert_eq!(epochs[0].retired_at, Some(ts(1_000)));
assert_eq!(epochs[0].bindings.len(), 1);
assert_eq!(epochs[1].version.as_str(), "policy-a");
assert_eq!(epochs[1].activated_at, ts(1_000));
assert_eq!(epochs[1].retired_at, Some(ts(2_000)));
assert_eq!(epochs[1].bindings.len(), 2);
assert_eq!(epochs[2].version.as_str(), "policy-b");
assert_eq!(epochs[2].retired_at, None);
assert_eq!(epochs[2].bindings.len(), 1);
}
#[test]
fn epochs_are_empty_when_the_registry_never_moved() {
assert!(derive_epochs(Vec::new(), Vec::new()).is_empty());
assert!(derive_epochs(
Vec::new(),
vec![binding("c-1", PolicyVersion::STATIC_V0, 1)]
)
.is_empty());
}
#[test]
fn version_validation_accepts_path_safe_names_and_reserves_the_floor() {
assert!(validate_policy_version("policy-0123456789ab").is_ok());
assert!(validate_policy_version("canary_retry.v2").is_ok());
assert!(validate_policy_version("").is_err());
assert!(validate_policy_version("a/b").is_err());
assert!(validate_policy_version(PolicyVersion::STATIC_V0).is_err());
}
#[tokio::test]
async fn layout_round_trips_all_three_entity_sets() {
let root = std::env::temp_dir().join(format!("rusty-policy-test-{}", uuid::Uuid::new_v4()));
let record = PolicyRecord {
version: PolicyVersion::new("policy-a"),
policy: ExecutorPolicy::static_v0(),
source: PolicySource::Candidate {
candidate_id: "cand-1".into(),
},
registered_at: ts(1_000),
};
persist_policy(&root, "policy-a", &record).await.unwrap();
persist_policy(&root, "acme/policy-b", &record)
.await
.unwrap();
let act = activation("policy-a", 1_000);
append_activation(&root, "default", &act).await.unwrap();
append_activation(&root, "acme", &act).await.unwrap();
let bind = binding("c-1", "policy-a", 1_200);
persist_binding(&root, "default", &bind).await.unwrap();
persist_binding(&root, "acme", &bind).await.unwrap();
std::fs::write(policies_dir(&root).join("broken.json"), b"{nope").unwrap();
let policies = load_policies(&root);
assert_eq!(policies.len(), 2, "corrupt files are skipped, not fatal");
assert!(
policies.contains_key("policy-a"),
"default tenant: bare key"
);
assert!(policies.contains_key("acme/policy-b"));
let activations = load_activations(&root);
assert_eq!(activations.len(), 2);
assert!(activations.contains_key(&activation_file_name(&act)));
assert!(activations.contains_key(&format!("acme/{}", activation_file_name(&act))));
let bindings = load_bindings(&root);
assert_eq!(bindings.len(), 2);
assert!(bindings.contains_key("c-1"));
assert!(bindings.contains_key("acme/c-1"));
let _ = std::fs::remove_dir_all(root);
}
}