majordomus_cli/

generate.rs

//! Generated projections that are committed for review: the OpenAPI document, the
//! capability reference, the benchmark matrix, the registry manifest, and the shell
//! tool's key allow-lists derived from the JSON Schemas. All come through this one
//! pipeline; the committed files are caches of it, never sources, and `--check` says when
//! they are stale.
//!
//! Every artifact is *typed*: it declares the document it projects, the encoding it is
//! written in, the JSON Schema its content satisfies when it has one, and the source it
//! was derived from. A structured document is written in every encoding this repository
//! commits it in — JSON for a program, YAML for a person editing configuration beside it,
//! Markdown for a reader — from one value, so the encodings cannot disagree. Every
//! artifact carries a provenance header in the form its encoding allows, and
//! [`manifest_document`] is the index of the whole set, itself generated.

use std::path::{Path, PathBuf};

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

use crate::app::App;
use crate::bench::{BenchmarkProjection, Coverage, CoverageState, SystemTarget, Transport};
use crate::capability::registry::ModuleSource;
use crate::capability::{CapabilityKind, CapabilityRegistry, CaseContext, Context, Provenance};
use crate::error::{Error, Result};
use crate::http::openapi;
use crate::metadata::{yaml, KindSchema};
use crate::policy::{sha256_hex, LoadedPolicy};
use crate::share::Share;

/// Where generated artifacts live, relative to the repository root.
pub const OUT_DIR: &str = "docs/generated";
/// Where the registry dataset the site renders lives, relative to the repository root. The
/// shell site generator owns `site/data/generated/` wholesale; this directory is the Rust
/// executable's, so that no directory has two writers.
pub const SITE_DATA_DIR: &str = "site/data/registry";

/// The first thing every generated artifact says about itself, whatever its encoding
/// wraps it in.
pub const HEADER: &str = "GENERATED FILE — DO NOT EDIT DIRECTLY";

/// The command that rewrites any of them.
pub const REGENERATE: &str = "majordomus generate";

/// The schema of `registry.json`.
pub const REGISTRY_SCHEMA: &str = "majordomus/capability-registry/v1";

/// The schema of `benchmarks.json`.
pub const BENCHMARKS_SCHEMA: &str = "majordomus/benchmark-matrix/v1";

/// The schema of `artifacts.json`, the manifest of every generated artifact.
pub const MANIFEST_SCHEMA: &str = "majordomus/generated-artifacts/v1";

/// The schema extension that names the allow-list a schema derives.
pub const ALLOW_EXTENSION: &str = "x-majordomus-allow";

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// What can be generated.
pub enum Target {
    /// `docs/generated/openapi.{json,yaml}`.
    OpenApi,
    /// `docs/generated/capabilities.md` (the index), `docs/generated/modules/<id>.md`,
    /// `docs/generated/cli.md` and `docs/generated/cli.{json,yaml}` (the command line as
    /// clap declares it, with the examples declared beside it), and
    /// `docs/generated/providers.{md,json,yaml}`: every provider the distribution declares,
    /// with what this repository does with it — the one table the documents point at
    /// instead of enumerating providers by hand (ADR 0024).
    Docs,
    /// `docs/generated/benchmarks.{md,json,yaml}`: every benchmark target and the
    /// coverage, from the projection.
    Benchmarks,
    /// `docs/generated/registry.{json,yaml}`: the builtin registry as data,
    /// `majordomus/capability-registry/v1`.
    Registry,
    /// `<share>/allow/<name>.txt` for every schema that carries `x-majordomus-allow`.
    Allow,
    /// The projections of every `.proto` document schema: the JSON Schema beside it and
    /// `<share>/sections/<name>.txt`, the body half of its contract (see
    /// [`crate::proto::project`]).
    Documents,
    /// The provider bootstraps the policy's `projections[]` declare, rendered from the
    /// provider templates: `AGENTS.md`, `CLAUDE.md`, ... (see [`crate::providers`]). The
    /// provider *table* is a document of [`Target::Docs`]: a repository that projects no
    /// bootstrap still has providers, and a fixture that checks its bootstraps alone is not
    /// asked for a document it never wrote.
    Providers,
    /// The files Zed and Google Antigravity read from a project: one
    /// `.agents/skills/<id>/SKILL.md` per active skill and `.zed/tasks.json` from the tracked
    /// justfile
    /// (see the `editors` module, ADR 0140).
    Editors,
    /// `site/data/registry/registry.json`: the registry dataset GitHub Pages renders
    /// (see [`crate::site`]).
    Site,
    /// `docs/generated/web.json`: the resolved web topology, `majordomus/web-topology/v1`.
    ///
    /// The site generator has no Rust toolchain and reads committed files; this is how the
    /// topology reaches the published documentation without the site shelling out to this
    /// executable, and how `generate --check` notices when it has gone stale.
    Web,
    /// `docs/generated/changelog.{json,yaml,md}`: the changelog of every published release,
    /// composed from the layer's release records, the decisions dated inside each release's
    /// window and the conventional commits in its range (see [`crate::release`]). Not the
    /// unreleased section: that is `<last release>..HEAD`, which no committed file can
    /// carry without going stale at the next commit, and which the served surfaces add at
    /// request time.
    ///
    /// A generated document like any other, which is the point: `generate --check` is what
    /// notices that the changelog has stopped describing the releases, so nobody has to
    /// remember to update it.
    Changelog,
    /// Everything derived from the distribution model (see `crate::distribution`): the
    /// release build matrix, the installer, the installation guide, the site's dataset,
    /// and the public metadata of every recorded release — and `share/version.txt`, the
    /// projection of the version the shell tool ships with and reads at start-up.
    Distribution,
    /// `docs/generated/artifacts.{json,yaml,md}`: every artifact of every other target,
    /// with its encoding, schema, source and hash. Always planned over the whole set, so
    /// that a manifest naming half the artifacts cannot exist.
    Manifest,
    /// The artifacts of every deployment object: `deploy/Dockerfile` and `.dockerignore`
    /// (see [`crate::deploy::render`]).
    Deployment,
    /// `docs/generated/graph.json`: the composed graph as data, and
    /// `docs/generated/graph.schema.json`: its schema, generated from the types.
    Graph,
    /// Every projection of the design system (see `design::render`): the
    /// stylesheets both Tailwind builds import, the tokens and the declaration compiled
    /// into the crate, the mark the Cockpit's shell inlines, the copies of the brand every
    /// surface serves, the site's dataset, and `docs/generated/design.{json,yaml,md}`.
    Design,
    /// `docs/generated/economics.{json,yaml,md}`: the token-economics summary and the
    /// human-readable benchmark report, computed from the committed run records by
    /// [`crate::economics::summarize_tracked`] — the numbers the site publishes, never
    /// typed, and never a record someone ran locally without committing it.
    Economics,
}

impl Target {
    /// Every target, in generation order. [`Target::Manifest`] is last because it indexes
    /// the others.
    pub const ALL: &'static [Target] = &[
        Target::OpenApi,
        Target::Docs,
        Target::Benchmarks,
        Target::Registry,
        Target::Allow,
        Target::Documents,
        Target::Providers,
        Target::Editors,
        Target::Site,
        Target::Web,
        Target::Design,
        Target::Changelog,
        Target::Distribution,
        Target::Graph,
        Target::Deployment,
        Target::Economics,
        Target::Manifest,
    ];

    /// Every target but the manifest, in generation order: the artifacts the manifest
    /// indexes.
    ///
    /// Derived from [`Target::ALL`] rather than written beside it. It was a second list by
    /// hand, and three times a target was added to `ALL` and forgotten here, which made
    /// that target's artifacts the only ones the index said nothing about.
    pub fn indexed() -> Vec<Target> {
        Target::ALL
            .iter()
            .copied()
            .filter(|t| *t != Target::Manifest)
            .collect()
    }

    /// The name the command line and the manifest use.
    pub fn name(self) -> &'static str {
        match self {
            Target::OpenApi => "openapi",
            Target::Docs => "docs",
            Target::Benchmarks => "benchmarks",
            Target::Registry => "registry",
            Target::Allow => "allow",
            Target::Documents => "documents",
            Target::Providers => "providers",
            Target::Editors => "editors",
            Target::Site => "site",
            Target::Web => "web",
            Target::Changelog => "changelog",
            Target::Distribution => "distribution",
            Target::Manifest => "manifest",
            Target::Deployment => "deployment",
            Target::Graph => "graph",
            Target::Design => "design",
            Target::Economics => "economics",
        }
    }
}

/// The encoding one generated artifact is written in.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum ArtifactFormat {
    /// A JSON document: pretty-printed, one trailing newline, provenance as members.
    Json,
    /// The same document in the layer's YAML, provenance as a comment banner.
    Yaml,
    /// Markdown for a reader, provenance as an HTML comment.
    Markdown,
    /// Line-oriented text another program reads: the shell tool's allow-lists,
    /// provenance as `#` comments.
    Text,
}

/// The schema of `web.json`.
pub const WEB_SCHEMA: &str = "majordomus/web-topology/v1";

/// The schema of `economics.json`: the token-economics summary.
pub const ECONOMICS_SCHEMA: &str = "majordomus/economics-summary/v1";

/// The schema id of `docs/generated/providers.{json,yaml}`: every provider the distribution
/// ships, as `share/providers.yaml` and the repository's policy describe it.
pub const PROVIDERS_SCHEMA: &str = "majordomus/providers/v1";

impl ArtifactFormat {
    /// The file suffix, without the dot.
    pub fn suffix(self) -> &'static str {
        match self {
            ArtifactFormat::Json => "json",
            ArtifactFormat::Yaml => "yaml",
            ArtifactFormat::Markdown => "md",
            ArtifactFormat::Text => "txt",
        }
    }

    /// The format a path's suffix declares, `Text` for anything unrecognised.
    pub fn of_path(path: &str) -> ArtifactFormat {
        match path.rsplit_once('.').map(|(_, s)| s) {
            Some("json") => ArtifactFormat::Json,
            Some("yaml") | Some("yml") => ArtifactFormat::Yaml,
            Some("md") => ArtifactFormat::Markdown,
            _ => ArtifactFormat::Text,
        }
    }
}

/// The three lines every provenance header says, whatever the encoding wraps them in.
pub fn banner_lines(source: &str, version: &str) -> [String; 3] {
    [
        HEADER.to_string(),
        format!("Source: {source}; regenerate with `{REGENERATE}`"),
        format!("Generator: majordomus-cli {version}"),
    ]
}

/// The provenance header of a Markdown artifact: an HTML comment, so it is invisible when
/// rendered and unmissable in the file.
pub fn markdown_banner(source: &str, version: &str) -> String {
    let [a, b, c] = banner_lines(source, version);
    format!("<!-- {a}\n     {b}\n     {c} -->\n")
}

/// The provenance header of a YAML or text artifact: `#` comments, which every reader of
/// both — the layer's YAML parser, `grep -E -f`, awk — skips.
pub fn comment_banner(source: &str, version: &str) -> String {
    banner_lines(source, version)
        .iter()
        .map(|l| format!("# {l}\n"))
        .collect()
}

/// The comment form a line-oriented text artifact opens its banner with, by suffix. A
/// stylesheet or a script cannot start with `#`; an SVG is XML.
///
/// ```
/// use majordomus_cli::generate::text_comment_opening;
/// assert_eq!(text_comment_opening("share/design/theme.css"), "/*");
/// assert_eq!(text_comment_opening("share/cockpit/favicon.svg"), "<!--");
/// assert_eq!(text_comment_opening("share/allow/policy.txt"), "#");
/// ```
pub fn text_comment_opening(path: &str) -> &'static str {
    match Path::new(path).extension().and_then(|e| e.to_str()) {
        Some("css") | Some("js") | Some("mjs") => "/*",
        Some("svg") | Some("html") | Some("xml") => "<!--",
        _ => "#",
    }
}

/// The one line a JSON artifact carries under `generated`.
pub fn json_banner(source: &str) -> String {
    format!("{HEADER}; source: {source}; regenerate with `{REGENERATE}`")
}

/// Where a structured document puts its provenance.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HeaderStyle {
    /// `schema`, `generated` and `generator` as members: this repository's own documents.
    Members,
    /// `x-majordomus-generated` and `x-majordomus-generator`: a document whose own
    /// specification fixes the member names, so provenance goes in an extension. The
    /// OpenAPI document is the only one.
    Extension,
}

#[derive(Debug, Clone, PartialEq, Eq)]
/// One generated file: what it projects, how it is encoded, what contract its content
/// satisfies, where it came from, and the whole file.
pub struct Artifact {
    /// Repository-relative path.
    pub path: String,
    /// The document it projects: `registry`, `cli`, `openapi`, `capabilities`, ... Two
    /// artifacts sharing an id are the same document in two encodings.
    pub document: String,
    /// The encoding.
    pub format: ArtifactFormat,
    /// The JSON Schema its content satisfies, by schema id, when it declares one.
    pub schema: Option<String>,
    /// One line: what it was derived from, as the header says it.
    pub source: String,
    /// The whole file.
    pub content: String,
}

impl Artifact {
    /// A Markdown artifact: the banner, then the body. Nothing writes the banner itself.
    pub fn markdown(
        path: impl Into<String>,
        document: impl Into<String>,
        source: impl Into<String>,
        version: &str,
        body: &str,
    ) -> Artifact {
        let source = source.into();
        Artifact {
            path: path.into(),
            document: document.into(),
            format: ArtifactFormat::Markdown,
            schema: None,
            content: markdown_banner(&source, version) + body,
            source,
        }
    }

    /// A text artifact another program reads line by line: the banner as `#` comments,
    /// then the lines.
    pub fn text(
        path: impl Into<String>,
        document: impl Into<String>,
        source: impl Into<String>,
        version: &str,
        body: &str,
    ) -> Artifact {
        let source = source.into();
        Artifact {
            path: path.into(),
            document: document.into(),
            format: ArtifactFormat::Text,
            schema: None,
            content: comment_banner(&source, version) + body,
            source,
        }
    }

    /// A JSON artifact whose own specification fixes its member names — a JSON Schema,
    /// the OpenAPI document — so its provenance goes in `x-majordomus-` extensions rather
    /// than in members the specification does not define. Both forms are read back by
    /// [`violations`]; neither is more generated than the other.
    pub fn json_extension(
        path: impl Into<String>,
        document: impl Into<String>,
        source: impl Into<String>,
        version: &str,
        value: Value,
    ) -> Artifact {
        let source = source.into();
        let stamped = match value {
            Value::Object(members) => {
                let mut out = members;
                out.insert(
                    "x-majordomus-generated".into(),
                    Value::String(json_banner(&source)),
                );
                out.insert(
                    "x-majordomus-generator".into(),
                    Value::String(format!("majordomus-cli {version}")),
                );
                Value::Object(out)
            }
            other => other,
        };
        Artifact {
            path: path.into(),
            document: document.into(),
            format: ArtifactFormat::Json,
            schema: None,
            source,
            content: openapi::render(&stamped),
        }
    }

    /// A line-oriented text artifact whose banner takes the comment form its suffix
    /// allows: `/* */` for a stylesheet or a script, `<!-- -->` for an SVG, `#` otherwise.
    /// A stylesheet cannot open with `#` and an image cannot open with a shell comment;
    /// [`violations`] asks for the same form by the same suffix.
    ///
    /// ```
    /// use majordomus_cli::generate::Artifact;
    ///
    /// let css = Artifact::comment_text("a/b.css", "doc", "the source", "0.1.0", "body { }\n");
    /// assert!(css.content.starts_with("/* GENERATED FILE"), "{}", css.content);
    /// assert!(css.content.ends_with("body { }\n"));
    ///
    /// // the same body under a different suffix opens the way that suffix allows
    /// let svg = Artifact::comment_text("a/b.svg", "doc", "the source", "0.1.0", "<svg/>\n");
    /// assert!(svg.content.starts_with("<!-- GENERATED FILE"), "{}", svg.content);
    /// ```
    pub fn comment_text(
        path: impl Into<String>,
        document: impl Into<String>,
        source: impl Into<String>,
        version: &str,
        body: &str,
    ) -> Artifact {
        let path = path.into();
        let source = source.into();
        let [a, b, c] = banner_lines(&source, version);
        let banner = match text_comment_opening(&path) {
            "/*" => format!("/* {a}\n   {b}\n   {c} */\n"),
            "<!--" => format!("<!-- {a}\n     {b}\n     {c} -->\n"),
            _ => comment_banner(&source, version),
        };
        Artifact {
            path,
            document: document.into(),
            format: ArtifactFormat::Text,
            schema: None,
            content: banner + body,
            source,
        }
    }

    /// An artifact whose content is taken as it stands: a projection another module
    /// renders whole and stamps itself (the provider bootstraps, the site dataset).
    pub fn verbatim(
        path: impl Into<String>,
        document: impl Into<String>,
        format: ArtifactFormat,
        schema: Option<String>,
        source: impl Into<String>,
        content: String,
    ) -> Artifact {
        Artifact {
            path: path.into(),
            document: document.into(),
            format,
            schema,
            source: source.into(),
            content,
        }
    }
}

