majordomus_cli/capability/builtin/

entity.rs

//! The `entity` module: every object of the layer as an addressable, cross-linked node.
//!
//! `objects.get` answers what a file *is*. This module answers the three further questions
//! a governance object is actually read for, and answers them for every kind at once
//! because none of them is asked of a kind by name:
//!
//! - **Where does it live?** Its route, derived from its kind and identity by
//!   [`crate::entity::slug`], the same function the Cockpit resolves a request with.
//! - **What is it joined to?** Its outgoing references and — the half nothing declared —
//!   the references that resolve to it, both read from the one relation table the graph
//!   and the dangling-reference check already share.
//! - **Where is it published?** Its public documentation page, when the repository's site
//!   publishes its kind: [`crate::entity::Publication`] reads `site/data/publication.toml`
//!   and the site's `base_url`, the same declaration the site generator builds the pages
//!   from, so the address named here is the page the site holds.
//! - **What can be said about its enforcement?** Which of the executable artefacts it
//!   names are in the tree, stated as a state a page may not round up, and a pointer to the
//!   capability that can prove more where the registry holds one.
//!
//! Nothing here enumerates kinds, entities or routes. A file added under `.ai/` becomes an
//! object, an object has a route, and this capability answers for it — which is the whole
//! of `project.entities-are-routable`.
//!
//! One entity is asked for either way a caller already holds it — the URI the layer indexes
//! it by, or the address a reader was given — and the two name the same object:
//!
//! ```
//! use majordomus_cli::capability::builtin::entity::{EntityInput, EvidenceState};
//!
//! let by_uri: EntityInput =
//!     serde_json::from_value(serde_json::json!({ "uri": "majordomus://rule/project.x@1" }))
//!         .unwrap();
//! assert_eq!(by_uri.uri.as_deref(), Some("majordomus://rule/project.x@1"));
//!
//! let by_route: EntityInput =
//!     serde_json::from_value(serde_json::json!({ "kind": "rule", "slug": "project-x-1" }))
//!         .unwrap();
//! assert_eq!(by_route.kind.as_deref(), Some("rule"));
//!
//! // a key nobody declared is an error, not a silently ignored field
//! assert!(serde_json::from_value::<EntityInput>(serde_json::json!({ "url": "x" })).is_err());
//!
//! // and what the answer may say about enforcement is a state, never a run
//! let unclaimed = serde_json::to_value(EvidenceState::Unclaimed).unwrap();
//! assert_eq!(unclaimed, serde_json::json!("unclaimed"));
//! ```

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::capability::benchmark::{BenchmarkCases, CaseContext, NamedCase};
use crate::capability::handler::{CapabilityError, Context};
use crate::capability::model::{CliExposure, Exposure, Stability};
use crate::capability::module::ModuleDescriptor;
use crate::entity::{self, Collision, Documentation, Edge, Publication, Surface};
use crate::model::Object;
use crate::{capability, module};

use super::{get, mcp, ObjectSummary};

// ---------------------------------------------------------------- input

/// Which entity: by URI, or by the address it is served at.
///
/// Two spellings of one question, because two kinds of caller ask it: MCP and the API hold
/// the `majordomus://` URI the index is keyed by, and the Cockpit's router has a `kind` and
/// a `slug` out of a path. Nothing converts one form into the other at the edge — the
/// capability resolves either, so neither caller has to know the other's spelling.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::EntityInput;
///
/// let by_route: EntityInput =
///     serde_json::from_value(serde_json::json!({ "kind": "adr", "slug": "adr-0056" }))
///         .unwrap();
/// assert_eq!(by_route.kind.as_deref(), Some("adr"));
/// assert_eq!(by_route.slug.as_deref(), Some("adr-0056"));
/// assert_eq!(by_route.uri, None);
///
/// // absent is a shape, not an error: which fields are required is the handler's question
/// assert_eq!(EntityInput::default().kind, None);
/// ```
#[derive(Debug, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct EntityInput {
    /// `majordomus://<kind>/<identity>`. Either this, or `kind` and `slug` together.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uri: Option<String>,
    /// The kind, when addressing by route.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    /// The last segment of the entity's route, when addressing by route.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub slug: Option<String>,
}

