safe_chains/engine/

archetype.rs

//! Static capability archetypes (`docs/design/behavioral-taxonomy-archetypes.md`). The recurring
//! facet profiles the Phase-1 subcommand surface classifies against. Each archetype is a fixed
//! [`Capability`] declared in `archetypes.toml`; a subcommand references one by name (`profile =
//! "remote-mutate"`) and the resolver emits that capability directly (a static profile — the
//! sub's facets don't depend on its arguments, unlike the operand-role commands of Phase 0).
//!
//! This is the archetype as a *reusable audited bundle*, never a unit of analysis: `profile = …`
//! expands to the explicit capability here, the researcher still verifies the sub genuinely is
//! that archetype and cites it (the per-item provenance schema). Facet fields take an EXACT term,
//! not a bound — these are points in facet-space, not the level predicates of `authoring`.

use std::collections::BTreeMap;
use std::sync::LazyLock;

use serde::Deserialize;

use super::facet::{Capability, FacetTerm, Operation};

/// The capability an archetype expands to, or `None` if the name is unknown (fail-closed: an
/// unknown `profile = …` must not silently resolve to nothing).
pub fn archetype(name: &str) -> Option<&'static Capability> {
    ARCHETYPES.get(name)
}

/// Every archetype name, for the `profile = …` closed-set check and the docs.
pub fn names() -> impl Iterator<Item = &'static str> {
    ARCHETYPES.keys().map(String::as_str)
}

static ARCHETYPES: LazyLock<BTreeMap<String, Capability>> = LazyLock::new(|| {
    build_archetypes(include_str!("../../archetypes.toml")).expect("embedded archetypes.toml must compile")
});

/// How an archetype is told apart from a confusable neighbour.
#[derive(Debug, Clone, Deserialize)]
struct TomlDistinction {
    #[allow(dead_code)] // authoring metadata, read by the near-neighbour guards
    archetype: String,
    /// The dotted facet name that differs, as `Capability::set_facets` spells it.
    #[allow(dead_code)] // authoring metadata, read by the near-neighbour guards
    by: String,
}

/// One archetype's authored disambiguation: its name, the `(other, axis)` pairs it declares itself
/// distinguished from, and the archetype it declares itself facet-identical to.
#[cfg(test)]
type DeclaredDistinction = (String, Vec<(String, String)>, Option<String>);

/// The authored disambiguation for every archetype — checked against the facets themselves by
/// `near_neighbours_are_declared`.
#[cfg(test)]
fn declared_distinctions() -> Vec<DeclaredDistinction> {
    let set: TomlArchetypeSet =
        toml::from_str(include_str!("../../archetypes.toml")).expect("archetypes.toml parses");
    set.archetype
        .into_iter()
        .map(|(name, tc)| {
            let d = tc
                .distinguished_from
                .into_iter()
                .map(|x| (x.archetype, x.by))
                .collect();
            (name, d, tc.same_point_as)
        })
        .collect()
}

fn build_archetypes(src: &str) -> Result<BTreeMap<String, Capability>, String> {
    let set: TomlArchetypeSet = toml::from_str(src).map_err(|e| e.to_string())?;
    set.archetype
        .into_iter()
        .map(|(name, tc)| build_capability(&name, tc).map(|c| (name, c)))
        .collect()
}