/// One generated *document*: a value with an identity, a schema and a provenance line,
/// projected into every encoding this repository commits it in. The encodings cannot
/// disagree because there is one value; adding an encoding is a line in
/// [`Document::artifacts`], never a second renderer.
#[derive(Debug, Clone)]
pub struct Document {
    /// The document id, which is also the file stem: `registry`, `cli`, `openapi`.
    pub id: String,
    /// The directory the encodings are written into, repository-relative.
    pub dir: String,
    /// The JSON Schema the value satisfies, when it declares one.
    pub schema: Option<String>,
    /// One line: what it was derived from.
    pub source: String,
    /// Where the provenance goes.
    pub style: HeaderStyle,
    /// The value, before provenance is added.
    pub value: Value,
}

impl Document {
    /// A document of this repository's own, provenance as members.
    pub fn new(
        id: impl Into<String>,
        schema: impl Into<String>,
        source: impl Into<String>,
        value: Value,
    ) -> Document {
        Document {
            id: id.into(),
            dir: OUT_DIR.to_string(),
            schema: Some(schema.into()),
            source: source.into(),
            style: HeaderStyle::Members,
            value,
        }
    }

    /// The value with its provenance in it: what both encodings serialise.
    pub fn stamped(&self, version: &str) -> Value {
        let Value::Object(members) = &self.value else {
            return self.value.clone();
        };
        let mut out = Map::new();
        match self.style {
            HeaderStyle::Members => {
                if let Some(schema) = &self.schema {
                    out.insert("schema".into(), Value::String(schema.clone()));
                }
                out.insert("generated".into(), Value::String(json_banner(&self.source)));
                out.insert(
                    "generator".into(),
                    Value::String(format!("majordomus-cli {version}")),
                );
                for (k, v) in members {
                    out.entry(k.clone()).or_insert_with(|| v.clone());
                }
            }
            HeaderStyle::Extension => {
                for (k, v) in members {
                    out.insert(k.clone(), v.clone());
                }
                out.insert(
                    "x-majordomus-generated".into(),
                    Value::String(json_banner(&self.source)),
                );
                out.insert(
                    "x-majordomus-generator".into(),
                    Value::String(format!("majordomus-cli {version}")),
                );
            }
        }
        Value::Object(out)
    }

    /// The document in every encoding it is committed in: JSON, then YAML.
    pub fn artifacts(&self, version: &str) -> Vec<Artifact> {
        let stamped = self.stamped(version);
        let base = |format: ArtifactFormat, content: String| Artifact {
            path: format!("{}/{}.{}", self.dir, self.id, format.suffix()),
            document: self.id.clone(),
            format,
            schema: self.schema.clone(),
            source: self.source.clone(),
            content,
        };
        vec![
            base(ArtifactFormat::Json, openapi::render(&stamped)),
            base(
                ArtifactFormat::Yaml,
                yaml::render_with_banner(&stamped, &banner_lines(&self.source, version).join("\n")),
            ),
        ]
    }
}
/// The registry's artifacts of the selected targets: the OpenAPI document, the
/// reference index with one file per builtin module, and the registry manifest.
/// `Target::Benchmarks` needs the repository's index for its cases and is answered by
/// [`context_artifacts`]; `Target::Allow` and `Target::Providers` are not the registry's
/// and are answered by [`allow_artifacts`] and [`crate::providers::artifacts`].
pub fn artifacts(
    registry: &CapabilityRegistry,
    version: &str,
    cases: Option<&CaseContext<'_>>,
    targets: &[Target],
) -> Result<Vec<Artifact>> {
    let mut out = Vec::new();
    for t in targets {
        match t {
            Target::OpenApi => {
                let doc = Document {
                    id: "openapi".into(),
                    dir: OUT_DIR.into(),
                    // the document's own contract is the OpenAPI specification, named by
                    // its `openapi` member; it declares no schema of ours
                    schema: None,
                    source: "the canonical Majordomus capability registry".into(),
                    style: HeaderStyle::Extension,
                    value: openapi::document(registry, version, cases)
                        .map_err(|reason| Error::Http { reason })?,
                };
                out.extend(doc.artifacts(version));
            }
            Target::Docs => {
                out.push(Artifact::markdown(
                    format!("{OUT_DIR}/capabilities.md"),
                    "capabilities",
                    "the canonical Majordomus capability registry",
                    version,
                    &reference(registry),
                ));
                let cli = crate::cli::tree();
                out.push(Artifact::markdown(
                    format!("{OUT_DIR}/cli.md"),
                    "cli",
                    "the clap declaration in apps/majordomus-cli/src/cli.rs and the examples beside it",
                    version,
                    &cli_reference(&cli),
                ));
                out.extend(
                    Document::new(
                        "cli",
                        crate::cli::SCHEMA,
                        "the clap declaration in apps/majordomus-cli/src/cli.rs and the examples beside it",
                        cli_document(&cli, version),
                    )
                    .artifacts(version),
                );
                for m in registry
                    .modules()
                    .filter(|m| m.source != ModuleSource::Declarative)
                {
                    out.push(Artifact::markdown(
                        format!("{OUT_DIR}/modules/{}.md", m.id),
                        format!("modules/{}", m.id),
                        format!(
                            "the `{}` module of the canonical Majordomus capability registry",
                            m.id
                        ),
                        version,
                        &module_reference(registry, m.id.as_str()),
                    ));
                }
            }
            Target::Registry => out.extend(
                Document::new(
                    "registry",
                    REGISTRY_SCHEMA,
                    "the canonical capability registry",
                    registry_manifest(registry),
                )
                .artifacts(version),
            ),
            Target::Benchmarks
            | Target::Allow
            | Target::Documents
            | Target::Providers
            | Target::Editors
            | Target::Site
            | Target::Web
            | Target::Changelog
            | Target::Distribution
            | Target::Deployment
            | Target::Graph
            | Target::Design
            | Target::Economics
            | Target::Manifest => {}
        }
    }
    Ok(out)
}

/// Every artifact of the selected targets, from every source: the registry (OpenAPI, the
/// reference, the registry manifest, the benchmark matrix), the schemas (allow-lists), the
/// policy and the templates (provider bootstraps), and the registry with the index (the
/// site dataset). This is the one plan `generate` writes and `generate --check` compares;
/// nothing else assembles artifacts.
pub fn plan(app: &App, targets: &[Target]) -> Result<Vec<Artifact>> {
    // the manifest indexes the artifacts of the plan it belongs to. Asked for alone
    // (`generate manifest`) that plan is every other target, because a manifest of nothing
    // but itself would be a lie; asked for beside a subset, it indexes that subset.
    let wants_manifest = targets.contains(&Target::Manifest);
    let alone = targets == [Target::Manifest];
    let indexed: Vec<Target> = if alone {
        Target::indexed()
    } else {
        targets
            .iter()
            .copied()
            .filter(|t| *t != Target::Manifest)
            .collect()
    };
    let mut out = indexed_plan(app, &indexed)?;
    if wants_manifest {
        let manifest = manifest_document(&out);
        if alone {
            out.clear();
        }
        out.extend(manifest_artifacts(&manifest, crate::VERSION));
    }
    Ok(out)
}

/// Every artifact the manifest indexes: everything but the manifest itself.
fn indexed_plan(app: &App, targets: &[Target]) -> Result<Vec<Artifact>> {
    let mut out = context_artifacts(&app.context, crate::VERSION, targets)?;
    // The schemas and their projections belong to the tool's data directory. When that
    // directory is not inside the repository being generated — a test pointing a fixture at
    // the distribution beside the crate, an installed tool run in someone else's tree —
    // their paths do not resolve under this root, and writing them would reach outside it.
    // There is nothing to project in that case, and saying so here is what keeps every
    // caller of `write` inside the root it was given.
    let share_is_here = app.share.dir().starts_with(app.repository.root());
    if share_is_here && (targets.contains(&Target::Documents) || targets.contains(&Target::Allow)) {
        let protos = document_schemas(&app.share, app.repository.root())?;
        if targets.contains(&Target::Documents) {
            out.extend(document_artifacts(
                &protos,
                &app.share,
                app.repository.root(),
                crate::VERSION,
            )?);
        }
        if targets.contains(&Target::Allow) {
            out.extend(proto_allow_artifacts(
                &protos,
                &app.share,
                app.repository.root(),
                crate::VERSION,
            )?);
            out.extend(allow_artifacts(
                &app.schema,
                &app.share,
                app.repository.root(),
                crate::VERSION,
            ));
        }
    }
    if targets.contains(&Target::Changelog) {
        // The changelog is composed from the layer's own release records, the decisions
        // dated inside each release's window, and the repository's commits up to the newest
        // release — the published half of what `release.changelog` answers with. The
        // unreleased section is `<last release>..HEAD`, and a file inside a commit cannot
        // describe the commit it is in; a committed artifact that tried made every commit
        // stale by construction. The API, MCP and the Cockpit add that section at request
        // time, where HEAD is a fact and not a promise. The Markdown is the rendering a
        // person reads; the JSON and YAML are the document every other reader gets, and all
        // three are compared by `generate --check`.
        let mut log =
            crate::release::compose_published(app.repository.root(), &app.context.index.objects);
        // A repository without the history of a release — an exported fixture, a shallow
        // clone — cannot compose what that release changed, and composing it anyway wrote a
        // changelog of empty sections and called the committed one stale (I1409). What such
        // a release changed is kept as committed, and said, rather than judged on history
        // this repository does not have.
        let unreadable = crate::release::changelog::unreadable_releases(
            app.repository.root(),
            &app.context.index.objects,
        );
        if !unreadable.is_empty() {
            let committed =
                std::fs::read_to_string(app.repository.root().join(OUT_DIR).join("changelog.json"))
                    .ok()
                    .and_then(|text| {
                        serde_json::from_str::<crate::release::model::Changelog>(&text).ok()
                    });
            let kept = committed
                .map(|c| crate::release::changelog::keep_committed(&mut log, &c, &unreadable))
                .unwrap_or_default();
            if let (Some(newest), Some(oldest)) = (kept.first(), kept.last()) {
                tracing::warn!(
                    "{OUT_DIR}/changelog.*: what {} release(s) changed ({newest} back to \
                     {oldest}) is kept as committed and not judged: their history is not in \
                     this repository's object database",
                    kept.len()
                );
            }
        }
        // The committed document names its producer the way the served one does, so a page
        // rendering either can find the same value on every other surface without a route
        // or an id of its own.
        log.produced_by = crate::capability::builtin::release::produced_by(&app.context.registry);
        let value = serde_json::to_value(&log).unwrap_or(serde_json::Value::Null);
        out.extend(
            Document::new(
                "changelog",
                crate::release::model::CHANGELOG_SCHEMA,
                "the layer's release records, the decisions dated in each release's window, and the commits in its range",
                value,
            )
            .artifacts(crate::VERSION),
        );
        out.push(Artifact::markdown(
            format!("{OUT_DIR}/changelog.md"),
            "changelog",
            "the layer's release records, the decisions dated in each release's window, and the commits in its range",
            crate::VERSION,
            &crate::release::changelog::render(&log),
        ));
    }

    if targets.contains(&Target::Editors) {
        let editors = crate::editors::plan(
            &app.context.index,
            &app.context.registry,
            app.repository.root(),
            crate::VERSION,
        );
        // a projection that would differ by whether this machine has `just` is not derived
        // from the tree; refuse instead of committing whichever half this runner could see
        if let Some(d) = editors
            .diagnostics
            .iter()
            .find(|d| d.code == crate::editors::WORKFLOWS_UNREADABLE)
        {
            return Err(Error::Refused {
                code: 12,
                reason: format!("generate editors: {}; {}", d.message, d.remedy),
            });
        }
        out.extend(editors.artifacts);
    }

    let needs_policy = targets.contains(&Target::Providers) || targets.contains(&Target::Site);
    if needs_policy {
        let policy = LoadedPolicy::load(&app.repository)?;
        if targets.contains(&Target::Providers) {
            out.extend(crate::providers::artifacts(
                &app.repository,
                &app.share,
                &policy,
            )?);
        }
        if targets.contains(&Target::Site) {
            let dataset =
                crate::site::dataset(&app.context, &app.schema, &policy, &app.repository)?;
            out.push(Artifact::verbatim(
                format!("{SITE_DATA_DIR}/registry.json"),
                "site-registry",
                ArtifactFormat::Json,
                Some(crate::site::SCHEMA.to_string()),
                "the capability registry and the index of this repository's layer",
                crate::site::render(&dataset),
            ));
            // The evidence subjects as the site reads them: every declaration a verdict can
            // be asked about, what it is made of and the tests it reaches. Structure only —
            // no ledger row, no commit — and read from kinds the site pass does not write,
            // so both `generate` passes of the derivation agree byte for byte.
            out.push(crate::evidence::subject::artifact(
                &app.context,
                crate::VERSION,
            )?);
            // The Why catalogue as the site reads it, and the graph of it. Both are
            // derived from the catalogue alone — never from the index's fingerprint —
            // so the two `generate` passes of the derivation graph agree byte for byte
            // even though the pass between them adds documents to the index.
            out.extend(crate::site::why_artifacts(&app.context)?);
            // The product model as the site reads it: the features with everything
            // derived, the matrix, the providers. Index-independent like the catalogue,
            // so both `generate` passes of the derivation graph agree byte for byte.
            out.extend(crate::site::product_artifacts(&app.context)?);
        }
    }
    // The design and the version are the tool's own and are projected into the tool's own
    // tree — the share directory, the crate, the site. Where the share is not inside this
    // repository, or the crate is not here, there is nothing of this repository's to project.
    let crate_is_here = app
        .repository
        .root()
        .join(crate::release::version::MANIFEST)
        .is_file();
    if targets.contains(&Target::Distribution) {
        out.extend(distribution_artifacts(app)?);
        if share_is_here && crate_is_here {
            out.push(version_projection(app.repository.root()));
        }
    }
    if share_is_here && crate_is_here && targets.contains(&Target::Design) {
        out.extend(design_artifacts(app)?);
    }
    if targets.contains(&Target::Deployment) {
        for object in app
            .context
            .index
            .objects
            .iter()
            .filter(|o| o.kind == crate::deploy::KIND)
        {
            let deployment = crate::deploy::Deployment::parse(object).map_err(|refusal| {
                Error::InvalidDeployment {
                    reason: refusal.to_string(),
                }
            })?;
            // The builder pins the toolchain the repository builds with, read from the one
            // file that declares it; a repository without an exact pin cannot render one.
            let rust = crate::deploy::render::builder_rust(app.repository.root())
                .map_err(|reason| Error::InvalidDeployment { reason })?;
            out.extend(crate::deploy::render::artifacts(
                &deployment,
                &object.provenance.path,
                &rust,
            ));
        }
    }
    Ok(out)
}

/// The projection of the version the shell tool reads at start-up, `share/version.txt`.
///
/// Its value is the authority read directly — [`crate::release::version::declared`] — and
/// not this executable's own constant, which the foreign-generation guard of
/// `majordomus generate` has already proved equal to it wherever the crate's sources are.
/// Part of the distribution target because it is part of what the distribution ships: every
/// archive carries `share/` whole, and the release plan's `generate distribution --check`
/// holds it.
///
/// ```
/// use majordomus_cli::generate::version_projection;
/// use majordomus_cli::release::version::{parse_projection, MANIFEST, PROJECTION};
/// let dir = tempfile::tempdir().unwrap();
/// std::fs::create_dir_all(dir.path().join("apps/majordomus-cli")).unwrap();
/// std::fs::write(dir.path().join(MANIFEST), "[package]\nversion = \"0.9.0\"\n").unwrap();
/// let artifact = version_projection(dir.path());
/// assert_eq!(artifact.path, PROJECTION);
/// assert!(artifact.content.starts_with("# GENERATED FILE"));
/// assert_eq!(parse_projection(&artifact.content).as_deref(), Some("0.9.0"));
/// ```
pub fn version_projection(root: &Path) -> Artifact {
    use crate::release::version::{declared, render_projection, MANIFEST, PROJECTION};
    let version = declared(root).unwrap_or_else(|| crate::VERSION.to_string());
    Artifact::text(
        PROJECTION,
        "version",
        format!("{MANIFEST} ([package] version), the one place the version is authored"),
        crate::VERSION,
        &render_projection(&version),
    )
}