impl BenchmarkCases for EntityInput {
    fn benchmark_cases(ctx: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        ctx.index
            .objects
            .first()
            .map(|o| {
                vec![NamedCase::new(
                    "first-object",
                    EntityInput {
                        uri: Some(o.uri.clone()),
                        ..Default::default()
                    },
                )]
            })
            .unwrap_or_default()
    }
}

// ---------------------------------------------------------------- evidence

/// What this repository can say about the executable artefacts an object names, and only
/// that. The word is chosen so that no reader can mistake it for a run.
///
/// The three states are ordered by how much they permit a reader to conclude, and the
/// strongest of them still concludes nothing about a run: `Resolved` means the files an
/// object points at exist. `proof` on [`Evidence`] is where "did it ever pass" is asked.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::EvidenceState;
///
/// // the wire spellings, which the Cockpit badge and the site template both read
/// for (state, word) in [
///     (EvidenceState::Unclaimed, "unclaimed"),
///     (EvidenceState::Dangling, "dangling"),
///     (EvidenceState::Resolved, "resolved"),
/// ] {
///     assert_eq!(serde_json::to_value(state).unwrap(), serde_json::json!(word));
/// }
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
#[schemars(rename = "EntityEvidenceState")]
pub enum EvidenceState {
    /// The object names no executable artefact. Most kinds name none, and that is not a
    /// defect: a prompt is not enforced by anything.
    Unclaimed,
    /// It names artefacts and at least one of them is not in the tree. A claim that points
    /// at nothing is worse than no claim, because it reads as enforcement.
    Dangling,
    /// Every artefact it names is in the tree. This says the claim resolves — never that it
    /// passed. Whether it ever ran is a different question, and `proof` is where it is
    /// asked.
    Resolved,
}

/// One executable artefact an object names, and whether the tree holds it.
///
/// `field` is kept beside the path because the same object can name artefacts under several
/// keys, and a reader fixing a dangling one needs to know which line of the front matter to
/// look at rather than which file is missing.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::ClaimedArtifact;
///
/// let a = ClaimedArtifact {
///     field: "x-majordomus.tests".into(),
///     path: "test/cases/277_entities_are_routable.sh".into(),
///     present: true,
/// };
/// let wire = serde_json::to_value(&a).unwrap();
/// assert_eq!(wire["field"], serde_json::json!("x-majordomus.tests"));
/// assert_eq!(wire["present"], serde_json::json!(true));
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ClaimedArtifact {
    /// The front matter key it was named under (`x-majordomus.tests`, `test`, ...).
    pub field: String,
    /// The repository-relative path as named.
    pub path: String,
    /// Whether the tree holds it.
    pub present: bool,
}

/// Where a fuller answer about this entity's enforcement lives.
///
/// A pointer, never an answer. This module states what it can see in the tree and then
/// names the capability that can say more, so that an entity page does not grow a second,
/// weaker implementation of proof beside the one that already exists.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::ProofRef;
///
/// let p = ProofRef {
///     capability: "rule.proves".into(),
///     title: "What proves a rule".into(),
///     address: "majordomus rule proves project.entities-are-routable@1".into(),
/// };
/// assert_eq!(
///     serde_json::to_value(&p).unwrap()["capability"],
///     serde_json::json!("rule.proves")
/// );
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[schemars(rename = "EntityProofRef")]
pub struct ProofRef {
    /// The capability that answers it.
    pub capability: String,
    /// Its title.
    pub title: String,
    /// How to ask it here.
    pub address: String,
}

/// What can be said about an object's enforcement without running anything.
///
/// `meaning` travels with `state` so that every surface shows the same sentence about it:
/// a badge alone invites each renderer to write its own gloss, and the gloss is where a
/// "resolved" quietly becomes a "passing". A kind that names no artefact is `Unclaimed`
/// with an empty `artifacts`, which is an answer and not an omission.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::{Evidence, EvidenceState};
///
/// let e = Evidence {
///     state: EvidenceState::Unclaimed,
///     meaning: "This object names no executable artefact.".into(),
///     artifacts: Vec::new(),
///     proof: None,
/// };
///
/// // the empty collections are omitted from the wire, so absence reads as absence
/// let wire = serde_json::to_value(&e).unwrap();
/// assert_eq!(wire["state"], serde_json::json!("unclaimed"));
/// assert!(wire.get("artifacts").is_none());
/// assert!(wire.get("proof").is_none());
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[schemars(rename = "EntityEvidence")]
pub struct Evidence {
    /// The state, which is never rounded up.
    pub state: EvidenceState,
    /// That state in one sentence, for a reader.
    pub meaning: String,
    /// Every artefact named, with whether the tree holds it.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub artifacts: Vec<ClaimedArtifact>,
    /// The capability that can say more, when this kind has one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub proof: Option<ProofRef>,
}

