Module generate 

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.

Structs

Artifact

One generated file: what it projects, how it is encoded, what contract its content satisfies, where it came from, and the whole file.

Document

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.

GeneratedSchemas

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.

Violation

One thing wrong with a generated artifact, named by its path.

Enums

ArtifactFormat

The encoding one generated artifact is written in.

HeaderStyle

Where a structured document puts its provenance.

Target

What can be generated.

Constants

ALLOW_EXTENSION

The schema extension that names the allow-list a schema derives.

BENCHMARKS_SCHEMA

The schema of benchmarks.json.

ECONOMICS_SCHEMA

The schema of economics.json: the token-economics summary.

GRAPH_SCHEMA

The schema of graph.json.

HEADER

The first thing every generated artifact says about itself, whatever its encoding wraps it in.

MANIFEST_ID

The document id of the manifest, and the file stem of its encodings.

MANIFEST_SCHEMA

The schema of artifacts.json, the manifest of every generated artifact.

MANIFEST_SOURCE

Where the manifest says it came from.

OUT_DIR

Where generated artifacts live, relative to the repository root.

PROVIDERS_SCHEMA

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.

REGENERATE

The command that rewrites any of them.

REGISTRY_SCHEMA

The schema of registry.json.

SITE_DATA_DIR

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.

WEB_SCHEMA

The schema of web.json.

Functions

allow_artifacts

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.

allow_lines

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 $refs into $defs are followed. No blank lines and no comments: every line is a pattern.

artifacts

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.

banner_lines

The three lines every provenance header says, whatever the encoding wraps them in.

benchmark_document

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.

benchmark_matrix

Every benchmark target and the coverage, from the projection of this repository.

check

Compare every artifact with what is on disk under root; write nothing.

cli_document

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.

cli_reference

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.

comment_banner

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.

context_artifacts

Every artifact of the selected targets, the benchmark matrix included: what majordomus generate writes and --check compares.

distribution_artifacts

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.

document_artifacts

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.

document_schemas

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.

forbidden_in

The first forbidden marker in content, with what it is, or None when the content is safe to publish.

graph_document

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.

graph_schema_document

The schema of the composed graph, generated from the types that define it rather than written beside them.

json_banner

The one line a JSON artifact carries under generated.

manifest_artifacts

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.

manifest_document

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.

manifest_paths

The three files the manifest is written to, in the order manifest_artifacts returns them.

markdown_banner

The provenance header of a Markdown artifact: an HTML comment, so it is invisible when rendered and unmissable in the file.

opens_with_banner

Does the content open with banner, allowing for a first line the format reserves?

plan

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.

proto_allow_artifacts

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.

providers_document

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.

providers_markdown

docs/generated/providers.md: the same value as a table a person reads, with the grammar of a scratch root beside it.

registry_manifest

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.

text_comment_opening

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.

verify

violations as an error: nothing, or one Stale naming every one of them. This is what generate and generate --check refuse on.

version_projection

The projection of the version the shell tool reads at start-up, share/version.txt.

violations

Every way a plan can be wrong, checked before a byte is written.

web_topology

The resolved web topology as data: every surface with its mount, category, visibility, kind, producer, artifact, runtime feature and provenance, in route-precedence order.

write

Write every artifact under root, creating the directory. Returns every artifact’s path.