/// Every artifact the distribution model produces. The model is read from the tool's own
/// data directory, which is the file an installed copy carries; the release records are
/// read from the repository. Nothing here decides a platform, a name or a URL — it renders
/// what `share/distribution.yaml` and `.ai/repo/releases/` already say.
pub fn distribution_artifacts(app: &App) -> Result<Vec<Artifact>> {
    use crate::distribution::{release, render, Model, Releases};

    let model = Model::load(&app.share)?;
    let releases = Releases::load(app.repository.root())?;
    let findings = releases.findings(&model);
    if let Some(first) = findings.first() {
        return Err(Error::InvalidRelease {
            path: release::DIR.to_string(),
            reason: if findings.len() == 1 {
                first.clone()
            } else {
                format!("{first} (and {} more)", findings.len() - 1)
            },
        });
    }

    use crate::distribution::render::SOURCE as DIST_SOURCE;
    let mut out = vec![
        Artifact::verbatim(
            format!("{OUT_DIR}/distribution-matrix.json"),
            "distribution-matrix",
            ArtifactFormat::Json,
            None,
            DIST_SOURCE,
            render::matrix_json(&model),
        ),
        Artifact::verbatim(
            format!("{SITE_DATA_DIR}/distribution.json"),
            "site-distribution",
            ArtifactFormat::Json,
            None,
            DIST_SOURCE,
            render::site_dataset(&model, &releases),
        ),
    ];

    let installer_template = read_share(&app.share, crate::distribution::INSTALLER_TEMPLATE)?;
    out.push(Artifact::verbatim(
        format!(
            "{}/{}",
            crate::distribution::PUBLIC_DIR,
            model.installer.script
        ),
        "installer",
        ArtifactFormat::Text,
        None,
        DIST_SOURCE,
        render::installer(&model, &installer_template).map_err(|reason| {
            Error::InvalidDistribution {
                path: crate::distribution::INSTALLER_TEMPLATE.to_string(),
                reason,
            }
        })?,
    ));

    let guide_template = read_share(&app.share, crate::distribution::GUIDE_TEMPLATE)?;
    let guide = render::install_doc(&model, &releases, crate::VERSION, &guide_template).map_err(
        |reason| Error::InvalidDistribution {
            path: crate::distribution::GUIDE_TEMPLATE.to_string(),
            reason,
        },
    )?;
    // The provenance header goes after the title, not before it: the site's documentation
    // projection strips a document's own first-line heading and would otherwise render two.
    let (title, rest) = guide.split_once('\n').unwrap_or((guide.as_str(), ""));
    out.push(Artifact::verbatim(
        crate::distribution::GUIDE.to_string(),
        "install-guide",
        ArtifactFormat::Markdown,
        None,
        "share/install/INSTALL.md.in (the prose) and share/distribution.yaml (every platform, name and URL)",
        format!(
            "{title}\n<!-- {HEADER}\n     Source: share/install/INSTALL.md.in (the prose) and share/distribution.yaml (every platform, name and URL);\n     regenerate with `majordomus generate`\n     Generator: majordomus-cli {} -->\n{rest}",
            crate::VERSION
        ),
    ));

    for r in &releases.releases {
        out.push(Artifact::verbatim(
            format!("{}/{}.json", release::PUBLIC_DIR, r.tag),
            format!("release/{}", r.tag),
            ArtifactFormat::Json,
            None,
            format!("the release record {}", r.tag),
            r.public_json(&model),
        ));
    }
    if let Some(latest) = releases.latest_stable() {
        out.push(Artifact::verbatim(
            format!("{}/{}.json", release::PUBLIC_DIR, release::LATEST),
            "release/latest",
            ArtifactFormat::Json,
            None,
            "the latest stable release record",
            release::latest_json(latest, &model),
        ));
    }
    Ok(out)
}

/// A source file a projection compiles, read as text: a failure names the path it read.
fn read_source(path: &Path) -> Result<String> {
    std::fs::read_to_string(path).map_err(|e| Error::io(path, e))
}

/// A file of the tool's data directory, read as text.
/// Every projection of the design system. The declaration is read from the tool's data
/// directory, validated, and rendered by [`crate::design::render`]; a stylesheet that would
/// be malformed is refused here rather than written, because the CSS parser would drop the
/// defect in silence and every check downstream would stay green.
pub(crate) fn design_artifacts(app: &App) -> Result<Vec<Artifact>> {
    use crate::design::{render, DesignSystem, DOCUMENT_SCHEMA, SHARE_PATH, SITE_SCHEMA, SOURCE};

    let path = app.share.dir().join(SHARE_PATH);
    let text = std::fs::read_to_string(&path).map_err(|e| Error::io(&path, e))?;
    let design = DesignSystem::parse(&text).map_err(|reason| Error::InvalidDesign {
        path: SOURCE.to_string(),
        reason,
    })?;
    let version = crate::VERSION;
    let source = render::SOURCE_LINE;
    let mut out = Vec::new();

    for (path, document, body) in [
        (
            render::THEME_CSS,
            "design-theme",
            render::theme_css(&design),
        ),
        (
            render::SURFACE_CSS,
            "design-surface",
            render::surface_css(&design),
        ),
        (
            render::STATUS_CSS,
            "design-status",
            render::status_css(&design),
        ),
        (
            render::TOKENS_CSS,
            "design-tokens",
            render::tokens_css(&design),
        ),
    ] {
        render::well_formed(&body).map_err(|reason| Error::InvalidDesign {
            path: path.to_string(),
            reason,
        })?;
        out.push(Artifact::comment_text(
            path, document, source, version, &body,
        ));
    }

    // the declaration itself, compiled into the crate so the executable answers from the
    // design its stylesheets were projected from
    out.push(Artifact::verbatim(
        render::COMPILED_YAML,
        "design-declaration",
        ArtifactFormat::Yaml,
        None,
        source,
        // `.as_str()` rather than `&text`: with rhai linked, `String + &String` has more than
        // one `Add` implementation to choose from and no longer coerces (ADR 0069)
        comment_banner(source, version) + text.as_str(),
    ));

    // the brand: one canonical file per mark under share/design/brand, and every copy a
    // surface serves written from it, so no copy is edited on its own
    let brand = |relative: &str| -> Result<String> {
        let p = app.share.dir().join("design").join(relative);
        std::fs::read_to_string(&p).map_err(|e| Error::io(&p, e))
    };
    let mark = brand(&design.identity.mark)?;
    let logo = brand(&design.identity.logo)?;
    let mark_source = format!("share/design/{}, the canonical mark", design.identity.mark);
    let logo_source = format!("share/design/{}, the canonical logo", design.identity.logo);
    for path in [
        render::COMPILED_MARK,
        "share/cockpit/favicon.svg",
        crate::ui::FAVICON,
        "site/static/favicon.svg",
        "site/static/images/logo-mark.svg",
    ] {
        out.push(Artifact::comment_text(
            path,
            "design-mark",
            mark_source.clone(),
            version,
            &mark,
        ));
    }
    out.push(Artifact::comment_text(
        "site/static/images/logo.svg",
        "design-logo",
        logo_source,
        version,
        &logo,
    ));

    // the kit's icons, declared once beside the site's templates and compiled into the
    // crate for the UI's shell (ADR 0135), so the two surfaces draw one icon set. A tree
    // without the site (a design fixture holds `share/` alone) has no set to compile and no
    // crate to compile it into; in this repository the set is present, and `ui::icons`
    // holds the compiled copy equal to it in a test, so its absence cannot pass unnoticed.
    let icons_path = app.repository.root().join(crate::ui::icons::SOURCE);
    if icons_path.is_file() {
        let icons = read_source(&icons_path)?;
        out.push(Artifact::comment_text(
            crate::ui::icons::COMPILED,
            "ui-icons",
            format!("{}, the kit's icons", crate::ui::icons::SOURCE),
            version,
            &icons,
        ));
    }

    // the site's dataset and the reference documents
    out.push(Artifact::verbatim(
        render::SITE_JSON,
        "site-design",
        ArtifactFormat::Json,
        Some(SITE_SCHEMA.to_string()),
        source,
        openapi::render(&render::site_document(&design, version)),
    ));
    out.extend(
        Document::new(
            render::DOCUMENT,
            DOCUMENT_SCHEMA,
            source,
            render::document(&design),
        )
        .artifacts(version),
    );
    out.push(Artifact::markdown(
        format!("{OUT_DIR}/{}.md", render::DOCUMENT),
        render::DOCUMENT,
        source,
        version,
        &render::reference_markdown(&design),
    ));
    Ok(out)
}

fn read_share(share: &Share, relative: &str) -> Result<String> {
    let path = share.dir().join(relative);
    std::fs::read_to_string(&path).map_err(|e| Error::io(&path, e))
}

/// Every artifact of the selected targets, the benchmark matrix included: what
/// `majordomus generate` writes and `--check` compares.
pub fn context_artifacts(
    ctx: &Context,
    version: &str,
    targets: &[Target],
) -> Result<Vec<Artifact>> {
    let cases = CaseContext { index: &ctx.index };
    let mut out = artifacts(&ctx.registry, version, Some(&cases), targets)?;
    if targets.contains(&Target::Benchmarks) {
        let source = "the benchmark projection of the canonical capability registry";
        out.push(Artifact::markdown(
            format!("{OUT_DIR}/benchmarks.md"),
            "benchmarks",
            source,
            version,
            &benchmark_matrix(ctx),
        ));
        out.extend(
            Document::new(
                "benchmarks",
                BENCHMARKS_SCHEMA,
                source,
                benchmark_document(ctx),
            )
            .artifacts(version),
        );
    }
    if targets.contains(&Target::Web) {
        out.extend(
            Document::new(
                "web",
                WEB_SCHEMA,
                "the resolved web topology of this repository",
                web_topology(ctx),
            )
            .artifacts(version),
        );
    }
    if targets.contains(&Target::Docs) {
        let source = "the provider declarations the distribution ships (share/providers.yaml), the templates beside them, and this repository's policy";
        let value = providers_document(ctx)?;
        out.push(Artifact::markdown(
            format!("{OUT_DIR}/providers.md"),
            "providers",
            source,
            version,
            &providers_markdown(&value),
        ));
        out.extend(Document::new("providers", PROVIDERS_SCHEMA, source, value).artifacts(version));
    }
    if targets.contains(&Target::Economics) {
        let source = "the token-economics methodology and every benchmark run committed under .ai/repo/benchmarks/economics";
        // the tracked records only: two checkouts of one commit must generate the same
        // bytes, whatever either has recorded locally and not committed
        let summary = crate::economics::summarize_tracked(
            std::path::Path::new(&ctx.index.repository.root),
            &Default::default(),
        );
        out.push(Artifact::markdown(
            format!("{OUT_DIR}/economics.md"),
            "economics",
            source,
            version,
            &crate::economics::report::markdown(&summary),
        ));
        let value = serde_json::to_value(&summary).map_err(|e| Error::Protocol {
            reason: format!("the economics summary does not serialise: {e}"),
        })?;
        out.extend(Document::new("economics", ECONOMICS_SCHEMA, source, value).artifacts(version));
    }
    if targets.contains(&Target::Graph) {
        out.push(Artifact::verbatim(
            format!("{OUT_DIR}/graph.json"),
            "graph",
            ArtifactFormat::Json,
            Some(GRAPH_SCHEMA.to_string()),
            "the composed graph of the registry and the index",
            graph_document(ctx, version)?,
        ));
        out.push(Artifact::verbatim(
            format!("{OUT_DIR}/graph.schema.json"),
            "graph-schema",
            ArtifactFormat::Json,
            None,
            "the schema of the composed graph, generated from its types",
            graph_schema_document(version),
        ));
    }
    Ok(out)
}

/// Every provider as data: the product model's providers — the declaration decorated with
/// what this repository's policy renders through it, the client configuration it carries and
/// the hooks the policy wires — and the tool's own scratch roots. Answered by the same
/// capability `majordomus product providers`, `majordomus_providers` and
/// `GET /api/v1/product/providers` answer, so the file and the interfaces cannot disagree.
pub fn providers_document(ctx: &Context) -> Result<Value> {
    let id = ctx
        .registry
        .by_cli(&["product".to_string(), "providers".to_string()])
        .map(|c| c.id.to_string())
        .ok_or_else(|| Error::Protocol {
            reason: "no capability is exposed as `majordomus product providers`".into(),
        })?;
    let answer = ctx
        .execute(&id, serde_json::json!({}))
        .map_err(|e| Error::Protocol {
            reason: e.to_string(),
        })?;
    Ok(serde_json::json!({
        "scratch_roots": ctx.index.providers.scratch_roots,
        "count": answer["count"],
        "providers": answer["providers"],
    }))
}

/// `docs/generated/providers.md`: the same value as a table a person reads, with the
/// grammar of a scratch root beside it.
pub fn providers_markdown(value: &Value) -> String {
    let cell = |v: &Value| -> String {
        let items: Vec<String> = v
            .as_array()
            .into_iter()
            .flatten()
            .map(|x| match x {
                Value::String(s) => format!("`{s}`"),
                other => other
                    .get("target")
                    .and_then(Value::as_str)
                    .map(|t| {
                        if other.get("always_loaded") == Some(&Value::Bool(true)) {
                            format!("`{t}` (always loaded)")
                        } else {
                            format!("`{t}`")
                        }
                    })
                    .unwrap_or_default(),
            })
            .collect();
        if items.is_empty() {
            "—".to_string()
        } else {
            items.join(", ")
        }
    };
    let mut s = String::new();
    s.push_str("# Providers\n\n");
    s.push_str("Every provider the tool ships an adapter for, and what this repository does with each. The set is the templates under `share/providers/`; the title, the client configuration a provider reads and the scratch roots it creates checkouts under are `share/providers.yaml`; the bootstraps are the policy's `projections[]`; whether a client configuration is present and which hooks are wired are facts of this tree. `majordomus product providers`, the MCP tool `majordomus_providers`, `GET /api/v1/product/providers` and the site's provider cards answer from the same value. A document that names providers points here rather than listing them (ADR 0024).\n\n");
    s.push_str("| provider | title | bootstraps | client configuration | hooks | scratch roots |\n|---|---|---|---|---|---|\n");
    for p in value["providers"].as_array().into_iter().flatten() {
        let str_of = |k: &str| {
            p.get(k)
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_string()
        };
        s.push_str(&format!(
            "| `{}` | {} | {} | {} | {} | {} |\n",
            str_of("id"),
            str_of("title"),
            cell(&p["bootstraps"]),
            p.get("client_config")
                .and_then(Value::as_str)
                .map(|c| format!("`{c}`"))
                .unwrap_or_else(|| "—".to_string()),
            cell(&p["hooks"]),
            cell(&p["scratch_roots"]),
        ));
    }
    s.push_str(&format!(
        "\n{} provider(s).\n\n## The tool's own scratch roots\n\n",
        value["count"].as_u64().unwrap_or(0)
    ));
    s.push_str("A checkout under any of these, or under a provider's root above, is a session's scratch checkout to the worktree topology: reported, never migrated unasked, never cleaned up by the tool, refused by the commit guard with the remedy of continuing in the canonical worktree. A root the primary checkout itself lives under is skipped.\n\n");
    for r in value["scratch_roots"].as_array().into_iter().flatten() {
        if let Some(r) = r.as_str() {
            s.push_str(&format!("- `{r}`\n"));
        }
    }
    s.push_str("\nA root is expanded before it is compared: `<primary>/` is the primary checkout, `~` the home directory, `${NAME:-default}` an environment variable with a default, `$NAME` one without — a root whose variable is unset is skipped.\n");
    s
}

/// The resolved web topology as data: every surface with its mount, category, visibility,
/// kind, producer, artifact, runtime feature and provenance, in route-precedence order.
///
/// It is the same value the `web.surfaces` capability answers and the same one the router
/// serves from — this file exists because the site generator runs without a Rust toolchain
/// and reads committed artifacts, not because the topology has a second source — less the
/// one part of that value which is a fact of a checkout rather than of the repository.
///
/// A surface that discovery declares from what says it exists is in it whether or not its
/// producer has run: the documentation, declared from the site's configuration, and the
/// crate's rustdoc, declared from the crate. Whether its directory is presently on disk is
/// a fact of a checkout, and so is the revision it was built from, which is dropped. A
/// surface known *only* from the declaration its producer wrote — a report — exists in the
/// checkout that ran the producer and in no other, so it is left out: the resolution a
/// process serves still holds it, and the committed file does not change because somebody
/// ran the suite. That is what keeps the file stable enough for `generate --check` to
/// compare, and what lets the site build trust that every published surface named here is
/// one every machine is expected to build.
pub fn web_topology(ctx: &Context) -> Value {
    web_document(&ctx.web)
}

/// The projection of one resolved topology, apart from the context that resolved it, so
/// that what the committed file depends on can be measured over a directory rather than
/// over a whole index.
fn web_document(topology: &crate::web::Topology) -> Value {
    let surfaces: Vec<Value> = surfaces_every_checkout_has(topology)
        .map(|s| {
            let mut v = serde_json::to_value(s).unwrap_or(Value::Null);
            // a built revision is a fact of one checkout's artifacts, never of the
            // repository: it would make this file differ per machine
            if let Some(map) = v.as_object_mut() {
                map.remove("built_from");
            }
            v
        })
        .collect();
    // The schema, the provenance and the generator are the document's, added by
    // `Document`: stating them here as well would be two statements of one thing, and the
    // encodings would then have to agree about which of them was right.
    serde_json::json!({
        "generated_root": crate::web::discover::GENERATED_ROOT,
        // the reservations as data, from the one place that declares them: the validator
        // refuses a topology that breaks one of these, and the site renders this map
        "reserved": crate::web::discover::reserved()
            .into_iter()
            .map(|r| (r.role.to_string(), Value::String(r.path.to_string())))
            .collect::<serde_json::Map<String, Value>>(),
        "surfaces": surfaces,
    })
}