/// The front matter keys that name an executable artefact. Not a list of kinds: a key, on
/// whatever kind carries it. `x-majordomus` is the extension block the layer's schemas
/// reserve for exactly this, and the others are the keys the claim and rule schemas already
/// use for the same purpose.
const ARTIFACT_FIELDS: &[&str] = &["tests", "test", "implementation", "validator"];

/// Collect the paths an object names as executable artefacts, from its front matter and
/// from its `x-majordomus` extension block.
fn claimed(metadata: &Value) -> Vec<(String, String)> {
    let mut out = Vec::new();
    let mut take = |prefix: &str, source: &Value| {
        for field in ARTIFACT_FIELDS {
            let key = if prefix.is_empty() {
                (*field).to_string()
            } else {
                format!("{prefix}.{field}")
            };
            match source.get(field) {
                Some(Value::Array(a)) => out.extend(
                    a.iter()
                        .filter_map(Value::as_str)
                        .filter(|s| looks_like_a_path(s))
                        .map(|s| (key.clone(), s.to_string())),
                ),
                Some(Value::String(s)) if looks_like_a_path(s) => {
                    out.push((key.clone(), s.clone()))
                }
                _ => {}
            }
        }
    };
    take("", metadata);
    if let Some(x) = metadata.get("x-majordomus") {
        take("x-majordomus", x);
    }
    out
}

/// A value that names a file rather than a symbol. `-` is the layer's written absence, and
/// a validator is named by its function rather than its path; neither is a path to look for.
fn looks_like_a_path(s: &str) -> bool {
    s.contains('/') && s != "-"
}

fn evidence(ctx: &Context, o: &Object) -> Evidence {
    let root = &ctx.index.repository.root;
    let artifacts: Vec<ClaimedArtifact> = claimed(&o.metadata)
        .into_iter()
        .map(|(field, path)| ClaimedArtifact {
            present: std::path::Path::new(root).join(&path).exists(),
            field,
            path,
        })
        .collect();
    // one formula, no table: a kind whose module answers `<kind>s.show` can prove more
    let proof = ctx
        .registry
        .get(&format!("{}s.show", o.kind))
        .map(|c| ProofRef {
            capability: c.id.to_string(),
            title: c.title.clone(),
            address: match &c.exposure.http {
                Some(h) => format!("{} {}", h.method.as_str(), h.path),
                None => c.id.to_string(),
            },
        });
    let missing = artifacts.iter().filter(|a| !a.present).count();
    let (state, meaning) = if artifacts.is_empty() {
        (
            EvidenceState::Unclaimed,
            "This object names no executable artefact, so nothing here claims it is enforced."
                .to_string(),
        )
    } else if missing > 0 {
        (
            EvidenceState::Dangling,
            format!(
                "{missing} of the {} artefact(s) this object names are not in the tree: it reads as enforced and is not.",
                artifacts.len()
            ),
        )
    } else {
        (
            EvidenceState::Resolved,
            format!(
                "Every one of the {} artefact(s) this object names is in the tree. That they resolve is not that they ran.",
                artifacts.len()
            ),
        )
    };
    Evidence {
        state,
        meaning,
        artifacts,
        proof,
    }
}

// ---------------------------------------------------------------- the view

