--- title: "Use cases" description: "System models with executable checks: service catalogs, event contracts, access-control policies, and other aontu use cases." source: "https://aontu.dev/use-cases/" --- # Use cases Each use case defines a system such as a service catalog, an event registry, or an access-control model. Its `check.sh` runs the CLI and checks both expected output and expected refusals. Every page here is the case's own worked example, rendered from [`use-cases/`](https://github.com/aontu-lang/aontu/tree/main/use-cases/) in the engine repository, with the verbatim output of its checks. [The short version](https://aontu.dev/docs/use-cases) compresses all 18 into one page. 4 cases include Mermaid diagrams, such as entity graphs and ER diagrams. Other views include dependency matrices, trees, and architecture layers. `aontu view` generates the figures from each model, and the case's checks compare them with saved output. - 01 [01\. A company-wide service catalog as system ontology](https://aontu.dev/use-cases/01-service-catalog) Company-wide service catalog as system ontology (two views of the same entities) `refer()` over tree paths, `relations` (acyclic + inverse), `@"aontu:system"`, `get`/`why`, vet-gated onboarding Carries a diagram - 02 [02\. Multi-environment deployment configuration](https://aontu.dev/use-cases/02-deploy-config) Multi-environment deployment config: org → team → service → env layering ranked `*`/`**` defaults, includes, `close()`, constraint atoms, `pack`, `filter`, `why` - 03 [03\. A REST API contract as agent ground truth](https://aontu.dev/use-cases/03-api-contract) REST API contract as the truth an agent codes against; emit→validate→repair `vet` (json/sarif/exit classes), `--at`, `--closed`, repair from vet's findings - 04 [04\. Schema-evolution governance for a shared customer-profile schema](https://aontu.dev/use-cases/04-schema-evolution) Governance of a shared schema across v1→v3 `subsume` profiles, `breaking --against`, `deprecate()`, `aontu_policy.compat`, `hash`, `diff` Carries a diagram - 05 [05\. RBAC / authorization policy as ground truth](https://aontu.dev/use-cases/05-rbac-policy) RBAC / authorization model as data `close()` exhaustiveness, disjunct shapes, `match`, `filter`+`length` invariants, `must()` - 06 [06\. Kubernetes golden path: one service model, N manifests](https://aontu.dev/use-cases/06-k8s-golden-path) Platform golden path generating k8s-shaped manifests for N services `pack`/`each`, `key()`, `_`, `unique()`, overrides onto generated children - 07 [07\. Event/message contracts (the schema-registry case)](https://aontu.dev/use-cases/07-event-contracts) Event/message contracts (schema-registry case) envelope spreads, discriminated unions, `re()` formats, `0d` ids, `breaking` - 08 [08\. Feature flags / runtime config (the write-path case)](https://aontu.dev/use-cases/08-feature-flags) Feature flags with env/tenant overrides and an operational write path `set` (overlay + `--in-place`), pinned-value refusals, ranked defaults, `--trust` confinement Carries a diagram - 09 [09\. An AI agent platform's tool registry as ground truth](https://aontu.dev/use-cases/09-agent-tools) An agent platform's tool registry; runtime call guardrail; the MCP server itself per-tool `vet --at`, the real `aontu-mcp` over JSON-RPC, `agentsmd`, generation - 10 [10\. Enterprise data domain model (customers, orders, invoices, money)](https://aontu.dev/use-cases/10-data-model) Enterprise data domain with exact money and 64-bit ids `0d` exact leaves, `lossy_integer_literal`, cross-field constraints, batch `vet`, `subsume`, the schema rendered as TypeScript and Go - 11 [11\. Shared truth across repos: distributing a schema package](https://aontu.dev/use-cases/11-shared-modules) Shared truth across repos: a schema package published, served and synced into a consumer `publish`/`sync`/`get`/`why`, `pkg tidy`/`verify`/`serve`, three lockfile pins, integrity errors, `#aon1-…` inline pins - 12 [12\. Relations: a pipeline DAG, declared once, enforced at generation](https://aontu.dev/use-cases/12-relations) Pipeline DAG: field-declared relations, one line of schema `rel(t)`, held constraints, `acyclic()`/`inverse(n)` atoms, verdict at generation, `relations`/`reaches` Carries 2 diagrams - 13 [13\. Recursive schema: an approval chain, one reference deep, any data deep](https://aontu.dev/use-cases/13-recursive-schema) Approval chain: a schema one reference deep over any-depth data recursive residuals (`$.spec.Step`), mu-form canon + hash, `recursion_unexpanded`, `vet --at` over plain JSON - 14 [14\. JSON Schema export: the bridge out, and the loss report](https://aontu.dev/use-cases/14-jsonschema-export) JSON Schema as the bridge out: MCP inputSchema, OpenAPI, stock validators `jsonschema --at`/`--strict`/`--format json`, the stderr loss report, exit classes, the money-wire `const` mark - 15 [15\. Code generation](https://aontu.dev/use-cases/15-code-generation) The model as the source of the code: Go, TypeScript and SQL from one catalogue, each over a slice list-spread + `pick` line building, `join` file assembly, backtick target text, `match` type mapping, both-ports byte parity - 16 [16\. Module deps: a layered codebase, drawn as a dependency tree](https://aontu.dev/use-cases/16-module-deps) A codebase's own module graph: four layers, no upward dependencies, drawn as a dependency tree and as the architecture layers `rel(t)` target-shape flow as an architecture rule, `acyclic()`/`inverse(n)`, `reaches`, the tree, matrix and layer views - 17 [17\. Lambda handlers from a service model](https://aontu.dev/use-cases/17-lambda-handlers) Twelve Lambda handlers and their index from one service model, by a rule set written twice: as canonical aontu, and as a Lambda handler with its aontu on marked lines `replace` with no hole syntax, `esc: sq`, verbatim whitespace, the empty-selection conditional, `each` order and the split-form-join chain, the template surface and its round trip, both-ports byte parity - 18 [18\. Role permissions for agent edits](https://aontu.dev/use-cases/18-role-permissions) Role permissions for agent edits: which role may change which subtree, asked before the change `allow` (the deciding entry named as a path into the role model, `--at`, `--format json`, exit classes), a `close()`d role vocabulary, the allow-then-`set` loop, an agent skill, `why` on the rule A case is a model with its refusals asserted. Where a model is put to work generating a **whole application** (held to the reference implementation's own tests, over HTTP) that is an [example](https://aontu.dev/examples). ## Running them yourself The suite is part of the engine repository, not a separate download. It needs Node with `ts/node_modules` installed, plus `python3` and `git` for a few cases. ```sh $ ./use-cases/03-api-contract/check.sh # one case $ ./use-cases/run-all.sh # all of them, one verdict line per case ``` If a documented result differs from a case's output, report the discrepancy with your engine version and the command you ran.