/// The surfaces of a topology that every checkout of the repository has: all of them but
/// those known only from a declaration a producer wrote in this one.
///
/// Every committed number or list of surfaces is read through this, so that the projection
/// and a count of it cannot disagree: `site/data/registry/product.json` once counted the
/// whole resolution while `web.json` filtered it, and a worktree that had run
/// `majordomus web report tests` committed eleven surfaces where a clean checkout derives ten.
pub(crate) fn surfaces_every_checkout_has(
    topology: &crate::web::Topology,
) -> impl Iterator<Item = &crate::web::Surface> {
    topology
        .surfaces
        .iter()
        .filter(|s| !only_where_its_producer_ran(s))
}

/// Whether a surface was found only by walking the generated root: its mount, or any other
/// value, came from the declaration a producer wrote beside its output.
///
/// That provenance is the walk's alone — every surface discovery declares from a source
/// (the registry, the site's configuration, the crate) says so instead — so it is the
/// discovered fact of "this exists because a producer ran here", not a list of report ids
/// kept beside the reports.
fn only_where_its_producer_ran(surface: &crate::web::Surface) -> bool {
    surface
        .provenance
        .values()
        .any(|p| matches!(p, crate::web::Provenance::ProducerDeclaration { .. }))
}

/// The schema of `graph.json`.
pub const GRAPH_SCHEMA: &str = "majordomus/capability-graph/v1";

/// Text that must never reach a published artifact: a path belonging to the machine that
/// generated it, and the shapes credentials are written in. The list is short on purpose —
/// every entry is something no derivation of this repository can legitimately produce, so
/// a hit is a defect rather than a judgement call.
const FORBIDDEN: &[(&str, &str)] = &[
    (
        "/Users/",
        "an absolute path on the machine that generated this",
    ),
    (
        "/home/",
        "an absolute path on the machine that generated this",
    ),
    (
        "/root/",
        "an absolute path on the machine that generated this",
    ),
    ("-----BEGIN ", "a PEM block"),
    ("Authorization:", "an authorization header"),
    ("Bearer ", "a bearer token"),
    ("AKIA", "an access key id"),
    ("ghp_", "a personal access token"),
    ("github_pat_", "a personal access token"),
];

/// The first forbidden marker in `content`, with what it is, or `None` when the content is
/// safe to publish.
///
/// The example joins the marker and a name at run time: this file is committed, and a
/// committed file that named a home directory would fail the very gate the marker exists
/// to keep the artifacts through.
///
/// ```
/// use majordomus_cli::generate::forbidden_in;
/// assert!(forbidden_in("nodes are repository-relative").is_none());
/// let machine_path = format!("source: {}someone/dev", "/Users/");
/// assert_eq!(forbidden_in(&machine_path).map(|(m, _)| m), Some("/Users/"));
/// ```
pub fn forbidden_in(content: &str) -> Option<(&'static str, &'static str)> {
    FORBIDDEN
        .iter()
        .find(|(marker, _)| content.contains(marker))
        .map(|(marker, what)| (*marker, *what))
}

/// The composed graph as a published artifact: the graph itself, and the provenance JSON
/// cannot carry as a comment recorded as fields of the document.
///
/// Refuses rather than writes when the rendered document carries anything from
/// `FORBIDDEN`: this file is published to a website, and a leak that is generated is a
/// leak that regenerates.
///
/// Refuses, for the same reason, while the layer names a rule, a decision or a capability
/// that no object and no declaration answers to. The composed graph drops the edge such a
/// reference would draw, so the defect is invisible in the artifact: the file looks whole
/// and is quietly short of one edge. [`crate::graph::unresolved_relations`] is the verdict
/// that already decides it — this is the consumer its own contract names.
pub fn graph_document(ctx: &Context, version: &str) -> Result<String> {
    graph_document_of(
        ctx,
        version,
        crate::graph::composed_complete(&ctx.registry, &ctx.index),
    )
}

/// [`graph_document`] over a composition already made, so the refusal of one that stopped
/// at a bound is reached by a test as it would be by a bound that comes back.
fn graph_document_of(
    ctx: &Context,
    version: &str,
    composed: crate::graph::Graph,
) -> Result<String> {
    let unresolved = crate::graph::unresolved_relations(&ctx.registry, &ctx.index.objects);
    if !unresolved.is_empty() {
        return Err(Error::UnresolvedRelation {
            findings: unresolved
                .iter()
                .map(|u| {
                    format!(
                        "{}: {} names `{}`, which resolves to nothing; {}",
                        u.declared_in, u.key, u.reference, u.correction
                    )
                })
                .collect(),
        });
    }
    // whole: the site's entity pages and its catalogue counts are read off this document,
    // and a prefix of the repository would drop what sorts past MAX_NODES without a word
    let graph = committed_graph(composed)?;
    let doc = serde_json::json!({
        "schema": GRAPH_SCHEMA,
        "generated": format!("{HEADER}; source: the capability registry and every object of the index; regenerate with `majordomus generate`"),
        "generator": format!("majordomus-cli {version}"),
        "graph": graph,
    });
    let rendered = openapi::render(&doc);
    if let Some((marker, what)) = forbidden_in(&rendered) {
        return Err(Error::Http {
            reason: format!(
                "the composed graph carries {what} (`{marker}`) and would publish it; \
                 a node's source is repository-relative, so find the derivation that put an \
                 absolute path or a secret on a node before regenerating"
            ),
        });
    }
    Ok(rendered)
}

/// The composed graph as it may be committed: a graph that stopped at a bound is refused
/// with the count it held and the bound, and nothing is written, as an unresolved relation
/// is refused before it. The composition has no bound today; this is what keeps one that
/// comes back from committing a prefix that still reads as whole (I1966).
fn committed_graph(graph: crate::graph::Graph) -> Result<crate::graph::Graph> {
    crate::graph::whole(graph).map_err(|reason| Error::Refused { code: 10, reason })
}

/// The schema of the composed graph, generated from the types that define it rather than
/// written beside them.
pub fn graph_schema_document(version: &str) -> String {
    let schema = crate::capability::schema::CanonicalSchema::of::<crate::graph::Graph>();
    // a JSON Schema's own members are fixed by its specification, so the provenance rides
    // in the extension the manifest validator reads beside `generated`
    let doc = serde_json::json!({
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": GRAPH_SCHEMA,
        "description": format!("{HEADER}; source: the Rust types of majordomus_cli::graph; regenerate with `majordomus generate`; generator majordomus-cli {version}"),
        "x-majordomus-generated": json_banner("the Rust types of majordomus_cli::graph"),
        "x-majordomus-generator": format!("majordomus-cli {version}"),
        "definitions": { "Graph": schema.schema },
        "$ref": "#/definitions/Graph",
    });
    openapi::render(&doc)
}

/// The builtin registry as data: modules, descriptors with their schemas, and the
/// declarative kinds by name. No fingerprint and no count of declarative objects, so the
/// file changes when the code changes and not when a document is added.
pub fn registry_manifest(registry: &CapabilityRegistry) -> Value {
    let modules: Vec<&crate::capability::registry::ModuleInfo> = registry
        .modules()
        .filter(|m| m.source != ModuleSource::Declarative)
        .collect();
    // every descriptor as it is, plus the file it was composed in: the one place a reader
    // of the manifest (the site generator among them) learns where a capability's source is
    let capabilities: Vec<Value> = registry
        .iter()
        .filter(|c| matches!(c.provenance, Provenance::Builtin { .. }))
        .map(|c| {
            let mut v = serde_json::to_value(c).unwrap_or(Value::Null);
            if let Some(o) = v.as_object_mut() {
                o.insert(
                    "source_path".into(),
                    Value::String(c.provenance.source_path()),
                );
            }
            v
        })
        .collect();
    let declarative_kinds: Vec<&str> = registry
        .modules()
        .filter(|m| m.source == ModuleSource::Declarative)
        .map(|m| m.id.as_str())
        .collect();
    serde_json::json!({
        "modules": modules,
        "capabilities": capabilities,
        "declarative_kinds": declarative_kinds,
        "system_benchmark_targets": SystemTarget::ALL.iter().map(|s| serde_json::json!({ "key": s.key(), "transport": s.transport(), "description": s.description() })).collect::<Vec<_>>(),
    })
}

/// Every benchmark target and the coverage, from the projection of this repository.
pub fn benchmark_matrix(ctx: &Context) -> String {
    let projection = BenchmarkProjection::from_context(ctx);
    let coverage = Coverage::compute(ctx, &projection);
    let mut s = String::new();
    s.push_str("# Benchmark targets and coverage\n\n");
    s.push_str("Every externally callable operation is a benchmark target, derived from the registry: each executable capability directly and on every transport its exposure declares, with the cases its input type provides, plus the transports' own operations. Nothing below is listed by hand; `majordomus bench coverage` computes the same table live, `majordomus bench` times it, and `capabilities validate` fails when a requirement is missing.\n\n");
    s.push_str(
        "## Coverage\n\n| scope | required | covered | missing | waived |\n|---|---|---|---|---|\n",
    );
    for (name, t) in &coverage.tallies {
        s.push_str(&format!(
            "| {name} | {} | {} | {} | {} |\n",
            t.required, t.covered, t.missing, t.waived
        ));
    }
    s.push_str("\n## Capabilities\n\n| capability | module | kind | cache | direct | mcp | http | cases |\n|---|---|---|---|---|---|---|---|\n");
    for c in ctx.registry.iter().filter(|c| c.kind.is_executable()) {
        let cell = |transport: Transport| -> String {
            let line = coverage
                .lines
                .iter()
                .find(|l| l.subject == c.id.as_str() && l.transport == transport);
            match line.map(|l| l.state) {
                Some(CoverageState::Covered) => "covered".into(),
                Some(CoverageState::Missing) => "**missing**".into(),
                Some(CoverageState::Waived) => "waived".into(),
                Some(CoverageState::Inapplicable) => "inapplicable".into(),
                None => "—".into(),
            }
        };
        let mut cases: Vec<String> = projection
            .of_capability(c.id.as_str())
            .filter(|t| t.transport() == Transport::Direct)
            .filter_map(|t| match &t.kind {
                crate::bench::TargetKind::Capability { case, .. } => Some(format!("`{case}`")),
                _ => None,
            })
            .collect();
        cases.dedup();
        let cache = c.cache.summary();
        let kind = serde_json::to_value(c.kind)
            .ok()
            .and_then(|v| v.as_str().map(str::to_string))
            .unwrap_or_default();
        s.push_str(&format!(
            "| `{}` | {} | {} | {} | {} | {} | {} | {} |\n",
            c.id,
            c.module,
            kind,
            cache,
            cell(Transport::Direct),
            cell(Transport::Mcp),
            cell(Transport::Http),
            if cases.is_empty() {
                "—".to_string()
            } else {
                cases.join(", ")
            }
        ));
    }
    s.push_str("\n## System targets\n\n| key | transport | measures |\n|---|---|---|\n");
    for t in SystemTarget::ALL {
        s.push_str(&format!(
            "| `{}` | {} | {} |\n",
            t.key(),
            t.transport().name(),
            t.description()
        ));
    }
    s.push_str("\n## UI pages\n\nEvery screen and panel of the UI's own route list, read with `GET` and `Accept: text/html`: a screen over the pinned context and over the live view a served process answers from (which pays the per-request git stamp), a panel over the pinned context only. Each is measured cold (the capability cache cleared before every sample) and warm. A deferred panel is one the UI pulls in after the screen, because its source is slow; only the `full` profile measures it, with `cold_spawns` samples.\n\n| key | route | view | deferred |\n|---|---|---|---|\n");
    for t in projection.pages() {
        if let crate::bench::TargetKind::Page {
            route,
            view,
            deferred,
        } = &t.kind
        {
            s.push_str(&format!(
                "| `{}` | `{route}` | {} | {} |\n",
                t.key,
                view.name(),
                if *deferred { "yes" } else { "—" }
            ));
        }
    }
    s.push_str("\nCache modes: a cached capability is measured cold (the cache cleared before every sample) and warm (the same input repeated); the direct transport reports the handler invocations of each. Evidence: `.ai/local/benchmarks/` for local runs, `.ai/repo/benchmarks/rust/` for the accepted baselines and the regression policy.\n");
    s
}

/// Every `.proto` document schema, from the distribution and then from the repository,
/// keyed by the identity each declares. A repository may add a schema; it may not redefine
/// one the distribution declares, and an attempt to is an error naming both files.
pub fn document_schemas(
    share: &Share,
    root: &Path,
) -> Result<std::collections::BTreeMap<String, crate::proto::ProtoFile>> {
    let dir = share.schemas_dir();
    crate::proto::read_dir(&dir, &relative_to(&dir, root))
}

/// The projections of the `.proto` document schemas: the JSON Schema beside each one, and
/// the section list the shell tool reads its body contract from.
///
/// Both are committed. `bin/majordomus doctor` is pure shell and validates a fresh
/// checkout with no Rust build having ever run, so the derived forms have to be in the
/// tree; `generate --check` is what keeps them honest.
pub fn document_artifacts(
    protos: &std::collections::BTreeMap<String, crate::proto::ProtoFile>,
    share: &Share,
    root: &Path,
    version: &str,
) -> Result<Vec<Artifact>> {
    let schemas = relative_to(&share.schemas_dir(), root);
    let sections = relative_to(&share.sections_dir(), root);
    let mut out = Vec::new();
    for file in protos.values() {
        let schema = crate::proto::project::to_json_schema(file)?;
        // Relative to the repository, never as this machine found it: the banner is
        // committed, so an absolute path would make the artifact differ by the directory it
        // was generated in — every other checkout would then regenerate all of them and
        // `generate --check` would fail for everyone but the last person to run it.
        let source = format!(
            "the document schema `{}`",
            relative_to(Path::new(&file.source), root)
        );
        let path = format!(
            "{schemas}/{}",
            crate::proto::project::schema_path(&file.schema_id)?
        );
        out.push(Artifact::json_extension(
            path.clone(),
            format!("schemas/{}", file.schema_id),
            source.clone(),
            version,
            serde_json::to_value(&schema).map_err(|e| Error::KindSchema {
                reason: format!("{}: cannot render the projected schema: {e}", file.source),
            })?,
        ));
        if let Some(name) = &file.allow_list {
            let lines = crate::proto::project::section_lines(file);
            out.push(Artifact::text(
                format!("{sections}/{name}.txt"),
                format!("sections/{name}"),
                source.clone(),
                version,
                &if lines.is_empty() {
                    String::new()
                } else {
                    lines.join("\n") + "\n"
                },
            ));
        }
    }
    Ok(out)
}

/// The allow-lists of the `.proto` document schemas, derived from the same projection the
/// JSON Schema beside each one carries, so the two can never disagree.
pub fn proto_allow_artifacts(
    protos: &std::collections::BTreeMap<String, crate::proto::ProtoFile>,
    share: &Share,
    root: &Path,
    version: &str,
) -> Result<Vec<Artifact>> {
    let dir = relative_to(&share.allow_dir(), root);
    let mut out = Vec::new();
    for file in protos.values() {
        let Some(name) = &file.allow_list else {
            continue;
        };
        let schema = crate::proto::project::to_json_schema(file)?;
        out.push(Artifact::text(
            format!("{dir}/{name}.txt"),
            format!("allow/{name}"),
            format!(
                "the document schema `{}`",
                relative_to(Path::new(&file.source), root)
            ),
            version,
            &(allow_lines(&schema).join("\n") + "\n"),
        ));
    }
    Ok(out)
}

/// A share subdirectory as the plan names it: repository-relative when the share is inside
/// the repository, absolute otherwise.
///
/// Both sides are resolved before they are compared. `Share::open` canonicalises the share
/// directory while the repository root arrives as it was discovered, so a share *inside*
/// the repository failed `strip_prefix` whenever the two spellings differed — a symlinked
/// or firmlinked component is enough — and the fallback then wrote the generator's own
/// absolute path into a committed artifact. That made the output depend on which worktree
/// last ran `majordomus generate`, which is precisely what `derive-check` cannot see.
pub(crate) fn relative_to(dir: &Path, root: &Path) -> String {
    let resolved = |p: &Path| p.canonicalize().unwrap_or_else(|_| p.to_path_buf());
    let (dir_resolved, root_resolved) = (resolved(dir), resolved(root));
    match dir_resolved.strip_prefix(&root_resolved) {
        Ok(relative) => relative.display().to_string(),
        Err(_) => dir.display().to_string(),
    }
}