/// One object of the layer as an addressable node: what it is, where it is served, what it
/// is joined to, and what can be said about its enforcement.
///
/// The whole answer in one value, because it is one question: every surface that shows an
/// entity — the Cockpit page, `GET /api/v1/entity`, `majordomus_entity`, `majordomus entity
/// show` — renders this and composes nothing of its own. A field a reader sees on one
/// surface and not another would be a surface holding an opinion, which is what ADR 0004
/// forecloses.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::EntityView;
///
/// // it round-trips through the wire shape every projection reads it as
/// let view: EntityView = serde_json::from_value(serde_json::json!({
///     "uri": "majordomus://adr/adr-0056",
///     "id": "adr.adr-0056",
///     "kind": "adr",
///     "identity": "adr-0056",
///     "slug": "adr-0056",
///     "route": "/cockpit/objects/adr/adr-0056",
///     "kind_route": "/cockpit/objects/adr",
///     "title": "Every object of the layer has a derived address",
///     "provenance": { "path": "x.md", "directory": "x", "source_class": "adr", "bytes": 0 },
///     "metadata": {},
///     "media_type": "text/markdown",
///     "content": "",
///     "relations": [],
///     "surfaces": [],
///     "evidence": { "state": "unclaimed", "meaning": "nothing named" },
///     "documentation": {
///         "projection": "entity",
///         "route": "/adrs/adr-0056/",
///         "url": "https://majordomus.dev/adrs/adr-0056/",
///         "declared_in": "site/data/publication.toml",
///     },
/// }))
/// .unwrap();
///
/// assert_eq!(view.route, "/cockpit/objects/adr/adr-0056");
/// // the Cockpit route is the object's; the public page is the site's, and both are named
/// let public = view.documentation.as_ref().and_then(|d| d.url.as_deref());
/// assert_eq!(public, Some("https://majordomus.dev/adrs/adr-0056/"));
/// // the kind's index is the entity's route with the last segment removed
/// assert!(view.route.starts_with(&view.kind_route));
/// ```
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct EntityView {
    /// `majordomus://<kind>/<identity>`.
    pub uri: String,
    /// The capability id, `<kind>.<identity>`.
    pub id: String,
    /// The kind.
    pub kind: String,
    /// The identity within the kind.
    pub identity: String,
    /// The last segment of its route, derived from the identity.
    pub slug: String,
    /// Its route in the Cockpit.
    pub route: String,
    /// The route of its kind's index.
    pub kind_route: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    /// The title, when the kind's title rule found one.
    pub title: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    /// The one-line description, when the kind holds one.
    pub description: Option<String>,
    /// Where it came from.
    pub provenance: crate::model::Provenance,
    /// The parsed front matter or YAML, keys in the file's order.
    pub metadata: Value,
    /// IANA media type of `content`.
    pub media_type: String,
    /// The file as read.
    pub content: String,
    /// The references it declares, and the references that resolve to it.
    pub relations: Vec<Edge>,
    /// Every surface that answers for it.
    pub surfaces: Vec<Surface>,
    /// What can be said about its enforcement without running anything.
    pub evidence: Evidence,
    /// Its public documentation page, derived from the repository's publication declaration
    /// (`site/data/publication.toml`) and the site's `base_url` by the same function the site
    /// generator writes the page with. Null when the repository declares no publication or
    /// does not declare this kind; a kind declared as not published carries the reason.
    #[serde(default)]
    pub documentation: Option<Documentation>,
}

fn subject<'a>(ctx: &'a Context, input: &EntityInput) -> Result<&'a Object, CapabilityError> {
    match (&input.uri, &input.kind, &input.slug) {
        (Some(uri), None, None) => ctx.index.get(uri).ok_or_else(|| {
            CapabilityError::NotFound(format!("no object of this layer has the URI {uri}"))
        }),
        (None, Some(kind), Some(slug)) => {
            entity::find(&ctx.index.objects, kind, slug).ok_or_else(|| {
                CapabilityError::NotFound(format!(
                    "no object of kind '{kind}' is served at {}",
                    entity::route(kind, slug)
                ))
            })
        }
        _ => Err(CapabilityError::InvalidInput(
            "name the entity either by 'uri' or by 'kind' and 'slug' together".into(),
        )),
    }
}