fn build_capability(name: &str, tc: TomlCapability) -> Result<Capability, String> {
    let operation = Operation::from_term(&tc.operation)
        .ok_or_else(|| format!("archetype `{name}`: unknown operation `{}`", tc.operation))?;
    let mut c = Capability::new(operation);

    if let Some(l) = &tc.locus {
        set_term(name, "locus.local", l.local.as_deref(), &mut c.locus.local)?;
        set_term(name, "locus.remote", l.remote.as_deref(), &mut c.locus.remote)?;
        set_term(name, "locus.binding", l.binding.as_deref(), &mut c.locus.binding)?;
        set_term(name, "locus.provenance", l.provenance.as_deref(), &mut c.locus.provenance)?;
    }
    set_term(name, "scale", tc.scale.as_deref(), &mut c.scale)?;
    set_term(name, "retrieval", tc.retrieval.as_deref(), &mut c.retrieval)?;
    set_term(name, "authority", tc.authority.as_deref(), &mut c.authority)?;
    set_term(name, "reversibility", tc.reversibility.as_deref(), &mut c.reversibility)?;
    if let Some(p) = &tc.persistence {
        set_term(name, "persistence.level", p.level.as_deref(), &mut c.persistence.level)?;
    }
    if let Some(d) = &tc.disclosure {
        set_term(name, "disclosure.audience", d.audience.as_deref(), &mut c.disclosure.audience)?;
    }
    if let Some(s) = &tc.secret {
        set_term(name, "secret.level", s.level.as_deref(), &mut c.secret.level)?;
    }
    if let Some(net) = &tc.network {
        set_term(name, "network.direction", net.direction.as_deref(), &mut c.network.direction)?;
        set_term(name, "network.destination", net.destination.as_deref(), &mut c.network.destination)?;
        set_term(name, "network.payload", net.payload.as_deref(), &mut c.network.payload)?;
    }
    set_term(name, "execution", tc.execution.as_deref(), &mut c.execution.trust)?;
    set_term(name, "cost", tc.cost.as_deref(), &mut c.cost)?;

    if tc.because.trim().is_empty() {
        return Err(format!("archetype `{name}`: `because` is required"));
    }
    c.because = tc.because;
    Ok(c)
}

/// Parse an optional term into `slot`, leaving the zero-term default when absent. An unrecognized
/// term is a compile error naming the archetype and facet (fail-closed, never a silent skip).
fn set_term<T: FacetTerm>(name: &str, field: &str, s: Option<&str>, slot: &mut T) -> Result<(), String> {
    if let Some(v) = s {
        *slot = T::from_term(v).ok_or_else(|| format!("archetype `{name}`: unknown {field} term `{v}`"))?;
    }
    Ok(())
}