/// The benchmark matrix as data: the same projection `benchmark_matrix` renders for a
/// reader, in the encoding a program reads. One computation, two encodings; a number that
/// differs between the Markdown and the JSON would be two computations, which is the
/// defect this exists to make impossible.
pub fn benchmark_document(ctx: &Context) -> Value {
    let projection = BenchmarkProjection::from_context(ctx);
    let coverage = Coverage::compute(ctx, &projection);
    let coverage_rows: Vec<Value> = coverage
        .tallies
        .iter()
        .map(|(name, t)| {
            serde_json::json!({
                "scope": name,
                "required": t.required,
                "covered": t.covered,
                "missing": t.missing,
                "waived": t.waived,
                "inapplicable": t.inapplicable,
            })
        })
        .collect();
    let capabilities: Vec<Value> = ctx
        .registry
        .iter()
        .filter(|c| c.kind.is_executable())
        .map(|c| {
            let state = |transport: Transport| -> &'static str {
                match coverage
                    .lines
                    .iter()
                    .find(|l| l.subject == c.id.as_str() && l.transport == transport)
                    .map(|l| l.state)
                {
                    Some(CoverageState::Covered) => "covered",
                    Some(CoverageState::Missing) => "missing",
                    Some(CoverageState::Waived) => "waived",
                    Some(CoverageState::Inapplicable) => "inapplicable",
                    None => "none",
                }
            };
            let mut cases: Vec<String> = projection
                .of_capability(c.id.as_str())
                .filter(|t| t.transport() == Transport::Direct)
                .filter_map(|t| match &t.kind {
                    crate::bench::TargetKind::Capability { case, .. } => Some(case.clone()),
                    _ => None,
                })
                .collect();
            cases.dedup();
            serde_json::json!({
                "id": c.id,
                "module": c.module,
                "kind": enum_name(c.kind),
                "cache": cache_cell(c.cache),
                "direct": state(Transport::Direct),
                "mcp": state(Transport::Mcp),
                "http": state(Transport::Http),
                "cases": cases,
            })
        })
        .collect();
    serde_json::json!({
        "coverage": coverage_rows,
        "capabilities": capabilities,
        "system_targets": SystemTarget::ALL.iter().map(|s| serde_json::json!({
            "key": s.key(),
            "transport": s.transport().name(),
            "measures": s.description(),
        })).collect::<Vec<_>>(),
        "pages": projection.pages().filter_map(|t| match &t.kind {
            crate::bench::TargetKind::Page { route, view, deferred } => Some(serde_json::json!({
                "key": t.key,
                "route": route,
                "view": view.name(),
                "deferred": deferred,
            })),
            _ => None,
        }).collect::<Vec<_>>(),
    })
}

// ---------------------------------------------------------------- the manifest

/// The document id of the manifest, and the file stem of its encodings.
pub const MANIFEST_ID: &str = "artifacts";

/// Where the manifest says it came from.
pub const MANIFEST_SOURCE: &str = "the generation plan itself, over every other target";

/// The three files the manifest is written to, in the order [`manifest_artifacts`]
/// returns them.
pub fn manifest_paths() -> [String; 3] {
    [
        format!("{OUT_DIR}/{MANIFEST_ID}.json"),
        format!("{OUT_DIR}/{MANIFEST_ID}.yaml"),
        format!("{OUT_DIR}/{MANIFEST_ID}.md"),
    ]
}

/// The index of every generated artifact: what each one projects, how it is encoded, what
/// contract it satisfies, where it came from, and its size and hash.
///
/// The manifest's own three files are listed with `describes_itself: true` and no hash:
/// a document that hashed itself would have no fixed point. Their staleness is not
/// unguarded — `generate --check` compares every artifact including these byte for byte,
/// which is a stronger statement than a hash the file makes about itself.
pub fn manifest_document(indexed: &[Artifact]) -> Value {
    let mut entries: Vec<Value> = indexed
        .iter()
        .map(|a| {
            let mut o = Map::new();
            o.insert("path".into(), Value::String(a.path.clone()));
            o.insert("document".into(), Value::String(a.document.clone()));
            o.insert(
                "format".into(),
                serde_json::to_value(a.format).unwrap_or(Value::Null),
            );
            if let Some(schema) = &a.schema {
                o.insert("schema".into(), Value::String(schema.clone()));
            }
            o.insert("source".into(), Value::String(a.source.clone()));
            o.insert("bytes".into(), Value::from(a.content.len()));
            o.insert("sha256".into(), Value::String(sha256_hex(&a.content)));
            Value::Object(o)
        })
        .collect();
    for path in manifest_paths() {
        let mut o = Map::new();
        o.insert("path".into(), Value::String(path.clone()));
        o.insert("document".into(), Value::String(MANIFEST_ID.into()));
        o.insert(
            "format".into(),
            serde_json::to_value(ArtifactFormat::of_path(&path)).unwrap_or(Value::Null),
        );
        if ArtifactFormat::of_path(&path) != ArtifactFormat::Markdown {
            o.insert("schema".into(), Value::String(MANIFEST_SCHEMA.into()));
        }
        o.insert("source".into(), Value::String(MANIFEST_SOURCE.into()));
        o.insert("describes_itself".into(), Value::Bool(true));
        entries.push(Value::Object(o));
    }
    entries.sort_by(|a, b| {
        a.get("path")
            .and_then(Value::as_str)
            .cmp(&b.get("path").and_then(Value::as_str))
    });

    // one row per document: the encodings it is committed in, which is the property a
    // reader and the enforcement rule actually ask about
    let mut documents: Vec<Value> = Vec::new();
    for entry in &entries {
        let id = entry.get("document").and_then(Value::as_str).unwrap_or("");
        let format = entry.get("format").cloned().unwrap_or(Value::Null);
        match documents
            .iter_mut()
            .find(|d| d.get("id").and_then(Value::as_str) == Some(id))
        {
            Some(Value::Object(d)) => {
                if let Some(Value::Array(formats)) = d.get_mut("formats") {
                    if !formats.contains(&format) {
                        formats.push(format);
                    }
                }
            }
            _ => {
                let mut d = Map::new();
                d.insert("id".into(), Value::String(id.to_string()));
                if let Some(schema) = entry.get("schema") {
                    d.insert("schema".into(), schema.clone());
                }
                d.insert(
                    "source".into(),
                    entry.get("source").cloned().unwrap_or(Value::Null),
                );
                d.insert("formats".into(), Value::Array(vec![format]));
                documents.push(Value::Object(d));
            }
        }
    }

    documents.sort_by(|a, b| {
        a.get("id")
            .and_then(Value::as_str)
            .cmp(&b.get("id").and_then(Value::as_str))
    });
    serde_json::json!({
        "documents": documents,
        "artifacts": entries,
    })
}

/// The manifest in its three encodings: JSON and YAML from the value, Markdown for a
/// reader. The Markdown is a rendering of the same value and holds nothing of its own.
pub fn manifest_artifacts(document: &Value, version: &str) -> Vec<Artifact> {
    let doc = Document::new(
        MANIFEST_ID,
        MANIFEST_SCHEMA,
        MANIFEST_SOURCE,
        document.clone(),
    );
    let mut out = doc.artifacts(version);
    out.push(Artifact::markdown(
        format!("{OUT_DIR}/{MANIFEST_ID}.md"),
        MANIFEST_ID,
        MANIFEST_SOURCE,
        version,
        &manifest_reference(document),
    ));
    out
}

/// The manifest as a reader sees it: the documents with the encodings each is committed
/// in, then every file with its contract, size and hash.
fn manifest_reference(document: &Value) -> String {
    let mut s = String::new();
    s.push_str("# Generated artifacts\n\n");
    s.push_str("Every file `majordomus generate` writes, with the document it projects, the encoding it is written in, the JSON Schema its content satisfies, and where it came from. Nothing below is a list kept by hand: it is the generation plan, generated. A file under a path this table does not name is not generated by this repository, and a file this table names that differs from the plan is stale — `majordomus generate --check` says which, byte for byte.\n\n");
    s.push_str("## Documents\n\n| document | encodings | schema | source |\n|---|---|---|---|\n");
    for d in document
        .get("documents")
        .and_then(Value::as_array)
        .map(Vec::as_slice)
        .unwrap_or_default()
    {
        let formats: Vec<String> = d
            .get("formats")
            .and_then(Value::as_array)
            .map(|f| {
                f.iter()
                    .filter_map(Value::as_str)
                    .map(|s| format!("`{s}`"))
                    .collect()
            })
            .unwrap_or_default();
        s.push_str(&format!(
            "| `{}` | {} | {} | {} |\n",
            d.get("id").and_then(Value::as_str).unwrap_or(""),
            formats.join(", "),
            d.get("schema")
                .and_then(Value::as_str)
                .map(|x| format!("`{x}`"))
                .unwrap_or_else(|| "—".into()),
            d.get("source").and_then(Value::as_str).unwrap_or(""),
        ));
    }
    s.push_str(
        "\n## Files\n\n| path | document | format | bytes | sha256 |\n|---|---|---|---|---|\n",
    );
    for a in document
        .get("artifacts")
        .and_then(Value::as_array)
        .map(Vec::as_slice)
        .unwrap_or_default()
    {
        let hash = match a.get("sha256").and_then(Value::as_str) {
            Some(h) => format!("`{}`", &h[..16.min(h.len())]),
            // the manifest's own encodings: see `manifest_document`
            None => "— (this file)".to_string(),
        };
        s.push_str(&format!(
            "| `{}` | `{}` | {} | {} | {} |\n",
            a.get("path").and_then(Value::as_str).unwrap_or(""),
            a.get("document").and_then(Value::as_str).unwrap_or(""),
            a.get("format").and_then(Value::as_str).unwrap_or(""),
            a.get("bytes")
                .and_then(Value::as_u64)
                .map(|b| b.to_string())
                .unwrap_or_else(|| "—".into()),
            hash,
        ));
    }
    s
}

/// The shell tool's allow-lists, one per schema that carries `x-majordomus-allow`, under
/// the share directory: a repository-relative path when the share is inside the
/// repository, absolute otherwise.
pub fn allow_artifacts(
    schema: &KindSchema,
    share: &Share,
    root: &Path,
    version: &str,
) -> Vec<Artifact> {
    let dir = share.allow_dir();
    let dir = dir
        .strip_prefix(root)
        .map(|p| p.to_path_buf())
        .unwrap_or(dir);
    schema
        .schemas()
        .filter_map(|(name, sch)| {
            // A schema derived from a `.proto` is projected beside its source, not here;
            // emitting it twice would make the plan disagree with itself.
            if sch
                .json
                .get(crate::proto::project::DERIVED_EXTENSION)
                .is_some()
            {
                return None;
            }
            let list = sch.json.get(ALLOW_EXTENSION).and_then(Value::as_str)?;
            Some(Artifact::text(
                format!("{}/{list}.txt", dir.display()),
                format!("allow/{list}"),
                format!("the JSON Schema `{name}` of the kind it validates"),
                version,
                &(allow_lines(&sch.json).join("\n") + "\n"),
            ))
        })
        .collect()
}

/// The allow-list a JSON Schema derives: one anchored pattern per key path the schema
/// allows, in the schema's order, as the shell tool's `mj_yaml_unknown_keys` reads them
/// (`grep -E -f`). A list of scalars is `name(\.[0-9]+)?`, a list of objects recurses
/// through `name\.[0-9]+\.`, a nested object through `name\.`. Local `$ref`s into
/// `$defs` are followed. No blank lines and no comments: every line is a pattern.
///
/// ```
/// use majordomus_cli::generate::allow_lines;
/// use serde_json::json;
/// let schema = json!({ "type": "object", "properties": {
///     "id": { "type": "string" },
///     "tags": { "type": "array", "items": { "type": "string" } },
///     "x-majordomus": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "string" } } } }
/// } });
/// assert_eq!(allow_lines(&schema), [
///     "^id$",
///     "^tags(\\.[0-9]+)?$",
///     "^x-majordomus\\.tests(\\.[0-9]+)?$",
/// ]);
/// ```
pub fn allow_lines(schema: &Value) -> Vec<String> {
    let mut out = Vec::new();
    // A whole-document schema describes the front matter under `header` and the Markdown
    // body under `body`; the allow-list is the front matter's keys, because that is what
    // the shell tool reads a file's front matter against. A schema with no `header`
    // describes the metadata directly, as every YAML kind's does.
    let start = schema
        .get("properties")
        .and_then(|p| p.get("header"))
        .unwrap_or(schema);
    walk_allow(schema, start, "", &mut out);
    out
}

fn resolve<'a>(root: &'a Value, node: &'a Value) -> &'a Value {
    match node
        .get("$ref")
        .and_then(Value::as_str)
        .and_then(|r| r.strip_prefix("#/"))
    {
        Some(pointer) => pointer.split('/').fold(root, |v, seg| &v[seg]),
        None => node,
    }
}

fn escape(key: &str) -> String {
    let mut s = String::with_capacity(key.len());
    for c in key.chars() {
        if ".+*?()[]{}^$|\\".contains(c) {
            s.push('\\');
        }
        s.push(c);
    }
    s
}

fn walk_allow(root: &Value, node: &Value, prefix: &str, out: &mut Vec<String>) {
    let node = resolve(root, node);
    let Some(props) = node.get("properties").and_then(Value::as_object) else {
        return;
    };
    for (key, prop) in props {
        let prop = resolve(root, prop);
        let path = format!("{prefix}{}", escape(key));
        let is_object = prop.get("properties").is_some();
        let items = prop.get("items").map(|i| resolve(root, i));
        if is_object {
            walk_allow(root, prop, &format!("{path}\\."), out);
        } else if let Some(items) = items {
            if items.get("properties").is_some() {
                walk_allow(root, items, &format!("{path}\\.[0-9]+\\."), out);
            } else {
                out.push(format!("^{path}(\\.[0-9]+)?$"));
            }
        } else {
            out.push(format!("^{path}$"));
        }
    }
}

// ---------------------------------------------------------------- the contract

/// The contracts of the generated documents, read from `share/schemas/generated/`, keyed
/// by the schema id each one pins through the `const` of its `schema` member. A document
/// says which contract it satisfies; nothing here maps a file name to a file name.
pub struct GeneratedSchemas {
    by_id: std::collections::BTreeMap<String, (String, jsonschema::Validator)>,
}

impl std::fmt::Debug for GeneratedSchemas {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("GeneratedSchemas")
            .field("documents", &self.by_id.keys().collect::<Vec<_>>())
            .finish()
    }
}

impl GeneratedSchemas {
    /// Load every schema in the directory. A file that pins no schema id is a schema for
    /// nothing and is refused, because it would silently validate no document.
    pub fn load(dir: &Path) -> Result<GeneratedSchemas> {
        let mut by_id = std::collections::BTreeMap::new();
        for (name, json) in crate::share::read_generated_schema_dir(dir)? {
            let id = json
                .pointer("/properties/schema/const")
                .and_then(Value::as_str)
                .ok_or_else(|| Error::KindSchema {
                    reason: format!(
                        "{}/{name}.schema.json pins no document: a schema of a generated document declares the id it validates as properties.schema.const",
                        dir.display()
                    ),
                })?
                .to_string();
            let validator = jsonschema::validator_for(&json).map_err(|e| Error::KindSchema {
                reason: format!("{}/{name}.schema.json: {e}", dir.display()),
            })?;
            if let Some((first, _)) = by_id.insert(id.clone(), (name.clone(), validator)) {
                return Err(Error::KindSchema {
                    reason: format!("schema id '{id}' is pinned by both {first} and {name}"),
                });
            }
        }
        Ok(GeneratedSchemas { by_id })
    }

    /// The schema ids that have a contract, sorted.
    pub fn ids(&self) -> impl Iterator<Item = &str> {
        self.by_id.keys().map(String::as_str)
    }

    /// Every reason `value` fails the contract of `schema_id`; empty when it passes or
    /// when no contract is published for that id.
    pub fn violations(&self, schema_id: &str, value: &Value) -> Vec<String> {
        let Some((_, validator)) = self.by_id.get(schema_id) else {
            return Vec::new();
        };
        validator
            .iter_errors(value)
            .map(|e| format!("{}: {e}", e.instance_path()))
            .collect()
    }
}

/// One thing wrong with a generated artifact, named by its path.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Violation {
    /// The artifact, repository-relative.
    pub path: String,
    /// What is wrong with it.
    pub reason: String,
}

impl std::fmt::Display for Violation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}: {}", self.path, self.reason)
    }
}

