apoc 0.9.1

Agentic process control for LLMs
Documentation
//! Stable invocation-pattern signatures for history mining.

use serde_json::Value;
use sha2::{Digest, Sha256};

/// One normalized pattern signature and the input paths that vary between calls.
pub(crate) struct PatternSignature {
    pub(crate) signature: String,
    pub(crate) variable_paths: Vec<String>,
}

pub(crate) fn invocation_pattern_signature(command_path: &str, input: &Value) -> PatternSignature {
    let mut variable_paths = Vec::new();
    let normalized = normalize(input, "$", None, &mut variable_paths);
    variable_paths.sort();
    variable_paths.dedup();
    let encoded = serde_json::json!({
        "command_path": command_path,
        "input": normalized,
    })
    .to_string()
    .into_bytes();
    let signature = format!("sha256:{:x}", Sha256::digest(encoded));
    PatternSignature {
        signature,
        variable_paths,
    }
}

fn normalize(
    value: &Value,
    path: &str,
    key: Option<&str>,
    variable_paths: &mut Vec<String>,
) -> Value {
    match value {
        Value::Object(values) => Value::Object(
            values
                .iter()
                .map(|(key, value)| {
                    let path = format!("{path}.{key}");
                    (
                        key.clone(),
                        normalize(value, &path, Some(key), variable_paths),
                    )
                })
                .collect(),
        ),
        Value::Array(values) => {
            variable_paths.push(format!("{path}[]"));
            let mut kinds = values.iter().map(value_kind).collect::<Vec<_>>();
            kinds.sort_unstable();
            kinds.dedup();
            serde_json::json!({ "$array": kinds })
        }
        Value::Bool(value) => Value::Bool(*value),
        Value::Null => Value::Null,
        Value::String(value) if key.is_some_and(stable_discriminator) => {
            Value::String(value.clone())
        }
        Value::Number(value) if key.is_some_and(stable_discriminator) => {
            Value::Number(value.clone())
        }
        value => {
            variable_paths.push(path.to_string());
            Value::String(format!("<{}>", value_kind(value)))
        }
    }
}

fn stable_discriminator(key: &str) -> bool {
    matches!(
        key,
        "executable" | "provider" | "method" | "operation" | "kind" | "signal"
    )
}

fn value_kind(value: &Value) -> &'static str {
    match value {
        Value::Null => "null",
        Value::Bool(_) => "boolean",
        Value::Number(_) => "number",
        Value::String(_) => "string",
        Value::Array(_) => "array",
        Value::Object(_) => "object",
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn groups_calls_that_only_change_volatile_values() {
        let first = invocation_pattern_signature(
            "execution command",
            &serde_json::json!({
                "args": { "executable": "cargo" },
                "options": {
                    "arg": ["test", "--test", "history_contract"],
                    "idempotency_key": "first-attempt",
                    "timeout_ms": 10_000
                }
            }),
        );
        let second = invocation_pattern_signature(
            "execution command",
            &serde_json::json!({
                "args": { "executable": "cargo" },
                "options": {
                    "arg": ["check", "--all-targets", "--locked"],
                    "idempotency_key": "retry-attempt",
                    "timeout_ms": 30_000
                }
            }),
        );

        assert_eq!(first.signature, second.signature);
        assert!(
            first
                .variable_paths
                .contains(&"$.options.arg[]".to_string())
        );
        assert!(
            first
                .variable_paths
                .contains(&"$.options.idempotency_key".to_string())
        );
    }

    #[test]
    fn keeps_command_path_and_stable_discriminators_distinct() {
        let cargo = invocation_pattern_signature(
            "execution command",
            &serde_json::json!({ "args": { "executable": "cargo" }, "options": {} }),
        );
        let git = invocation_pattern_signature(
            "execution command",
            &serde_json::json!({ "args": { "executable": "git" }, "options": {} }),
        );
        let process = invocation_pattern_signature(
            "process get",
            &serde_json::json!({ "args": { "executable": "cargo" }, "options": {} }),
        );

        assert_ne!(cargo.signature, git.signature);
        assert_ne!(cargo.signature, process.signature);
    }

    #[test]
    fn normalizes_every_value_kind_and_numeric_discriminator() {
        let pattern = invocation_pattern_signature(
            "provider invoke",
            &serde_json::json!({
                "enabled": true,
                "kind": 7,
                "values": [null, true, 1, "text", [], {}]
            }),
        );

        assert_eq!(pattern.variable_paths, vec!["$.values[]"]);
        assert!(pattern.signature.starts_with("sha256:"));
    }
}