#[derive(Deserialize)]
struct TomlArchetypeSet {
    #[serde(default)]
    archetype: BTreeMap<String, TomlCapability>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlCapability {
    operation: String,
    because: String,
    /// Archetypes this one is easily confused with, and the axis that separates them. Required
    /// (both ways) for any pair differing on a single facet — see `near_neighbours_are_declared`.
    #[serde(default)]
    #[allow(dead_code)] // authoring metadata, read by the near-neighbour guards
    distinguished_from: Vec<TomlDistinction>,
    /// An archetype occupying the SAME point in facet space, declared deliberately. The two
    /// classify identically and differ only in the prose `--explain` shows.
    #[serde(default)]
    #[allow(dead_code)] // authoring metadata, read by the near-neighbour guards
    same_point_as: Option<String>,
    #[serde(default)]
    locus: Option<TomlLocus>,
    #[serde(default)]
    scale: Option<String>,
    #[serde(default)]
    retrieval: Option<String>,
    #[serde(default)]
    authority: Option<String>,
    #[serde(default)]
    reversibility: Option<String>,
    #[serde(default)]
    persistence: Option<TomlPersistence>,
    #[serde(default)]
    disclosure: Option<TomlDisclosure>,
    #[serde(default)]
    secret: Option<TomlSecret>,
    #[serde(default)]
    network: Option<TomlNetwork>,
    #[serde(default)]
    execution: Option<String>,
    #[serde(default)]
    cost: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlLocus {
    local: Option<String>,
    remote: Option<String>,
    binding: Option<String>,
    provenance: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlPersistence {
    level: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlDisclosure {
    audience: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlSecret {
    level: Option<String>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct TomlNetwork {
    direction: Option<String>,
    destination: Option<String>,
    payload: Option<String>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::authoring::default_levels;
    use crate::engine::bridge::project;
    use crate::engine::facet::Profile;
    use crate::engine::level::Level;
    use crate::verdict::Verdict;

    fn level(name: &str) -> &'static Level {
        default_levels().iter().find(|l| l.name == name).expect("level exists")
    }

    /// The `adjacent` (sibling-workspace) locus lands where the design says, INDEPENDENT of the legacy
    /// 3-band CLI projection (which collapses editor/developer to SafeWrite). A sibling READ auto-
    /// approves from reader up; a sibling create/mutate (a "quick patch") is admitted at developer but
    /// NOT editor (editor's writes stay `<= worktree`); a sibling DESTROY is withheld even at developer
    /// (conservative — `rm -rf ../otherrepo` is not a patch).
    #[test]
    fn sibling_adjacent_locus_reads_at_reader_writes_at_developer_not_editor() {
        use crate::engine::facet::{Capability, LocalLocus, Operation, PersistenceLevel, Reversibility};
        let at_adjacent = |op: Operation| {
            let mut c = Capability::new(op);
            c.locus.local = LocalLocus::Adjacent;
            c
        };
        let read = Profile::of(vec![at_adjacent(Operation::Observe)]);
        let patch = Profile::of(vec![{
            let mut c = at_adjacent(Operation::Mutate);
            c.reversibility = Reversibility::Recoverable;
            c.persistence.level = PersistenceLevel::Data;
            c
        }]);
        let destroy = Profile::of(vec![at_adjacent(Operation::Destroy)]);

        assert!(level("reader").admits(&read), "a sibling READ auto-approves from reader");
        assert!(level("developer").admits(&read), "…and higher");
        assert!(!level("editor").admits(&patch), "editor does NOT write a sibling (writes stay worktree)");
        assert!(level("developer").admits(&patch), "developer patches a sibling (create/mutate)");
        assert!(!level("editor").admits(&destroy), "editor does NOT destroy a sibling");
        assert!(!level("developer").admits(&destroy), "developer does NOT destroy a sibling (conservative — its destroy clause stays `<= worktree`)");
    }

    #[test]
    fn archetypes_toml_compiles_and_every_capability_is_justified() {
        // LazyLock forces the parse; a bad term / missing `because` would have panicked.
        let mut count = 0;
        for n in names() {
            let c = archetype(n).expect("listed archetype resolves");
            assert!(!c.because.is_empty(), "archetype `{n}` has no because");
            count += 1;
        }
        assert!(count >= 10, "expected the full catalog, got {count}");
        assert!(archetype("does-not-exist").is_none(), "unknown profile fails closed");
    }

    /// The catalog's "Lands at" column, verified against the real algebra by loading the ACTUAL
    /// archetype definitions (not hand-built copies): each is admitted by its claimed level and
    /// refused by the level just below it. Ties archetypes.toml ↔ the catalog doc ↔ the levels.
    #[test]
    fn archetypes_land_where_the_catalog_says() {
        // (archetype, admitted_by, refused_by)
        let cases: &[(&str, &str, &str)] = &[
            // A pure remote fetch is a READ — reader admits it; only paranoid (no network) refuses.
            ("remote-read", "reader", "paranoid"),
            // A BULK remote export (db dump to stdout) is still a read — reader admits it. `scale`
            // records the volume but does not gate a read; the -f output file is a SEPARATE cap.
            ("data-export", "reader", "paranoid"),
            ("remote-mutate", "network-admin", "developer"),
            ("remote-create", "network-admin", "developer"),
            ("remote-destroy-recoverable", "network-admin", "developer"),
            ("remote-destroy-irreversible", "yolo", "network-admin"),
            ("remote-authorize", "network-admin", "developer"),
            ("remote-control", "network-admin", "developer"),
            ("vcs-sync", "network-admin", "developer"),
            ("blockchain-txn", "yolo", "network-admin"),
            ("local-privileged", "local-admin", "developer"),
            // Transient service control (systemctl restart) — the mildest root-machine op, still local-admin.
            ("privileged-control", "local-admin", "developer"),
            // A pinned, scripts-off install runs no foreign code → developer (via the install clause).
            ("local-install-pinned", "developer", "editor"),
            // The scripts-on / unpinned install RUNS foreign code (network-sourced) → yolo only.
            ("supply-chain-build", "yolo", "developer"),
            // Arbitrary remote code execution (kubectl exec, ssh cmd) — execute op, no level below yolo.
            ("remote-exec", "yolo", "network-admin"),
            // Credential material read/mint → yolo (secret > uses-ambient everywhere below yolo).
            ("credential-read", "yolo", "network-admin"),
            ("credential-mint", "yolo", "network-admin"),
            // Decrypt-to-screen (sops -d, age -d, ansible-vault view): a secret read that flows to the
            // model — same `secret = reads` tier as a credential-store read → yolo, refused below.
            ("decrypt-read", "yolo", "network-admin"),
            // Arbitrary stored-object retrieval (s3 get-object): classified by `retrieval =
            // bulk-content` (§5 #1), it lands at NETWORK-ADMIN — the proportionate bulk-egress tier —
            // refused by developer. NOT yolo (it is not a credential read) and NOT reader (opaque bulk
            // content is above the everyday read band).
            ("bulk-object-read", "network-admin", "developer"),
            // The LOCAL working-copy quartet — the mirror of the remote one, split on the same
            // reversibility axis. Both mutates land at editor (differing only in how easily they
            // undo, which the levels do not yet distinguish); the destroys split editor→developer
            // →yolo exactly as reversibility worsens.
            ("local-mutate-trivial", "editor", "reader"),
            ("local-mutate-recoverable", "editor", "reader"),
            ("local-destroy-recoverable", "developer", "editor"),
            ("local-destroy-irreversible", "yolo", "developer"),
        ];
        for (name, admitted_by, refused_by) in cases {
            let p = Profile::of(vec![archetype(name).expect("archetype exists").clone()]);
            assert!(level(admitted_by).admits(&p), "{name} should be admitted by {admitted_by}");
            assert!(!level(refused_by).admits(&p), "{name} should be refused by {refused_by}");
        }

        // COMPLETENESS. Without this, adding an archetype to archetypes.toml and forgetting the
        // catalog row leaves it with NO level verification at all — it would ship classifying
        // commands with nobody having checked where it lands. Enumerating the real catalog means a
        // new archetype fails here until its landing is asserted above.
        let uncovered: Vec<&str> =
            names().filter(|n| !cases.iter().any(|(c, _, _)| c == n)).collect();
        assert!(
            uncovered.is_empty(),
            "archetype(s) with no catalog row — add (name, admitted_by, refused_by) above: {uncovered:?}",
        );
    }

    /// The whole point of Phase 1 for the WRITE side: every remote archetype that CHANGES remote
    /// state (mutate/create/destroy/authorize/control), plus vcs-sync and blockchain-txn, is above
    /// the auto-approve band — denied by CLASSIFICATION, not hand-marking. `remote-read` is the
    /// deliberate exception: a pure fetch is a reader-level read and auto-approves (SafeRead).
    #[test]
    fn every_remote_write_archetype_is_not_auto_approved() {
        let write_remotes = names()
            .filter(|n| (n.starts_with("remote-") && *n != "remote-read") || *n == "vcs-sync" || *n == "blockchain-txn");
        for name in write_remotes {
            let p = Profile::of(vec![archetype(name).expect("archetype").clone()]);
            assert_eq!(project(&p), Verdict::Denied, "{name} must not auto-approve in the 3-value projection");
        }
        // and the read DOES auto-approve — the read/write asymmetry, verified
        assert_eq!(
            project(&Profile::of(vec![archetype("remote-read").unwrap().clone()])),
            Verdict::Allowed(crate::verdict::SafetyLevel::SafeRead),
            "a pure remote fetch is reader-level",
        );
    }

    /// The exposure reframe (behavioral-taxonomy-exposure.md §3, §7): `disclosure.audience = public`
    /// is a RECORD, not a gate. Publishing content you authored to a public destination (git push to
    /// a public repo, `npm publish`) is a network-admin operation — NOT held back to yolo by its
    /// publicness. What still gates to yolo is CONTENT: transmitting a secret off-box. Proves the
    /// gate moved from "how public the destination is" to "is a secret leaving". Red on the old
    /// `disclosure = { audience = "<= trusted-remote" }` ceiling (public publish refused everywhere
    /// below yolo); green on `<= public`.
    #[test]
    fn public_disclosure_is_recorded_not_gated_secret_transmission_is() {
        use crate::engine::facet::{
            DisclosureAudience, NetDestination, NetDirection, NetPayload, Network, RemoteReach,
            Reversibility, SecretLevel,
        };

        let publish_to_public = || {
            let mut c = Capability::new(Operation::Communicate);
            c.locus.remote = RemoteReach::Arbitrary;
            c.reversibility = Reversibility::Effortful;
            c.disclosure.audience = DisclosureAudience::Public;
            c.network = Network {
                direction: NetDirection::Outbound,
                destination: NetDestination::Arbitrary,
                payload: NetPayload::SendsHostData,
            };
            c
        };

        // Non-secret public publish → a network-admin op, still above the local developer band.
        let mut publish = publish_to_public();
        publish.because = "publish authored content to a public destination".into();
        let publish = Profile::of(vec![publish]);
        assert!(level("network-admin").admits(&publish), "public non-secret publish is network-admin");
        assert!(!level("developer").admits(&publish), "outbound remote egress is above developer");

        // Same shape, but it TRANSMITS A SECRET — now the CONTENT gates it up to yolo.
        let mut exfil = publish_to_public();
        exfil.secret.level = SecretLevel::Transmits;
        exfil.because = "transmit a secret off-box".into();
        let exfil = Profile::of(vec![exfil]);
        assert!(!level("network-admin").admits(&exfil), "secret transmission is the gate, above network-admin");
        assert!(level("yolo").admits(&exfil), "yolo admits secret exfil (non-destroy clause)");
    }

    /// The machine locus SUB-RUNG split (the `restart nginx` vs `/etc/passwd` distinction). ORDINARY
    /// machine state — a service, an app config — is `machine` → local-admin. The identity/auth/boot/
    /// loader TRUST substrate is `system-integrity` → ABOVE local-admin, yolo-only. Same operation +
    /// authority; only the locus rung differs, and that difference is the whole gate: "run the machine
    /// as admin" vs "own the machine's trust root".
    #[test]
    fn system_integrity_is_above_local_admin_ordinary_machine_is_not() {
        use crate::engine::facet::{Authority, LocalLocus};
        let (local, yolo) = (level("local-admin"), level("yolo"));

        let root_write_at = |loc| {
            let mut c = Capability::new(Operation::Mutate);
            c.locus.local = loc;
            c.authority = Authority::Root;
            c.because = "root machine write".into();
            Profile::of(vec![c])
        };

        // ordinary machine config (edit /etc/nginx.conf as root) — local-admin admits.
        assert!(local.admits(&root_write_at(LocalLocus::Machine)), "ordinary machine write is local-admin");

        // the trust substrate (rewrite /etc/passwd as root) — local-admin REFUSES; only yolo.
        let integrity = root_write_at(LocalLocus::SystemIntegrity);
        assert!(!local.admits(&integrity), "the system-integrity substrate is above local-admin");
        assert!(yolo.admits(&integrity), "yolo owns the machine's trust root");
    }

    /// The developer supply-chain / install clause. A PINNED, SCRIPTS-OFF install (`npm ci
    /// --ignore-scripts`) fetches packages and writes node_modules but runs NO foreign code —
    /// `execution = self`, `persistence = installing` → a dev-loop staple, admitted at developer.
    /// The scripts-ON or UNPINNED install is `execution = network-sourced` (the supply-chain-build
    /// archetype) → no home below yolo. The resolver picks which shape a command emits; this pins the
    /// LEVEL boundary. Modeling the safe install as `execution = self` (not a guardrail-gated
    /// `network-sourced`) is what keeps the clause all-`<=` and facet-monotone.
    #[test]
    fn pinned_scripts_off_install_is_developer_the_supply_chain_surface_is_yolo() {
        use crate::engine::facet::{
            ExecutionTrust, LocalLocus, NetDirection, NetPayload, PersistenceLevel, Reversibility,
        };
        let (dev, yolo) = (level("developer"), level("yolo"));

        // `npm ci --ignore-scripts`: install files, execute nothing foreign.
        let safe_install = {
            let mut c = Capability::new(Operation::Create);
            c.locus.local = LocalLocus::Worktree;
            c.persistence.level = PersistenceLevel::Installing;
            c.reversibility = Reversibility::Effortful;
            c.network.direction = NetDirection::Outbound;
            c.network.payload = NetPayload::Fetches;
            c.execution.trust = ExecutionTrust::SelfCode;
            c.because = "pinned, scripts-off install".into();
            Profile::of(vec![c])
        };
        assert!(dev.admits(&safe_install), "a pinned, scripts-off install is developer");
        assert!(yolo.admits(&safe_install), "and of course yolo");

        // scripts-ON / unpinned: the supply-chain surface (network-sourced execution).
        let supply_chain = Profile::of(vec![archetype("supply-chain-build").unwrap().clone()]);
        assert!(!dev.admits(&supply_chain), "network-sourced install (scripts on / unpinned) is above developer");
        assert!(yolo.admits(&supply_chain), "the supply-chain surface lands at yolo");
    }

    /// Destination-trust (behavioral-taxonomy-exposure.md §4): the new `locus.provenance` facet.
    /// A send to a target designated `literal` (a URL typed inline) is a network-admin op — the
    /// human reviewing at that level SEES the URL; a send to an `opaque` target (from a variable,
    /// unreviewable) is held to yolo. Proves network-admin's `provenance <= literal` ceiling. Red
    /// if the ceiling is absent (opaque would leak into network-admin) or set to `established`
    /// (literal URLs would be wrongly refused); green at `<= literal`.
    #[test]
    fn a_literal_send_target_is_network_admin_an_opaque_one_is_yolo() {
        use crate::engine::facet::{NetDirection, NetPayload, Provenance, RemoteReach};

        let send_to = |prov| {
            let mut c = Capability::new(Operation::Communicate);
            c.locus.remote = RemoteReach::Fixed;
            c.locus.provenance = prov;
            c.network.direction = NetDirection::Outbound;
            c.network.payload = NetPayload::SendsHostData;
            c.because = "send host data to a designated target".into();
            c
        };

        let literal = Profile::of(vec![send_to(Provenance::Literal)]);
        assert!(level("network-admin").admits(&literal), "a visible literal URL is a network-admin send");
        assert!(!level("developer").admits(&literal), "sends-host-data is above the local developer band");

        let opaque = Profile::of(vec![send_to(Provenance::Opaque)]);
        assert!(!level("network-admin").admits(&opaque), "an opaque (variable) destination is held above network-admin");
        assert!(level("yolo").admits(&opaque), "yolo leaves provenance unconstrained");
    }
}

#[cfg(test)]
mod neighbour_tests {
    use super::*;
    use std::collections::BTreeMap;

    /// The facets on which two archetypes differ. `set_facets` omits terms sitting at their zero,
    /// so a facet present in one map and absent from the other IS a difference (present vs default).
    fn differing_facets(a: &Capability, b: &Capability) -> Vec<&'static str> {
        let am: BTreeMap<_, _> = a.set_facets().into_iter().collect();
        let bm: BTreeMap<_, _> = b.set_facets().into_iter().collect();
        let mut keys: Vec<_> = am.keys().chain(bm.keys()).copied().collect();
        keys.sort_unstable();
        keys.dedup();
        keys.into_iter().filter(|k| am.get(k) != bm.get(k)).collect()
    }

    /// Any two archetypes within ONE facet of each other must say so, both ways, naming the axis
    /// that separates them.
    ///
    /// Choosing an archetype fixes 27 facets at once and is the most consequential authoring act in
    /// the repo — yet it is done by picking a name from a flat list of 23, with the differences
    /// buried in prose. That is not a theoretical hazard: `dynamodb scan` was classified
    /// `bulk-object-read` when it is a `data-export`, because the two differ ONLY on `retrieval`
    /// and the sentence saying so lived inside the OTHER archetype's `because`, invisible to
    /// someone reading this one.
    ///
    /// Detection is mechanical rather than authored, so a confusable pair introduced later is
    /// caught the moment it appears — nobody has to notice it first.
    #[test]
    fn near_neighbours_are_declared() {
        let declared = declared_distinctions();
        let dist_of = |n: &str| -> Vec<(String, String)> {
            declared.iter().find(|(name, ..)| name == n).map(|(_, d, _)| d.clone()).unwrap_or_default()
        };
        let same_of = |n: &str| -> Option<String> {
            declared.iter().find(|(name, ..)| name == n).and_then(|(_, _, s)| s.clone())
        };

        let names: Vec<&str> = names().collect();
        let mut problems = Vec::new();
        for (i, a) in names.iter().enumerate() {
            for b in &names[i + 1..] {
                let d = differing_facets(archetype(a).unwrap(), archetype(b).unwrap());
                match d.len() {
                    // Same point in facet space: they classify identically, so the choice is pure
                    // prose. Legitimate, but it has to be deliberate — otherwise an author picks by
                    // coin-flip and a later facet edit to one silently diverges them. A pair that
                    // DOES declare it falls through to `_`, which is the no-op.
                    0 if same_of(a).as_deref() != Some(*b) || same_of(b).as_deref() != Some(*a) => {
                        problems.push(format!(
                            "`{a}` and `{b}` are facet-IDENTICAL; both must declare \
                             `same_point_as` naming the other, or be given a real difference",
                        ));
                    }
                    1 => {
                        let axis = d[0];
                        for (x, y) in [(a, b), (b, a)] {
                            if !dist_of(x).iter().any(|(n, by)| n == *y && by == axis) {
                                problems.push(format!(
                                    "`{x}` must declare `distinguished_from = [{{ archetype = \"{y}\", \
                                     by = \"{axis}\" }}]` — they differ on that axis alone",
                                ));
                            }
                        }
                    }
                    _ => {}
                }
            }
        }
        assert!(problems.is_empty(), "confusable archetypes:\n  {}", problems.join("\n  "));
    }

    /// A declared distinction must be TRUE: the named axis is really where the two differ. A stale
    /// annotation is worse than none — it points an author at the wrong facet with authority.
    #[test]
    fn declared_distinctions_are_accurate() {
        let mut problems = Vec::new();
        for (name, dists, same) in declared_distinctions() {
            let Some(a) = archetype(&name) else { continue };
            for (other, by) in dists {
                let Some(b) = archetype(&other) else {
                    problems.push(format!("`{name}` names unknown archetype `{other}`"));
                    continue;
                };
                let d = differing_facets(a, b);
                if !d.contains(&by.as_str()) {
                    problems.push(format!(
                        "`{name}` claims it differs from `{other}` by `{by}`, but they differ on {d:?}",
                    ));
                }
            }
            if let Some(other) = same {
                match archetype(&other) {
                    None => problems.push(format!("`{name}` names unknown archetype `{other}`")),
                    Some(b) => {
                        let d = differing_facets(a, b);
                        if !d.is_empty() {
                            problems.push(format!(
                                "`{name}` claims `same_point_as = \"{other}\"`, but they differ on {d:?}",
                            ));
                        }
                    }
                }
            }
        }
        assert!(problems.is_empty(), "inaccurate distinctions:\n  {}", problems.join("\n  "));
    }
}