/// Does the content open with `banner`, allowing for a first line the format reserves?
///
/// Usually the banner is the first thing in the file. Two artifacts cannot put it there,
/// and neither is cutting a corner: an executable script must open with its `#!` line or
/// the kernel will not run it, and a Markdown page the site projects must open with its
/// own title, because the projection strips a document's first heading and a banner above
/// it would leave the page with none. Both carry the banner on the line after, which is
/// still the opening of the file and still impossible to miss. Anything further down is a
/// banner a reader scrolls past, and is refused.
pub fn opens_with_banner(content: &str, banner: &str) -> bool {
    if content.starts_with(banner) {
        return true;
    }
    let Some((first, rest)) = content.split_once('\n') else {
        return false;
    };
    let reserved = first.starts_with("#!") || first.starts_with("# ");
    reserved && rest.starts_with(banner)
}

/// Every way a plan can be wrong, checked before a byte is written.
///
/// Three properties, and they are the whole of the enforcement rule
/// `project.generated-artifacts-are-typed@1`:
///
/// 1. **Every artifact carries a provenance header** in the form its encoding allows —
///    members in JSON, a comment banner in YAML and text, an HTML comment in Markdown —
///    except the provider bootstraps, which stamp themselves with the policy hash they
///    were rendered from and are checked by `majordomus update` instead.
/// 2. **Every structured artifact parses**, and a document that declares a schema
///    satisfies the contract published for it under `share/schemas/generated/`.
/// 3. **The manifest is the plan**: exactly the artifacts of the plan, each with the
///    encoding, contract, size and hash it actually has.
pub fn violations(artifacts: &[Artifact], schemas: &GeneratedSchemas) -> Vec<Violation> {
    let mut out = Vec::new();
    let at = |path: &str, reason: String| Violation {
        path: path.to_string(),
        reason,
    };
    for a in artifacts {
        if a.format != ArtifactFormat::of_path(&a.path) {
            out.push(at(
                &a.path,
                format!(
                    "declares format {} and its suffix says {}",
                    a.format.suffix(),
                    ArtifactFormat::of_path(&a.path).suffix()
                ),
            ));
        }
        if a.source.trim().is_empty() {
            out.push(at(&a.path, "names no source".into()));
        }
        // the provider bootstraps carry the `majordomus update` stamp, not this banner:
        // a region projection owns part of a file it did not write, and a header at the
        // top of it would be a claim over text this generator does not own
        let stamped_elsewhere = a.document.starts_with("providers/");
        // an editor's file is read by the editor, whose format decides where the banner can
        // go: after the front matter of a skill, as `//` lines in JSONC (ADR 0140)
        if a.document.starts_with(crate::editors::DOCUMENT_PREFIX) {
            if !crate::editors::banner_is_present(&a.content) {
                out.push(at(&a.path, "carries no generated-file banner".into()));
            }
            if a.format == ArtifactFormat::Json {
                let body = crate::editors::jsonc_body(&a.content).unwrap_or(&a.content);
                if let Err(e) = serde_json::from_str::<Value>(body) {
                    out.push(at(&a.path, format!("is not JSON below its banner: {e}")));
                }
            }
            continue;
        }
        // the opening an encoding wraps the banner in: an HTML comment in Markdown, a `#`
        // comment in YAML and in line-oriented text, and nothing here for JSON, which
        // carries it as members and is checked below
        let opening = match a.format {
            ArtifactFormat::Markdown if !stamped_elsewhere => Some(format!("<!-- {HEADER}")),
            ArtifactFormat::Yaml => Some(format!("# {HEADER}")),
            ArtifactFormat::Text => Some(format!("{} {HEADER}", text_comment_opening(&a.path))),
            _ => None,
        };
        if opening.is_some_and(|o| !opens_with_banner(&a.content, &o)) {
            out.push(at(&a.path, "carries no generated-file banner".into()));
        }
        if a.format == ArtifactFormat::Json {
            match serde_json::from_str::<Value>(&a.content) {
                Err(e) => out.push(at(&a.path, format!("is not JSON: {e}"))),
                Ok(value) => {
                    let banner = value
                        .get("generated")
                        .or_else(|| value.get("x-majordomus-generated"))
                        .and_then(Value::as_str);
                    match banner {
                        Some(b) if b.starts_with(HEADER) => {}
                        _ if stamped_elsewhere => {}
                        _ => out.push(at(
                            &a.path,
                            "carries no `generated` member saying it is generated".into(),
                        )),
                    }
                    if let Some(schema) = &a.schema {
                        let declared = value.get("schema").and_then(Value::as_str);
                        if declared.is_some() && declared != Some(schema.as_str()) {
                            out.push(at(
                                &a.path,
                                format!(
                                    "declares schema '{schema}' and carries '{}'",
                                    declared.unwrap_or("")
                                ),
                            ));
                        }
                        for reason in schemas.violations(schema, &value) {
                            out.push(at(&a.path, format!("does not satisfy {schema} — {reason}")));
                        }
                    }
                }
            }
        }
    }

    // --- the manifest is the plan. Only when the plan holds the artifacts it indexes:
    // `generate manifest` writes the manifest alone, and its content was computed from the
    // whole plan inside `plan`, so there is nothing here to compare it against.
    let manifest = artifacts
        .iter()
        .find(|a| a.document == MANIFEST_ID && a.format == ArtifactFormat::Json)
        .filter(|_| artifacts.iter().any(|a| a.document != MANIFEST_ID));
    if let Some(manifest) = manifest {
        let listed: Vec<Value> = serde_json::from_str::<Value>(&manifest.content)
            .ok()
            .and_then(|v| v.get("artifacts").and_then(Value::as_array).cloned())
            .unwrap_or_default();
        let mut planned: Vec<&Artifact> = artifacts.iter().collect();
        planned.sort_by(|a, b| a.path.cmp(&b.path));
        if listed.len() != planned.len() {
            out.push(at(
                &manifest.path,
                format!(
                    "lists {} artifacts and the plan has {}",
                    listed.len(),
                    planned.len()
                ),
            ));
        }
        for entry in &listed {
            let path = entry
                .get("path")
                .and_then(Value::as_str)
                .unwrap_or_default();
            let Some(a) = artifacts.iter().find(|a| a.path == path) else {
                out.push(at(
                    &manifest.path,
                    format!("lists {path}, which is not planned"),
                ));
                continue;
            };
            if entry.get("describes_itself").is_some() {
                continue;
            }
            if entry.get("sha256").and_then(Value::as_str) != Some(sha256_hex(&a.content).as_str())
            {
                out.push(at(
                    &manifest.path,
                    format!("records a stale hash for {path}"),
                ));
            }
            if entry.get("bytes").and_then(Value::as_u64) != Some(a.content.len() as u64) {
                out.push(at(
                    &manifest.path,
                    format!("records a stale size for {path}"),
                ));
            }
        }
        for a in &planned {
            if !listed
                .iter()
                .any(|e| e.get("path").and_then(Value::as_str) == Some(a.path.as_str()))
            {
                out.push(at(&manifest.path, format!("does not list {}", a.path)));
            }
        }
    }
    out
}

/// [`violations`] as an error: nothing, or one `Stale` naming every one of them. This is
/// what `generate` and `generate --check` refuse on.
pub fn verify(artifacts: &[Artifact], schemas: &GeneratedSchemas) -> Result<()> {
    let violations = violations(artifacts, schemas);
    if violations.is_empty() {
        Ok(())
    } else {
        Err(Error::Stale {
            files: violations.iter().map(Violation::to_string).collect(),
        })
    }
}

/// Write every artifact under `root`, creating the directory. Returns every artifact's path.
///
/// A file whose bytes are already the artifact's is left alone, so its modification time
/// says when it last changed rather than when it was last generated; any other is written to
/// a temporary sibling and renamed over the target, so a reader never sees half a file and
/// an interrupted run leaves the old one intact.
pub fn write(root: &Path, artifacts: &[Artifact]) -> Result<Vec<PathBuf>> {
    let mut written = Vec::new();
    for a in artifacts {
        let path = root.join(&a.path);
        if std::fs::read(&path).is_ok_and(|on_disk| on_disk == a.content.as_bytes()) {
            written.push(path);
            continue;
        }
        if let Some(dir) = path.parent() {
            std::fs::create_dir_all(dir).map_err(|e| Error::io(dir, e))?;
        }
        let name = path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default();
        let staging = path.with_file_name(format!(".{name}.mj-tmp.{}", std::process::id()));
        std::fs::write(&staging, &a.content).map_err(|e| Error::io(&staging, e))?;
        if let Err(e) = std::fs::rename(&staging, &path) {
            let _ = std::fs::remove_file(&staging);
            return Err(Error::io(&path, e));
        }
        written.push(path);
    }
    Ok(written)
}

/// Compare every artifact with what is on disk under `root`; write nothing.
pub fn check(root: &Path, artifacts: &[Artifact]) -> Result<()> {
    let mut stale = Vec::new();
    for a in artifacts {
        let path = root.join(&a.path);
        match std::fs::read_to_string(&path) {
            Ok(on_disk) if on_disk == a.content => {}
            Ok(_) => stale.push(format!("{} (differs)", a.path)),
            Err(_) => stale.push(format!("{} (missing)", a.path)),
        }
    }
    if stale.is_empty() {
        Ok(())
    } else {
        Err(Error::Stale { files: stale })
    }
}

/// The capability reference's index: every module, every builtin capability with its
/// projections, and the declarative kinds by rule. Declarative objects are not enumerated
/// here because that inventory belongs to the repository's own state, changes with it, and
/// is answered live by `majordomus capabilities list`.
fn reference(registry: &CapabilityRegistry) -> String {
    let mut s = String::new();
    s.push_str("# Capability reference\n\n");
    s.push_str("Every capability this executable ships, as the registry holds it. MCP tools and resources, HTTP routes, the OpenAPI document (`openapi.json` beside this file, and `/openapi.json` when serving), Swagger UI, the command line's `capabilities` commands, the benchmark targets (`benchmarks.md`) and the registry manifest (`registry.json`) are projections of the same entries; nothing below is declared anywhere else.\n\n");
    s.push_str("## Modules\n\n| module | title | stability | capabilities | reference |\n|---|---|---|---|---|\n");
    for m in registry
        .modules()
        .filter(|m| m.source != ModuleSource::Declarative)
    {
        let stability = m
            .stability
            .and_then(|st| serde_json::to_value(st).ok())
            .and_then(|v| v.as_str().map(str::to_string))
            .unwrap_or_default();
        s.push_str(&format!(
            "| `{}` | {} | {} | {} | [`modules/{}.md`](modules/{}.md) |\n",
            m.id, m.title, stability, m.capabilities, m.id, m.id
        ));
    }
    s.push_str("\n## Executable capabilities\n\n");
    s.push_str("| id | module | kind | stability | MCP tool | MCP resource | HTTP | CLI | cache | benchmark |\n|---|---|---|---|---|---|---|---|---|---|\n");
    for c in registry
        .iter()
        .filter(|c| matches!(c.provenance, Provenance::Builtin { .. }))
    {
        s.push_str(&format!(
            "| `{}` | `{}` | {} | {} | {} | {} | {} | {} | {} | {} |\n",
            c.id,
            c.module,
            enum_name(c.kind),
            enum_name(c.stability),
            c.exposure
                .mcp
                .as_ref()
                .and_then(|m| m.tool.clone())
                .map(|t| format!("`{t}`"))
                .unwrap_or("—".into()),
            c.exposure
                .mcp
                .as_ref()
                .and_then(|m| m.resource.as_ref())
                .map(|r| format!("`{}`", r.uri))
                .unwrap_or("—".into()),
            c.exposure
                .http
                .as_ref()
                .map(|h| format!("`{} {}`", h.method.as_str(), h.path))
                .unwrap_or("—".into()),
            c.exposure
                .cli
                .as_ref()
                .map(|x| format!("`majordomus {}`", x.path.join(" ")))
                .unwrap_or("—".into()),
            cache_cell(c.cache),
            benchmark_cell(c.benchmark),
        ));
    }
    s.push_str("\n## Declarative resources\n\n");
    s.push_str("Every object of the repository's AI layer is a capability of kind `resource` with the id `<kind>.<identity>` (`rule.majordomus.scope-integrity@1`, `prompt.continue`, `document.docs/CLI.md`), exposed as the MCP resource `majordomus://<kind>/<identity>` and read over HTTP through `objects.get`; its module is its kind. They are not listed here: they are the repository's, not the executable's, and `majordomus capabilities list --kind resource` answers for the repository at hand. Kinds present in this repository at generation: ");
    let kinds: Vec<String> = registry
        .modules()
        .filter(|m| m.source == ModuleSource::Declarative)
        .map(|m| format!("`{}`", m.id))
        .collect();
    s.push_str(&if kinds.is_empty() {
        "none".to_string()
    } else {
        kinds.join(", ")
    });
    s.push_str(".\n\n## Infrastructure routes\n\n");
    s.push_str("The HTTP projection's own routes, not capabilities: ");
    s.push_str(
        &openapi::infrastructure_routes()
            .iter()
            .map(|r| format!("`{}`", r.path))
            .collect::<Vec<_>>()
            .join(", "),
    );
    s.push_str(
        ". `/swagger` is a Swagger UI shell that loads `/openapi.json`; it embeds no specification. `/docs/` is this repository's own documentation, and `/mcp` is MCP over HTTP on the shared server.\n",
    );
    let _ = CapabilityKind::Query; // the kind vocabulary is documented in docs/CAPABILITIES.md
    s
}

/// One module's reference: its metadata and each capability in full.
fn module_reference(registry: &CapabilityRegistry, module: &str) -> String {
    let mut s = String::new();
    if let Some(m) = registry.module(module) {
        s.push_str(&format!(
            "# Module `{}` — {}\n\n{}\n\n",
            m.id, m.title, m.description
        ));
        if let Some(st) = m.stability {
            s.push_str(&format!(
                "Stability: {}. Capabilities: {}.\n\n",
                enum_name(st),
                m.capabilities
            ));
        }
    }
    for c in registry.iter().filter(|c| {
        c.module.as_str() == module && matches!(c.provenance, Provenance::Builtin { .. })
    }) {
        s.push_str(&format!(
            "## `{}` — {}\n\n{}\n\n",
            c.id, c.title, c.description
        ));
        s.push_str("| | |\n|---|---|\n");
        s.push_str(&format!("| kind | {} |\n", enum_name(c.kind)));
        s.push_str(&format!("| stability | {} |\n", enum_name(c.stability)));
        if let Some(t) = c.exposure.mcp.as_ref().and_then(|m| m.tool.as_ref()) {
            s.push_str(&format!("| MCP tool | `{t}` |\n"));
        }
        if let Some(r) = c.exposure.mcp.as_ref().and_then(|m| m.resource.as_ref()) {
            s.push_str(&format!("| MCP resource | `{}` |\n", r.uri));
        }
        if let Some(h) = &c.exposure.http {
            s.push_str(&format!("| HTTP | `{} {}` |\n", h.method.as_str(), h.path));
        }
        if let Some(x) = &c.exposure.cli {
            s.push_str(&format!("| CLI | `majordomus {}` |\n", x.path.join(" ")));
        }
        s.push_str(&format!("| cache | {} |\n", cache_cell(c.cache)));
        s.push_str(&format!(
            "| benchmark | {} |\n",
            benchmark_cell(c.benchmark)
        ));
        s.push_str(&format!("| provenance | {} |\n", c.provenance));
        if !c.tags.is_empty() {
            s.push_str(&format!("| tags | {} |\n", c.tags.join(", ")));
        }
        s.push('\n');
        let (props, required) = c.input.properties();
        if props.is_empty() {
            s.push_str("Input: none.\n\n");
        } else {
            s.push_str("| input | type | required | description |\n|---|---|---|---|\n");
            for (name, schema) in props {
                let ty = match schema.get("type") {
                    Some(serde_json::Value::String(t)) => t.clone(),
                    Some(serde_json::Value::Array(a)) => a
                        .iter()
                        .filter_map(|v| v.as_str())
                        .collect::<Vec<_>>()
                        .join(" or "),
                    _ => schema
                        .get("$ref")
                        .and_then(|r| r.as_str())
                        .map(|r| r.rsplit('/').next().unwrap_or(r).to_string())
                        .unwrap_or("object".into()),
                };
                let desc = schema
                    .get("description")
                    .and_then(|d| d.as_str())
                    .unwrap_or("")
                    .replace('|', "\\|");
                s.push_str(&format!(
                    "| `{name}` | {ty} | {} | {desc} |\n",
                    if required.contains(&name) {
                        "yes"
                    } else {
                        "no"
                    }
                ));
            }
            s.push('\n');
        }
        s.push_str(&format!(
            "Output: `{}`.\n\n",
            c.output.name.as_deref().unwrap_or("object")
        ));
    }
    s
}