fn objects_entity(ctx: &Context, input: EntityInput) -> Result<EntityView, CapabilityError> {
    let o = subject(ctx, &input)?;
    Ok(EntityView {
        uri: o.uri.clone(),
        id: format!("{}.{}", o.kind, o.identity),
        kind: o.kind.clone(),
        identity: o.identity.clone(),
        slug: entity::slug(&o.identity),
        route: entity::object_route(o),
        kind_route: entity::kind_route(&o.kind),
        title: o.title.clone(),
        description: o.description.clone(),
        provenance: o.provenance.clone(),
        metadata: o.metadata.clone(),
        media_type: o.media_type.to_string(),
        content: o.content.clone(),
        relations: entity::edges(&ctx.registry, &ctx.index.objects, o),
        surfaces: entity::surfaces(&ctx.registry, o),
        evidence: evidence(ctx, o),
        // read at request time: the declaration is the repository's, and a repository
        // without a site has none
        documentation: Publication::read(std::path::Path::new(&ctx.index.repository.root))
            .and_then(|p| p.documentation(&o.kind, &entity::slug(&o.identity))),
    })
}

// ---------------------------------------------------------------- kinds

/// One kind of the layer, with its address and how many objects it holds.
///
/// `example` carries one of the kind's objects so that a catalogue of kinds is somewhere a
/// reader can go from rather than a list of words: a kind with a count and no way in is a
/// dead row. It is `None` only for a kind the index holds no object of.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::KindEntry;
///
/// let e: KindEntry = serde_json::from_value(serde_json::json!({
///     "kind": "adr",
///     "count": 52,
///     "route": "/cockpit/objects/adr",
/// }))
/// .unwrap();
///
/// assert_eq!(e.kind, "adr");
/// // the route is the kind's, derived — never a per-kind entry in a table of routes
/// assert_eq!(e.route, majordomus_cli::entity::kind_route(&e.kind));
/// assert!(e.example.is_none());
/// ```
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct KindEntry {
    /// The kind.
    pub kind: String,
    /// How many objects of it the index holds.
    pub count: usize,
    /// Where its index is served.
    pub route: String,
    /// One of its objects, so a reader has somewhere to go.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub example: Option<ObjectSummary>,
}

/// Every kind of the layer, each with its route, and every route collision there is.
///
/// The two numbers are what `scripts/ci/entity-check` compares: the objects the index holds
/// against the objects that have an address. They are reported together, in one answer, so
/// that the gate asks one question instead of joining two lists and deciding for itself
/// what the difference means.
///
/// ```
/// use majordomus_cli::capability::builtin::entity::KindList;
///
/// let healthy: KindList = serde_json::from_value(serde_json::json!({
///     "count": 1,
///     "kinds": [{ "kind": "adr", "count": 52, "route": "/cockpit/objects/adr" }],
///     "routable": 52,
/// }))
/// .unwrap();
///
/// let held: usize = healthy.kinds.iter().map(|k| k.count).sum();
/// // every object addressable, and no collision: the only state the gate accepts
/// assert_eq!(held, healthy.routable);
/// assert!(healthy.collisions.is_empty());
/// ```
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct KindList {
    /// How many kinds.
    pub count: usize,
    /// The kinds, in the index's order.
    pub kinds: Vec<KindEntry>,
    /// How many objects have a route. Every object does, unless it is in `collisions`.
    pub routable: usize,
    /// Two objects of one kind whose identities reduce to one route, which is the only way
    /// an object can fail to be addressable. Empty is the healthy answer and the only one
    /// `scripts/ci/entity-check` accepts.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub collisions: Vec<Collision>,
}

fn objects_kinds(ctx: &Context, _: super::Empty) -> Result<KindList, CapabilityError> {
    let kinds: Vec<KindEntry> = ctx
        .index
        .kinds()
        .into_iter()
        .map(|(kind, count)| KindEntry {
            route: entity::kind_route(kind),
            example: ctx
                .index
                .objects
                .iter()
                .find(|o| o.kind == kind)
                .map(ObjectSummary::of),
            kind: kind.to_string(),
            count,
        })
        .collect();
    let collisions = entity::collisions(&ctx.index.objects);
    let colliding: usize = collisions.iter().map(|c| c.identities.len()).sum();
    Ok(KindList {
        count: kinds.len(),
        kinds,
        routable: ctx.index.objects.len().saturating_sub(colliding),
        collisions,
    })
}

