Struct Surface 

pub struct Surface {
    pub schema: String,
    pub origin: Origin,
    pub capabilities: BTreeMap<String, PublicCapability>,
}

The public surface of one tree or one ref.

use majordomus_cli::release::surface::{public_capabilities, Origin, Surface, SURFACE_SCHEMA};
use serde_json::json;
let of = |caps| Surface {
    schema: SURFACE_SCHEMA.to_string(),
    origin: Origin::WorkingTree,
    capabilities: public_capabilities(&json!({"capabilities": caps})),
};
// The same surface enumerated in a different order is the same surface.
let one = of(json!([{"id": "b", "kind": "query"}, {"id": "a", "kind": "query"}]));
let other = of(json!([{"id": "a", "kind": "query"}, {"id": "b", "kind": "query"}]));
assert_eq!(one.fingerprint(), other.fingerprint());

Fields

schema: String

The normalisation these capabilities were reduced by.

origin: Origin

Where it was read from.

capabilities: BTreeMap<String, PublicCapability>

Every public capability, by id, in a deterministic order.

Implementations

impl Surface

pub fn of_registry(registry: &CapabilityRegistry) -> Surface

The surface of the current tree, from the live registry.

Never reads the committed projection: a stale docs/generated/registry.json would make this side of the comparison a description of an older tree, and every verdict drawn from it wrong in a way nothing else would catch.

use majordomus_cli::capability::registry::CapabilityRegistry;
use majordomus_cli::release::surface::{Origin, Surface};
let registry = CapabilityRegistry::builder().build().expect("an empty registry composes");
let surface = Surface::of_registry(&registry);
assert_eq!(surface.origin, Origin::WorkingTree);

pub fn read_ref(root: &Path, reference: &str) -> Result<Surface, SurfaceError>

The surface a ref published, from the registry projection committed at it.

use majordomus_cli::release::surface::{Surface, SurfaceError};
let dir = tempfile::tempdir().unwrap();
// Not a work tree, so there is no such ref — and it says so rather than
// comparing against an empty surface.
assert!(matches!(
    Surface::read_ref(dir.path(), "v0.5.0"),
    Err(SurfaceError::NoSuchRef { .. })
));

pub fn atoms(&self) -> usize

How many public atoms this surface carries: the things a caller can hold, counted.

One per capability identity, plus one per binding it answers to. This is what the reports mean by “87 public atoms”; it is a size, never an input to a verdict.

use majordomus_cli::release::surface::{public_capabilities, Origin, Surface, SURFACE_SCHEMA};
use serde_json::json;
let surface = Surface {
    schema: SURFACE_SCHEMA.to_string(),
    origin: Origin::WorkingTree,
    capabilities: public_capabilities(&json!({"capabilities": [{
        "id": "a.one", "kind": "query", "visibility": "public",
        "exposure": {"mcp": {"tool": "t"}, "http": {"method": "GET", "path": "/x"}}
    }]})),
};
assert_eq!(surface.atoms(), 3, "the identity, the tool, the route");

pub fn fingerprint(&self) -> String

A stable identity for this surface.

Deterministic, ordering-independent and schema-versioned: the same logical surface hashes the same however the registry enumerated it, because the capabilities are a sorted map and every schema was normalised before it got here. Two trees with the same fingerprint have the same public contract, which is what makes it usable as release evidence rather than decoration.

use majordomus_cli::capability::registry::CapabilityRegistry;
use majordomus_cli::release::surface::Surface;
let registry = CapabilityRegistry::builder().build().expect("an empty registry composes");
let surface = Surface::of_registry(&registry);
assert_eq!(surface.fingerprint(), surface.fingerprint(), "deterministic");
assert!(surface.fingerprint().starts_with("sha256:"));

Trait Implementations

impl Clone for Surface

fn clone(&self) -> Surface

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Surface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Surface

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Surface

impl JsonSchema for Surface

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl PartialEq for Surface

fn eq(&self, other: &Surface) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Surface

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Surface