/// The native command line as Markdown: every command with its arguments, from the clap
/// declaration ([`crate::cli::tree`]). The site renders the same tree from the registry
/// dataset; neither is typed by hand.
pub fn cli_reference(tree: &crate::cli::CommandDoc) -> String {
    let mut s = String::new();
    s.push_str("# Command line of the Rust executable\n\n");
    s.push_str(&format!("{}\n\n", tree.about));
    if let Some(long) = &tree.long_about {
        s.push_str(&format!("{long}\n\n"));
    }
    s.push_str(&format!("Every command below is declared once, in [`{}`](../../{}), together with its examples; this file is a projection of that declaration, as `--help` is, as `docs/generated/cli.json` is, and as the website's reference under `{}/` is. Every example printed here is executed against the built executable by `apps/majordomus-cli/tests/cli_examples.rs`. The task lifecycle (`init`, `start`, `check`, `finish`, `doctor`, ...) is the *shell* tool `bin/majordomus`, a different program, documented in `docs/CLI.md`.\n\n", crate::cli::DECLARATION, crate::cli::DECLARATION, crate::cli::ROUTE_PREFIX));
    s.push_str("## Commands\n\n| command | route | does |\n|---|---|---|\n");
    for c in tree.flatten().into_iter().skip(1) {
        s.push_str(&format!(
            "| [`{}`](#{}) | `{}` | {} |\n",
            c.path.join(" "),
            c.path.join("-"),
            c.route,
            c.about
        ));
    }
    s.push('\n');
    for c in tree.flatten() {
        let name = c.path.join(" ");
        let anchor = c.path.join("-");
        s.push_str(&format!("<a id=\"{anchor}\"></a>\n## `{name}`\n\n"));
        if !c.subcommands.is_empty() || c.path.len() > 1 {
            s.push_str(&format!("{}\n\n", c.about));
        }
        if let (Some(long), true) = (&c.long_about, c.path.len() > 1) {
            s.push_str(&format!("{long}\n\n"));
        }
        if !c.subcommands.is_empty() {
            s.push_str("Subcommands: ");
            s.push_str(
                &c.subcommands
                    .iter()
                    .map(|sc| format!("[`{}`](#{})", sc.path.join(" "), sc.path.join("-")))
                    .collect::<Vec<_>>()
                    .join(", "),
            );
            s.push_str(".\n\n");
        }
        s.push_str(&format!("```text\n{}\n```\n\n", c.usage));
        if c.args.is_empty() {
            s.push_str("Arguments: none.\n\n");
        } else {
            s.push_str("| argument | value | default | description |\n|---|---|---|---|\n");
            for a in &c.args {
                let flag = match (&a.long, a.short, a.positional) {
                    (_, _, true) => format!(
                        "`<{}>`",
                        a.value_name.clone().unwrap_or(a.name.to_uppercase())
                    ),
                    (Some(l), Some(sh), _) => format!("`-{sh}`, `--{l}`"),
                    (Some(l), None, _) => format!("`--{l}`"),
                    (None, Some(sh), _) => format!("`-{sh}`"),
                    (None, None, _) => format!("`{}`", a.name),
                };
                let value = if !a.takes_value {
                    "flag".to_string()
                } else if !a.possible_values.is_empty() {
                    a.possible_values
                        .iter()
                        .map(|v| format!("`{}`", v.name))
                        .collect::<Vec<_>>()
                        .join(" \\| ")
                } else {
                    format!(
                        "`<{}>`",
                        a.value_name.clone().unwrap_or(a.name.to_uppercase())
                    )
                };
                let default = if a.defaults.is_empty() || !a.takes_value {
                    if a.required {
                        "required".to_string()
                    } else {
                        "—".to_string()
                    }
                } else {
                    a.defaults
                        .iter()
                        .map(|d| format!("`{d}`"))
                        .collect::<Vec<_>>()
                        .join(", ")
                };
                let mut help = a.help.replace('|', "\\|");
                if a.global {
                    help.push_str(" (accepted by every subcommand)");
                }
                let values: Vec<String> = a
                    .possible_values
                    .iter()
                    .filter_map(|v| {
                        v.help
                            .as_ref()
                            .map(|h| format!("`{}`: {}", v.name, h.replace('|', "\\|")))
                    })
                    .collect();
                if !values.is_empty() {
                    help.push_str(" — ");
                    help.push_str(&values.join("; "));
                }
                s.push_str(&format!("| {flag} | {value} | {default} | {help} |\n"));
            }
            s.push('\n');
        }
        s.push_str(&cli_examples(c));
    }
    s
}

/// The whole command line as the committed machine-readable projection,
/// `docs/generated/cli.json`: pretty JSON with a trailing newline, the same tree
/// `cli_reference` renders as Markdown. The website's generator reads this file and never
/// the Rust source.
pub fn cli_document(tree: &crate::cli::CommandDoc, version: &str) -> Value {
    serde_json::to_value(crate::cli::document(tree, version)).unwrap_or(Value::Null)
}

/// The examples of one command, as the reference prints them: the title, what it does, the
/// session a reader copies (the setup lines first, then the example itself), and what the
/// example test asserts about the run. Rendered from the same declaration the tests
/// execute, so nothing here can be true of the page and false of the executable.
fn cli_examples(c: &crate::cli::CommandDoc) -> String {
    let mut s = String::new();
    // A command that only groups others has none; a command a person can run cannot have
    // none, because `cli::validate` refuses to let one exist.
    if c.examples.is_empty() {
        return s;
    }
    s.push_str("Examples:\n\n");
    for e in &c.examples {
        s.push_str(&format!("- **{}** — {}\n\n", e.title, e.description));
        s.push_str("  ```console\n");
        for step in &e.setup {
            s.push_str(&format!("  $ {}\n", step.command));
        }
        s.push_str(&format!("  $ {}\n  ```\n\n", e.command));
        s.push_str(&format!("  Verified: {}.\n\n", e.expectation));
    }
    s
}

fn enum_name<T: serde::Serialize>(v: T) -> String {
    serde_json::to_value(v)
        .ok()
        .and_then(|v| v.as_str().map(str::to_string))
        .unwrap_or_default()
}

fn cache_cell(policy: crate::capability::CachePolicy) -> String {
    policy.summary()
}