/// The canonical declaration of the `entity` module: the two capabilities that answer for
/// an object and for the catalogue of kinds, with every projection each is exposed through.
///
/// This is the only place either capability is written down. The MCP tool, the HTTP route,
/// the command-line path, the generated OpenAPI and the Cockpit's page are all read from
/// here, which is why adding a surface to `entity.show` is an edit to this function and
/// never to a transport registry or a documentation table (ADR 0004).
///
/// ```
/// use majordomus_cli::capability::builtin::entity;
///
/// let m = entity::module();
/// assert_eq!(m.id.as_str(), "entity");
///
/// // both capabilities are namespaced by the module id, with no second spelling of it
/// let ids: Vec<String> = m
///     .capabilities
///     .iter()
///     .map(|c| c.capability.id.to_string())
///     .collect();
/// assert!(ids.iter().any(|id| id == "entity.show"));
/// assert!(ids.iter().any(|id| id == "entity.kinds"));
///
/// // and each declares where it is answered, rather than being registered elsewhere
/// let show = m
///     .capabilities
///     .iter()
///     .find(|c| c.capability.id.to_string() == "entity.show")
///     .expect("entity.show is declared here");
/// assert_eq!(
///     show.capability.exposure.http.as_ref().map(|h| h.path.as_str()),
///     Some("/api/v1/entity")
/// );
/// ```
pub fn module() -> ModuleDescriptor {
    module! {
        id: "entity",
        title: "Entities",
        description: "Every object of the layer as an addressable, cross-linked node: its route, its outgoing references, the references that resolve to it, the surfaces that answer for it, and what can be said about its enforcement without running anything. Nothing here enumerates kinds, entities or routes — an object of the index has a route because it is an object.",
        stability: Stability::Implemented,
        capabilities: [
            capability! {
                id: "entity.show",
                title: "Read one entity",
                description: "One object of the layer as an addressable node, by URI or by the address it is served at: identity and route, provenance, front matter and content, every reference it declares and every reference that resolves to it, the surfaces that answer for it, the state of the executable artefacts it names, and its public documentation page as the repository's site/data/publication.toml derives it (null when the repository declares none).",
                input: EntityInput,
                output: EntityView,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: mcp("majordomus_entity"),
                    http: get("/api/v1/entity"),
                    cli: Some(CliExposure { path: vec!["entity".into(), "show".into()] }),
                },
                tags: ["objects", "governance"],
                handler: objects_entity,
            },
            capability! {
                id: "entity.kinds",
                title: "Every kind, and whether every object of it is addressable",
                description: "The kinds the layer holds, each with the route of its index and how many objects it carries, and every route collision there is. A collision is the only way an object of the index can fail to have an address of its own; the healthy answer is none.",
                input: super::Empty,
                output: KindList,
                stability: Stability::Implemented,
                exposure: Exposure {
                    mcp: mcp("majordomus_kinds"),
                    http: get("/api/v1/entity/kinds"),
                    cli: Some(CliExposure { path: vec!["entity".into(), "kinds".into()] }),
                },
                tags: ["objects", "governance"],
                handler: objects_kinds,
            },
        ],
    }
}

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

    #[test]
    fn only_a_path_counts_as_a_named_artefact() {
        assert!(looks_like_a_path("scripts/ci/x"));
        assert!(!looks_like_a_path("-"));
        assert!(
            !looks_like_a_path("scope_is_declared"),
            "a validator named by its function is not a file to look for"
        );
    }

    #[test]
    fn artefacts_are_collected_from_the_front_matter_and_the_extension_block() {
        let m = json!({
            "test": "test/cases/1_a.sh",
            "implementation": "-",
            "x-majordomus": { "tests": ["scripts/ci/a", "scripts/ci/b"] },
        });
        assert_eq!(
            claimed(&m),
            vec![
                ("test".to_string(), "test/cases/1_a.sh".to_string()),
                ("x-majordomus.tests".to_string(), "scripts/ci/a".to_string()),
                ("x-majordomus.tests".to_string(), "scripts/ci/b".to_string()),
            ],
            "the written absence is not an artefact, and the extension block is read too"
        );
    }

    #[test]
    fn an_object_that_names_nothing_is_unclaimed_rather_than_enforced() {
        assert!(claimed(&json!({"title": "x"})).is_empty());
        assert!(claimed(&Value::Null).is_empty());
    }
}