a3s-use-core 0.2.9

Shared typed contracts for A3S Use domains
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

use std::collections::{BTreeMap, BTreeSet};

use crate::UseResult;

use super::catalog::{catalog_error, CatalogSurface, PluginCatalogRecord, MAX_CATALOG_SURFACES};
use super::validation::strictly_sorted_unique;
use super::{PluginSurfaceKind, PluginSurfaceRef};

impl PluginCatalogRecord {
    /// Resolve mandatory surfaces plus the exact transitive dependency closure
    /// of an explicit optional-surface selection.
    pub fn resolve_surfaces(
        &self,
        requested: &[PluginSurfaceRef],
    ) -> UseResult<Vec<CatalogSurface>> {
        self.validate()?;
        if requested.len() > MAX_CATALOG_SURFACES {
            return Err(catalog_error(
                "The requested plugin surface selection is too large.",
            ));
        }
        let available = self
            .surfaces
            .iter()
            .map(|surface| (surface.reference(), surface))
            .collect::<BTreeMap<_, _>>();
        let requested_count = requested.len();
        let requested = requested.iter().cloned().collect::<BTreeSet<_>>();
        if requested.len() != requested_count
            || requested
                .iter()
                .any(|surface| !available.contains_key(surface))
        {
            return Err(catalog_error(
                "The requested plugin surface selection is invalid.",
            ));
        }
        let mut selected = self
            .surfaces
            .iter()
            .filter(|surface| !surface.optional)
            .map(CatalogSurface::reference)
            .chain(requested)
            .collect::<BTreeSet<_>>();
        loop {
            let before = selected.len();
            let dependencies = selected
                .iter()
                .filter_map(|surface| available.get(surface))
                .flat_map(|surface| surface.requires.iter().cloned())
                .collect::<Vec<_>>();
            selected.extend(dependencies);
            if selected.len() == before {
                break;
            }
        }
        Ok(self
            .surfaces
            .iter()
            .filter(|surface| selected.contains(&surface.reference()))
            .cloned()
            .collect())
    }
}

pub(super) fn validate_surface_dependencies(
    surfaces: &[CatalogSurface],
    surface_refs: &BTreeSet<PluginSurfaceRef>,
) -> UseResult<()> {
    for surface in surfaces {
        if surface.requires.len() > MAX_CATALOG_SURFACES
            || !strictly_sorted_unique(&surface.requires)
            || surface.requires.iter().any(|required| {
                required == &surface.reference()
                    || !surface_refs.contains(required)
                    || !valid_surface_dependency(surface.kind, required.kind)
            })
        {
            return Err(catalog_error(
                "A catalog surface dependency set is invalid.",
            ));
        }
    }
    let mut resolved = BTreeSet::new();
    loop {
        let before = resolved.len();
        for surface in surfaces {
            let reference = surface.reference();
            if surface
                .requires
                .iter()
                .all(|required| resolved.contains(required))
            {
                resolved.insert(reference);
            }
        }
        if resolved.len() == surfaces.len() {
            return Ok(());
        }
        if resolved.len() == before {
            return Err(catalog_error(
                "Catalog surface dependencies must be acyclic.",
            ));
        }
    }
}

fn valid_surface_dependency(owner: PluginSurfaceKind, required: PluginSurfaceKind) -> bool {
    match owner {
        PluginSurfaceKind::Flow => matches!(
            required,
            PluginSurfaceKind::Tool | PluginSurfaceKind::Mcp | PluginSurfaceKind::Okf
        ),
        PluginSurfaceKind::Skill => {
            matches!(
                required,
                PluginSurfaceKind::Flow
                    | PluginSurfaceKind::Tool
                    | PluginSurfaceKind::Mcp
                    | PluginSurfaceKind::Okf
            )
        }
        PluginSurfaceKind::Ui => matches!(
            required,
            PluginSurfaceKind::Flow
                | PluginSurfaceKind::Skill
                | PluginSurfaceKind::Tool
                | PluginSurfaceKind::Mcp
        ),
        PluginSurfaceKind::Tool | PluginSurfaceKind::Mcp | PluginSurfaceKind::Okf => false,
    }
}