Module surface 

The public surface: everything a caller can hold, read from the one declaration that states it.

Why this exists as a type

A version is a claim about compatibility, and a claim nobody can check is worth nothing. Elm’s package manager answers this by refusing to let the author choose: it reads the public API of both versions and computes the smallest honest bump. This module is the first half of that — the reading — and super::compat is the second.

The surface is not discovered by crawling a running server, parsing rendered Markdown or calling MCP. Every interface of this repository is a projection of the capability registry (ADR 0002, ADR 0027), so the registry is the public surface and the projections are what it looks like from outside. Comparing projections would compare renderings; comparing the registry compares the contract.

Two origins, one shape

  the current tree    generate::registry_manifest(&registry)   in process, never stale
  a released ref      git show <ref>:docs/generated/registry.json

The current tree is read from the live registry rather than from the committed file, because a committed projection can be stale and a surface comparison against a stale current side is a false verdict in the dangerous direction: it would report a removal that did not happen, or miss an addition that did. A historical ref has no such option — the executable of that commit is not available — so the committed projection is used, and Surface::read_ref refuses loudly rather than guessing when a ref does not carry one. That asymmetry is deliberate and is the reason the generated registry is committed at every commit at all.

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": {"http": {"method": "GET", "path": "/api/v1/a"}}},
        {"id": "a.hidden", "kind": "query", "visibility": "internal"},
    ]})),
};
// An internal capability is not a promise to anyone, so it is not surface.
assert_eq!(surface.capabilities.len(), 1);
assert_eq!(surface.atoms(), 2, "the identity and the route");
assert!(surface.fingerprint().starts_with("sha256:"));

Structs

HttpBinding

One HTTP binding a caller can hold.

PublicCapability

One public capability, reduced to what a caller outside this repository can depend on.

Surface

The public surface of one tree or one ref.

Enums

Origin

Where a surface was read from.

SurfaceError

Why a surface could not be read.

Constants

REGISTRY

The committed projection of the registry, which is how a released ref’s surface is read.

SURFACE_SCHEMA

The schema this module’s normalisation is defined against. It is carried into the plan so that a verdict recorded today can be reproduced when the rules below change.

Functions

normalise

Reduce a JSON Schema to the part of it a caller can break against.

public_capabilities

Reduce a registry manifest to the public capabilities it declares.