fn benchmark_cell(policy: crate::capability::BenchmarkPolicy) -> String {
    match policy {
        crate::capability::BenchmarkPolicy::Required => "required".into(),
        crate::capability::BenchmarkPolicy::RequiredWhen { precondition } => {
            format!("required when {}", enum_name(precondition))
        }
        crate::capability::BenchmarkPolicy::Waived { reason } => {
            format!("waived ({})", enum_name(reason))
        }
    }
}

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

    /// A source that cannot be read is refused with its path, never compiled as empty.
    #[test]
    fn a_source_that_cannot_be_read_is_refused_with_its_path() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("icons.toml");
        let Err(Error::Io { path: named, .. }) = read_source(&path) else {
            panic!("a missing source was read");
        };
        assert_eq!(named, path);
        std::fs::write(&path, "[icons]\n").unwrap();
        assert_eq!(read_source(&path).unwrap(), "[icons]\n");
    }

    /// `docs/generated/web.json` is committed and `generate --check` compares it, so it
    /// may hold nothing that depends on which producers ran in the checkout that wrote it.
    /// The documentation and the rustdoc are the surfaces whose producers run in some
    /// checkouts and not others; each writes a declaration with the revision it was built
    /// from. The projection must be byte-identical with and without those declarations —
    /// and with two different revisions, which is two machines generating one commit.
    #[test]
    fn the_web_projection_is_the_same_whether_or_not_a_producer_ran() {
        use crate::web::discover::{self, Runtime};
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        let krate = root.join(crate::capability::model::CRATE_DIR);
        std::fs::create_dir_all(krate.join("src")).unwrap();
        std::fs::write(krate.join("Cargo.toml"), "").unwrap();
        std::fs::write(krate.join("src/lib.rs"), "//! x\n").unwrap();
        std::fs::create_dir_all(root.join("site")).unwrap();
        std::fs::write(root.join(discover::SITE_CONFIG), "base_url = \"/\"\n").unwrap();

        let projection = || {
            let topology = discover::discover(root, Runtime::full()).unwrap();
            serde_json::to_string_pretty(&web_document(&topology)).unwrap()
        };
        let produce = |revision: &str| {
            for (artifact, id, mount) in [
                (
                    discover::DOCS_ARTIFACT,
                    discover::DOCS,
                    discover::DOCS_MOUNT,
                ),
                (
                    discover::RUSTDOC_ARTIFACT,
                    discover::RUSTDOC,
                    discover::RUSTDOC_MOUNT,
                ),
            ] {
                let dir = root.join(artifact);
                std::fs::create_dir_all(&dir).unwrap();
                std::fs::write(dir.join("index.html"), "<h1>built</h1>").unwrap();
                std::fs::write(
                    dir.join(discover::DECLARATION_FILE),
                    json!({
                        "schema": discover::DECLARATION_SCHEMA, "id": id, "mount": mount,
                        "availability": "both", "built_from": revision,
                    })
                    .to_string(),
                )
                .unwrap();
            }
        };

        let unbuilt = projection();
        produce("1111111111111111111111111111111111111111");
        // the resolution does read the declarations: this is not equal because nothing
        // was looked at
        let topology = discover::discover(root, Runtime::full()).unwrap();
        for id in [discover::DOCS, discover::RUSTDOC] {
            assert_eq!(
                topology.get(id).and_then(|s| s.built_from.as_deref()),
                Some("1111111111111111111111111111111111111111"),
                "{id}"
            );
        }
        let built_here = projection();
        produce("2222222222222222222222222222222222222222");
        let built_elsewhere = projection();
        assert_eq!(
            unbuilt, built_here,
            "a producer running changed the projection"
        );
        assert_eq!(
            built_here, built_elsewhere,
            "a revision reached the projection"
        );
        assert!(!built_here.contains("built_from"), "{built_here}");
        assert!(!built_here.contains("1111111"), "{built_here}");

        // and the document holds both surfaces, so the equality is not two empty documents
        let doc: Value = serde_json::from_str(&built_here).unwrap();
        let ids: Vec<&str> = doc["surfaces"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|s| s["id"].as_str())
            .collect();
        assert!(ids.contains(&discover::DOCS), "{ids:?}");
        assert!(ids.contains(&discover::RUSTDOC), "{ids:?}");
        assert_eq!(doc["reserved"]["rustdoc"], discover::RUSTDOC_MOUNT);
    }

    /// The other producers that run in some checkouts and not others: the reports. A
    /// report is a surface only where its producer wrote it — the walk of the generated
    /// root finds it there and nowhere else — so a report reaching the committed file would
    /// make `generate --check` fail in exactly the checkout that ran the suite, and would
    /// hand the site build a published surface whose directory no other machine has. The
    /// declaration here is written by the reports' own `declare`, not by a fixture of it.
    #[test]
    fn a_report_on_disk_does_not_reach_the_web_projection() {
        use crate::web::discover::{self, Runtime};
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        std::fs::create_dir_all(root.join("site")).unwrap();
        std::fs::write(root.join(discover::SITE_CONFIG), "base_url = \"/\"\n").unwrap();
        let projection = || {
            let topology = discover::discover(root, Runtime::full()).unwrap();
            serde_json::to_string_pretty(&web_document(&topology)).unwrap()
        };

        let before = projection();
        crate::web::report::declare(root, "tests", "The test run", "scripts/test").unwrap();
        // the resolution holds the report — it is served and composed where it was built
        let topology = discover::discover(root, Runtime::full()).unwrap();
        assert!(topology.get("tests").is_some(), "the walk found the report");
        // and the committed projection does not, because only this checkout has it
        let after = projection();
        assert_eq!(
            before, after,
            "a report on disk reached the committed projection"
        );
        assert!(!after.contains("\"tests\""), "{after}");
        // and a count of the committed surfaces is the count of the projection, not of the
        // resolution: the report is served here and counted nowhere
        let committed = surfaces_every_checkout_has(&topology).count();
        let projected = serde_json::from_str::<Value>(&after).unwrap()["surfaces"]
            .as_array()
            .unwrap()
            .len();
        assert_eq!(committed, projected);
        assert_eq!(
            committed + 1,
            topology.surfaces.len(),
            "the report is in the resolution"
        );
    }

    /// A share directory inside the repository is named relative to it even when the root
    /// is spelled differently from the canonical path the share carries. `Share::open`
    /// canonicalises; the root does not, so the two spellings differ whenever a component
    /// is a symlink — and the banner then named the generator's own absolute path, making
    /// the artifact depend on the worktree it was generated in.
    #[test]
    #[cfg(unix)]
    fn a_share_inside_the_repository_is_named_relative_to_it() {
        let tmp = tempfile::tempdir().unwrap();
        let real = tmp.path().join("repository");
        std::fs::create_dir_all(real.join("share").join("schemas")).unwrap();

        let linked = tmp.path().join("by-another-name");
        std::os::unix::fs::symlink(&real, &linked).unwrap();

        // The share as `Share::open` hands it over: canonical. The root as it was
        // discovered: through the symlink.
        let schemas = real.join("share").join("schemas").canonicalize().unwrap();
        assert_eq!(relative_to(&schemas, &linked), "share/schemas");
        assert_eq!(relative_to(&schemas, &real), "share/schemas");
    }

    /// A share genuinely outside the repository keeps its absolute path — that is the
    /// documented behaviour and the only honest answer.
    #[test]
    fn a_share_outside_the_repository_keeps_its_absolute_path() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path().join("repository");
        let outside = tmp.path().join("elsewhere").join("share");
        std::fs::create_dir_all(&root).unwrap();
        std::fs::create_dir_all(&outside).unwrap();

        let named = relative_to(&outside, &root);
        assert!(
            Path::new(&named).is_absolute(),
            "a share outside the repository cannot be named relative to it: {named}"
        );
    }

    /// The manifest indexes every target but itself, and it is generated last. Three times
    /// a target was added to `ALL` and left out of the list beside it, which made that
    /// target's artifacts the only ones the index said nothing about. The set is derived
    /// now; this is what holds the order.
    #[test]
    fn every_target_but_the_manifest_is_indexed_and_the_manifest_is_last() {
        assert_eq!(
            Target::ALL.last(),
            Some(&Target::Manifest),
            "the manifest indexes the others, so it is generated after them"
        );
        assert!(
            !Target::indexed().contains(&Target::Manifest),
            "the manifest does not index itself"
        );
        assert_eq!(
            Target::indexed(),
            Target::ALL[..Target::ALL.len() - 1].to_vec(),
            "the indexed targets are ALL up to the manifest, in generation order"
        );
    }

    /// Every target has a name and every name is distinct: the manifest and the command
    /// line both address a target by it.
    #[test]
    fn every_target_is_named_once() {
        let names: Vec<&str> = Target::ALL.iter().map(|t| t.name()).collect();
        let mut unique = names.clone();
        unique.sort_unstable();
        unique.dedup();
        assert_eq!(names.len(), unique.len(), "{names:?}");
        assert!(names.iter().all(|n| !n.is_empty()));
        assert_eq!(Target::Manifest.name(), "manifest");
        assert_eq!(Target::indexed().len(), Target::ALL.len() - 1);
    }

    /// The encoding is read from the suffix, and anything the generator does not encode
    /// structurally is line-oriented text — the shell tool's allow-lists are the case.
    #[test]
    fn the_suffix_names_the_encoding() {
        for (path, format) in [
            ("docs/generated/registry.json", ArtifactFormat::Json),
            ("docs/generated/registry.yaml", ArtifactFormat::Yaml),
            ("a/b.yml", ArtifactFormat::Yaml),
            ("docs/generated/cli.md", ArtifactFormat::Markdown),
            ("share/allow/rule.txt", ArtifactFormat::Text),
            ("AGENTS", ArtifactFormat::Text),
            ("weird.suffix", ArtifactFormat::Text),
        ] {
            assert_eq!(ArtifactFormat::of_path(path), format, "{path}");
        }
        assert_eq!(ArtifactFormat::Json.suffix(), "json");
        assert_eq!(ArtifactFormat::Markdown.suffix(), "md");
        assert_eq!(ArtifactFormat::Text.suffix(), "txt");
        assert_eq!(ArtifactFormat::Yaml.suffix(), "yaml");
    }

    /// A document whose value is not a mapping has nowhere to put members, so it is
    /// written as it stands rather than silently wrapped.
    #[test]
    fn a_value_that_is_not_a_mapping_carries_no_members() {
        let doc = Document::new("fixture", "x/v1", "a test", json!([1, 2, 3]));
        assert_eq!(doc.stamped("test"), json!([1, 2, 3]));
        let arts = doc.artifacts("test");
        // the YAML encoding still carries the banner, which is a comment and not a member
        assert!(arts[1].content.starts_with(&format!("# {HEADER}")));
        assert!(arts[1].content.contains("\n- 1\n"));
    }

    /// The banner says the same three things in every encoding, and the JSON one names
    /// the command that rewrites the file.
    #[test]
    fn the_banner_is_one_text_in_three_wrappings() {
        let [a, b, c] = banner_lines("nowhere", "9.9.9");
        assert_eq!(a, HEADER);
        assert!(b.starts_with("Source: nowhere;") && b.contains(REGENERATE));
        assert_eq!(c, "Generator: majordomus-cli 9.9.9");
        assert_eq!(
            markdown_banner("nowhere", "9.9.9"),
            format!("<!-- {a}\n     {b}\n     {c} -->\n")
        );
        assert_eq!(
            comment_banner("nowhere", "9.9.9"),
            format!("# {a}\n# {b}\n# {c}\n")
        );
        assert!(json_banner("nowhere").starts_with(HEADER));
        assert!(json_banner("nowhere").contains(REGENERATE));
    }

    /// A schema id nothing publishes is not a failure: the document simply has no
    /// contract, and saying so is not the same as inventing one.
    #[test]
    fn an_unpublished_schema_id_validates_nothing_and_the_set_names_what_it_holds() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("thing.schema.json"),
            r#"{"type":"object","properties":{"schema":{"const":"x/v1"}},"required":["schema"]}"#,
        )
        .unwrap();
        let schemas = GeneratedSchemas::load(dir.path()).unwrap();
        assert_eq!(schemas.ids().collect::<Vec<_>>(), ["x/v1"]);
        assert!(format!("{schemas:?}").contains("x/v1"));
        assert_eq!(
            schemas.violations("nobody/v1", &json!({})),
            Vec::<String>::new()
        );
        assert!(!schemas.violations("x/v1", &json!({})).is_empty());
        assert_eq!(
            schemas.violations("x/v1", &json!({ "schema": "x/v1" })),
            Vec::<String>::new()
        );
    }

    /// Two schemas pinning one document would make the contract of that document
    /// ambiguous, so loading refuses rather than picking one.
    #[test]
    fn two_contracts_for_one_document_are_refused() {
        let dir = tempfile::tempdir().unwrap();
        let body = r#"{"type":"object","properties":{"schema":{"const":"x/v1"}}}"#;
        std::fs::write(dir.path().join("one.schema.json"), body).unwrap();
        std::fs::write(dir.path().join("two.schema.json"), body).unwrap();
        let err = GeneratedSchemas::load(dir.path()).unwrap_err().to_string();
        assert!(err.contains("x/v1") && err.contains("both"), "{err}");
    }

    /// A violation prints as the artifact it is about, then the reason: the one line the
    /// command shows.
    #[test]
    fn a_violation_names_the_artifact_first() {
        let v = Violation {
            path: "docs/generated/x.md".into(),
            reason: "carries no generated-file banner".into(),
        };
        assert_eq!(
            v.to_string(),
            "docs/generated/x.md: carries no generated-file banner"
        );
    }

    /// The manifest of an empty plan still describes itself, in every encoding it is
    /// committed in, and none of its own three carries a hash.
    #[test]
    fn the_manifest_of_nothing_is_still_the_manifest() {
        let doc = manifest_document(&[]);
        let entries = doc["artifacts"].as_array().unwrap();
        assert_eq!(entries.len(), 3);
        assert!(entries.iter().all(|e| e["describes_itself"] == true));
        assert!(entries.iter().all(|e| e.get("sha256").is_none()));
        let arts = manifest_artifacts(&doc, "test");
        assert_eq!(
            arts.iter().map(|a| a.path.as_str()).collect::<Vec<_>>(),
            manifest_paths()
        );
        assert!(arts[2].content.contains("— (this file)"));
        // and with nothing but itself in the plan, the verifier has nothing to compare
        let dir = tempfile::tempdir().unwrap();
        let schemas = GeneratedSchemas::load(dir.path()).unwrap();
        let manifest_only = violations(&arts, &schemas);
        assert!(
            !manifest_only
                .iter()
                .any(|v| v.reason.contains("does not list")),
            "{manifest_only:?}"
        );
    }

    #[test]
    fn the_graph_is_a_target_of_the_one_plan_and_not_a_script_of_its_own() {
        assert!(Target::ALL.contains(&Target::Graph));
    }

    #[test]
    fn a_published_artifact_is_refused_when_it_carries_a_machine_path_or_a_credential() {
        // every marker is something no derivation of this repository can legitimately
        // produce, so a hit is a defect rather than a judgement call; the home directory
        // is joined at run time because this file is committed and the gate reads it too
        for (content, marker) in [
            (
                format!("\"source\": \"{}someone/dev/x\"", "/Users/"),
                "/Users/",
            ),
            ("\"source\": \"/home/someone/x\"".to_string(), "/home/"),
            ("-----BEGIN PRIVATE KEY-----".to_string(), "-----BEGIN "),
            ("Authorization: Bearer abc".to_string(), "Authorization:"),
            ("AKIAIOSFODNN7EXAMPLE".to_string(), "AKIA"),
            ("ghp_0123456789".to_string(), "ghp_"),
        ] {
            assert_eq!(
                forbidden_in(&content).map(|(m, _)| m),
                Some(marker),
                "{content}"
            );
        }
    }

    #[test]
    fn a_composed_graph_that_stopped_at_a_bound_is_refused_and_not_committed() {
        use crate::graph::{Builder, Node};
        let thing = |id: &str| Node {
            id: id.into(),
            kind: "thing".into(),
            label: id.into(),
            summary: None,
            route: None,
            source: None,
            status: None,
            external: false,
            facts: Default::default(),
        };
        let mut b = Builder::new("composed", "Everything", "two things, room for one", "test")
            .node_kind("thing", "a thing")
            .limit(1);
        b.node(thing("a"));
        b.node(thing("b"));
        let err = committed_graph(b.finish()).expect_err("a prefix is not committed");
        assert_eq!(err.exit_code(), 10);
        let message = err.to_string();
        assert!(message.contains("stopped at 1 nodes"), "{message}");
        assert!(
            message.contains(&crate::graph::MAX_NODES.to_string()),
            "{message}"
        );

        let mut whole = Builder::new("composed", "Everything", "one thing", "test")
            .node_kind("thing", "a thing");
        whole.node(thing("a"));
        assert!(
            committed_graph(whole.finish()).is_ok(),
            "a graph that stopped nowhere is committed"
        );
    }

    #[test]
    fn a_graph_of_repository_relative_sources_is_publishable() {
        let safe = r#"{"nodes":[{"id":"majordomus://rule/a","source":".ai/repo/rules/a.md"}]}"#;
        assert!(forbidden_in(safe).is_none());
    }

    #[test]
    fn the_schema_of_the_graph_comes_from_the_types_that_define_it() {
        let doc = graph_schema_document("test");
        let parsed: Value = serde_json::from_str(&doc).expect("the schema is JSON");
        assert_eq!(parsed["$id"], Value::String(GRAPH_SCHEMA.into()));
        // the shape is schemars' rendering of `graph::Graph`, not a hand-written copy:
        // the fields it names are the struct's own
        let graph = &parsed["definitions"]["Graph"]["properties"];
        for field in [
            "id",
            "nodes",
            "edges",
            "node_kinds",
            "edge_kinds",
            "metadata",
        ] {
            assert!(graph.get(field).is_some(), "the schema names `{field}`");
        }
        assert!(
            parsed["description"]
                .as_str()
                .unwrap_or_default()
                .contains(HEADER),
            "JSON carries its provenance as a field, having no comment to carry it in"
        );
    }

    /// An editor reads these files, so their banner sits where the editor's format allows;
    /// the contract still refuses one without it, and one whose JSON is broken below it.
    #[test]
    fn an_editor_artifact_without_its_banner_or_with_broken_json_is_refused() {
        let dir = tempfile::tempdir().unwrap();
        let schemas = GeneratedSchemas::load(dir.path()).unwrap();
        let json = |content: &str| {
            Artifact::verbatim(
                ".zed/tasks.json",
                "editors/zed-tasks",
                ArtifactFormat::Json,
                None,
                "the justfile",
                content.to_string(),
            )
        };
        let reasons = |a: Artifact| -> Vec<String> {
            violations(&[a], &schemas)
                .into_iter()
                .map(|v| v.reason)
                .collect()
        };
        assert_eq!(reasons(json("[1]\n")), ["carries no generated-file banner"]);
        let banner = crate::editors::jsonc_banner("the justfile", "0.0.0");
        assert!(reasons(json(&format!("{banner}[1]\n"))).is_empty());
        let broken = reasons(json(&format!("{banner}[1,\n")));
        assert_eq!(broken.len(), 1, "{broken:?}");
        assert!(
            broken[0].starts_with("is not JSON below its banner"),
            "{broken:?}"
        );
    }

    /// A write that cannot land leaves the old file and no staging file behind.
    #[test]
    fn a_write_that_cannot_land_leaves_nothing_half_written() {
        let dir = tempfile::tempdir().unwrap();
        // a non-empty directory sits where the file should go: the rename cannot replace it
        std::fs::create_dir_all(dir.path().join("out/file.txt/inside")).unwrap();
        let a = Artifact::verbatim(
            "out/file.txt",
            "doc",
            ArtifactFormat::Text,
            None,
            "s",
            "x\n".into(),
        );
        assert!(write(dir.path(), &[a]).is_err());
        let left: Vec<String> = std::fs::read_dir(dir.path().join("out"))
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .collect();
        assert_eq!(left, ["file.txt"], "no staging file remains");

        // a directory nothing can be written into refuses at the staging file
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let locked = dir.path().join("locked");
            std::fs::create_dir_all(&locked).unwrap();
            std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o555)).unwrap();
            let c = Artifact::verbatim(
                "locked/new.txt",
                "doc",
                ArtifactFormat::Text,
                None,
                "s",
                "x\n".into(),
            );
            // root writes anywhere; where that is so there is nothing to observe
            if std::fs::write(locked.join("probe"), "x").is_err() {
                assert!(write(dir.path(), &[c]).is_err());
            }
            std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o755)).unwrap();
        }

        // and an unchanged file is not rewritten
        let b = Artifact::verbatim(
            "kept.txt",
            "doc",
            ArtifactFormat::Text,
            None,
            "s",
            "same\n".into(),
        );
        write(dir.path(), std::slice::from_ref(&b)).unwrap();
        let before = std::fs::metadata(dir.path().join("kept.txt"))
            .unwrap()
            .modified()
            .unwrap();
        write(dir.path(), std::slice::from_ref(&b)).unwrap();
        let after = std::fs::metadata(dir.path().join("kept.txt"))
            .unwrap()
            .modified()
            .unwrap();
        assert_eq!(before, after);
    }

    /// A repository holding one release record and none of its history, as an exported
    /// fixture does: its index, and the app that plans over it.
    fn released_without_history() -> (crate::synthetic::SyntheticRepository, crate::cli::RepoArgs) {
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let sources = repo.root().join(".ai/repo/knowledge/sources.yaml");
        let mut text = std::fs::read_to_string(&sources).unwrap();
        text.push_str(
            "  - id: release\n    kind: release-record\n    discovery: vcs\n    \
             pathspec: ':(glob).ai/repo/releases/*.yaml'\n    required: false\n",
        );
        std::fs::write(&sources, text).unwrap();
        let manifest = repo.root().join(".ai/manifest.yaml");
        let mut text = std::fs::read_to_string(&manifest).unwrap();
        text.push_str("  releases: repo/releases\n");
        std::fs::write(&manifest, text).unwrap();
        let releases = repo.root().join(".ai/repo/releases");
        std::fs::create_dir_all(&releases).unwrap();
        std::fs::write(
            releases.join("v1.0.0.yaml"),
            "schema: release/v1\nversion: \"1.0.0\"\ntag: v1.0.0\nchannel: stable\n\
             commit: 1111111111111111111111111111111111111111\n\
             published_at: \"2026-10-01T00:00:00Z\"\nartifacts:\n  - target: linux-x86_64-gnu\n    \
             name: majordomus-v1.0.0-x86_64-unknown-linux-gnu.tar.gz\n    \
             url: https://github.com/example/synthetic/releases/download/v1.0.0/\
             majordomus-v1.0.0-x86_64-unknown-linux-gnu.tar.gz\n    \
             sha256: 3333333333333333333333333333333333333333333333333333333333333333\n    \
             size: 1\n",
        )
        .unwrap();
        let args = crate::cli::RepoArgs {
            repo: Some(repo.root().to_path_buf()),
            share: Some(crate::synthetic::crate_share()),
            discovery: crate::cli::DiscoveryMode::Filesystem,
            ..Default::default()
        };
        (repo, args)
    }

    fn planned_changelog(args: &crate::cli::RepoArgs) -> crate::release::model::Changelog {
        let app = crate::app::App::load(args).unwrap();
        let plan = plan(&app, &[Target::Changelog]).unwrap();
        let json = plan
            .iter()
            .find(|a| a.path == format!("{OUT_DIR}/changelog.json"))
            .expect("the changelog is planned");
        serde_json::from_str(&json.content).unwrap()
    }

    /// A release whose history is not in the repository keeps what the committed changelog
    /// says it changed; with nothing committed, or with a committed changelog that cannot
    /// be read, there is nothing to keep and the composed section stands as composed.
    #[test]
    fn a_release_without_its_history_keeps_what_the_committed_changelog_says() {
        use crate::release::model::{Change, ChangeGroup, ChangeKind};
        let (repo, args) = released_without_history();
        let app = crate::app::App::load(&args).unwrap();
        assert!(
            app.context
                .index
                .objects
                .iter()
                .any(|o| o.kind == crate::release::changelog::RELEASE_KIND),
            "the fixture's release record is indexed: {:?}",
            app.context.index.diagnostics
        );
        assert_eq!(
            crate::release::changelog::unreadable_releases(
                app.repository.root(),
                &app.context.index.objects
            ),
            ["1.0.0"],
            "the fixture's release must be one whose history is absent"
        );

        // nothing committed: the section is composed from the history it does not have
        let composed = planned_changelog(&args);
        let section = composed
            .sections
            .iter()
            .find(|s| s.version == "1.0.0")
            .expect("the release has a section");
        assert!(section.groups.is_empty(), "{section:?}");

        // a committed changelog that does not parse is not a source of anything
        let out = repo.root().join(OUT_DIR);
        std::fs::create_dir_all(&out).unwrap();
        std::fs::write(out.join("changelog.json"), "{ not json").unwrap();
        let unparsed = planned_changelog(&args);
        assert_eq!(unparsed.sections, composed.sections);

        // a committed changelog naming the same release at the same commit is kept
        let mut committed = composed.clone();
        let kept = Change {
            kind: ChangeKind::Fix,
            scope: None,
            subject: "what the committed changelog said".into(),
            breaking: false,
            commit: "2222222222222222222222222222222222222222".into(),
            url: None,
            references: Vec::new(),
        };
        for s in committed
            .sections
            .iter_mut()
            .filter(|s| s.version == "1.0.0")
        {
            s.groups = vec![ChangeGroup {
                kind: ChangeKind::Fix,
                heading: "Fixed".into(),
                rank: 1,
                changes: vec![kept.clone()],
            }];
        }
        std::fs::write(
            out.join("changelog.json"),
            serde_json::to_string(&committed).unwrap(),
        )
        .unwrap();
        // the warning that names what is kept is formatted only where a subscriber listens
        // at warn, so the plan is made under one: its count and its range are executed
        let subscriber = tracing_subscriber::fmt()
            .with_max_level(tracing::Level::WARN)
            .with_writer(std::io::sink)
            .finish();
        let planned = tracing::subscriber::with_default(subscriber, || planned_changelog(&args));
        let section = planned
            .sections
            .iter()
            .find(|s| s.version == "1.0.0")
            .unwrap();
        assert_eq!(section.groups.len(), 1, "{section:?}");
        assert_eq!(section.groups[0].changes, [kept]);
    }

    /// The composed graph of a repository whose every reference resolves is the committed
    /// document: its schema, its generator, and the graph composed whole.
    #[test]
    fn the_graph_document_of_a_whole_repository_is_committed() {
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let ctx = repo.context().unwrap();
        let rendered = graph_document(&ctx, "9.9.9").unwrap();
        let doc: serde_json::Value = serde_json::from_str(&rendered).unwrap();
        assert_eq!(doc["schema"], GRAPH_SCHEMA);
        assert_eq!(doc["generator"], "majordomus-cli 9.9.9");
        assert_eq!(doc["graph"]["metadata"]["truncated"], false);
        let nodes = doc["graph"]["nodes"].as_array().expect("graph nodes");
        assert!(
            nodes
                .iter()
                .any(|n| n["id"].as_str() == Some("capability:worktree.status")),
            "the registry is composed into the graph"
        );
    }

    /// A composition that stopped at a bound is refused, and nothing is rendered: committing
    /// it would publish a prefix of the repository that still reads as whole (I1966).
    #[test]
    fn a_graph_that_stopped_at_a_bound_is_not_committed() {
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let ctx = repo.context().unwrap();
        let mut composed = crate::graph::composed_complete(&ctx.registry, &ctx.index);
        composed.metadata.truncated = true;
        match graph_document_of(&ctx, "9.9.9", composed) {
            Err(Error::Refused { code, reason }) => {
                assert_eq!(code, 10);
                assert!(reason.contains("stopped at"), "{reason}");
            }
            other => panic!("{other:?}"),
        }
    }
}