# Public API — `mgf-standard`

> ⚠️ **This file documents `main` HEAD.** Names listed here may be
> unreleased. To learn what your installed wheel actually ships, run
> `pip show mgf-standard` and compare against the `__version__` field at
> the top of [`PUBLIC_API.json`](PUBLIC_API.json). The git tag matching
> the published version is authoritative; this file's tip can be ahead of
> it during a release window.

This document is the **contract list** for `mgf-standard` (rule
**AP-10**). Every name listed below is a public name that consumers MAY
depend on. The contract terms are defined in
[`docs/standards/API_DESIGN.md`](docs/standards/API_DESIGN.md). In short:

- **Stability tiers** (rule **AP-11**):
  - `experimental` — MAY change shape in any MINOR release.
  - `stable` — follows the deprecation cycle; removal only in MAJOR.
  - `deprecated` — slated for removal; emits `DeprecationWarning`.
- **Names not listed below are private.** Anything starting with `_`
  (e.g. `_docs_data_dir`, `_load_registry`) is internal and MAY change
  without notice (rule **AP-14**).
- **The 0.x window applies.** Per [SemVer](https://semver.org/) 0.x
  semantics, MINOR releases MAY break the public API (rule **AP-03**).
  Pin tightly: `mgf-standard = ">=0.1,<0.2"`.

This file MUST stay in sync with the package's `__all__` and with
[`PUBLIC_API.json`](PUBLIC_API.json); the pin is enforced by
[`tests/unit/test_public_api_doc.py`](tests/unit/test_public_api_doc.py)
(the rule **AP-10** sync test).

---

## `mgf.standard`

The federation's zero-dependency standards-corpus accessor: resolve the
engineering standards, recipes, design papers, the federation contract,
and the library registry from the version a consumer pins — without
vendoring or path-hacking. Thirteen names.

| Name | Tier | Description |
|---|---|---|
| `__version__: str` | **stable** | Package version string. Mirrors `pyproject.toml::project.version` (rule **AP-13**); enforced by the CI `tag-coherence` step + `test_federation_design.py::TestVersionCoherence`. |
| `standards_dir() -> Path` | **stable** | The directory holding the engineering-standards docs. Resolves wheel-shipped data (`mgf/standard/_standards/`) first, then the editable-install repo path `docs/standards/`. Raises `FileNotFoundError` if neither resolves. |
| `list_standards() -> list[str]` | **stable** | The canonical standards topic names (Markdown file stems), sorted — e.g. `LOGGING`, `ERROR_HANDLING`. |
| `read_standard(name: str) -> str` | **stable** | The full UTF-8 text of one standards doc by file stem. Raises `FileNotFoundError` (listing available topics) if `name` is unknown. |
| `recipes_dir() -> Path` | **stable** | The directory holding the federation-operations recipes + governance templates (the `/sync` prompt, cohort-release, sibling-rename, per-repo doc templates). Same wheel-then-editable resolution as `standards_dir`. |
| `list_recipes() -> list[str]` | **stable** | The recipe names (Markdown file stems), sorted. |
| `read_recipe(name: str) -> str` | **stable** | The full UTF-8 text of one recipe by file stem. Raises `FileNotFoundError` (listing available recipes) if `name` is unknown. |
| `design_dir() -> Path` | **stable** | The directory holding the foundation design papers (`docs/design/`, e.g. the federation-pattern paper). Same wheel-then-editable resolution. |
| `list_design() -> list[str]` | **stable** | The design-paper names (Markdown file stems), sorted. |
| `read_design(name: str) -> str` | **stable** | The full UTF-8 text of one design paper by file stem. Raises `FileNotFoundError` (listing available papers) if `name` is unknown. |
| `federation() -> str` | **stable** | The full UTF-8 text of the federation contract (`FEDERATION.md`, DOC-17) — the canonical duties, conformance levels, and federation-first principle. |
| `libraries() -> list[dict[str, Any]]` | **stable** | The federation library registry — one record per `mgf-*` member (`repo`, `lang`, `version`, `requires_python`, `deps`, `used_by`, `extras`, `third_party_count`, `purpose`), sorted by repo name. |
| `release_waves() -> list[list[str]]` | **stable** | The dependency-ordered release waves (roots → leaves) — the invariant walk order for any cross-federation update. Empty if the registry predates the field. |
| `list_scaffold() -> list[str]` | **stable** | The canonical standardized-scaffold artifact names (the AG-03 `prepare-commit-msg` hook + the `check_commit_trailers.py` CI checker), sorted. |
| `read_scaffold(name: str) -> str` | **stable** | The full UTF-8 text of a canonical scaffold artifact by name — shipped as wheel data so a consumer (e.g. `mgf-fed catch-up`) writes the canonical text into a repo rather than a drift-prone copy. Raises `FileNotFoundError` for an unknown name. |
