Skip to content

ADR-0032: Annotation File for the Event Model Renderer

Status: Accepted

Date: August 2026

Context

The event-model renderer (protean docs generate --type=event-model, added under #1442) draws the domain as an EventModeling slice timeline: one slice per aggregate cluster, each reading command -> aggregate -> event -> consumer. Each node stands for a domain element. The IR identifies every element by its fully-qualified name (FQN).

The render carries structure. It does not carry the business context a person adds: why a slice exists, the rule behind it, which team owns it. The next regeneration destroys any context written into the generated diagram. The model therefore stays read-only in practice, and no one can use it as a shared artifact. #1338 adds a layer that keeps human notes outside the generated output and merges them back in on render.

The notes live in a file that people commit and hand-edit, so the file's shape is a contract. ADR-0030 records the generated project layout for the same reason. The renderer code that reads the file ships in #1338. This ADR records the file's shape, so a reviewer of that code, or of a project's committed notes, has a fixed reference to check against.

Decision

Human annotations for the event model live in .protean/annotations.toml, a TOML file keyed by element FQN.

Location. The file sits in .protean/, the project-state directory that already holds ir.json, config.toml, and schemas/. TOML matches .protean/config.toml and pyproject.toml, so no new format enters the project. Keeping the notes out of the docs output directory is the point: the generated model stays disposable, and the notes stay under version control next to the code they describe.

Key. Each entry is keyed by the element's fully-qualified name, module.QualifiedName, the value protean.utils.fqn computes. In a project generated from the canonical layout (ADR-0030), an Order aggregate in src/myproj/example/aggregate.py has the FQN myproj.example.aggregate.Order. The FQN is quoted because it contains dots, which TOML reads as table separators otherwise:

[annotations."myproj.example.aggregate.Order"]
note = """
Orders are the fulfillment boundary. An order cannot ship until payment
clears, so PaymentConfirmed gates the shipment slice.
"""
owner = "Fulfillment"

The FQN is the element's identity in the IR, so a note keyed by it survives anything that leaves that identity intact: reordering elements in the source, adding a field, regenerating the model. Renaming or moving the element changes its FQN and breaks the link. That link should break, because a renamed element is a different element, and carrying a note across a rename would attach stale context to new code.

Field set. An entry carries two fields:

  • note (string, required): the business context, in free text. Why the slice exists and the rule behind it. A TOML multi-line string carries a paragraph.
  • owner (string, optional): the team or person accountable for the element.

note and owner cover the three things #1338 names as the context a person adds: the why, the rule, and ownership. A new field is a change to this contract and gets recorded here before the renderer reads it.

Unmatched annotations are reported. An entry whose FQN matches no element in the IR is listed in an "unmatched annotations" section at the end of the render. It is never dropped in silence. A note orphaned by a rename stays visible, so the person who wrote it sees that it needs re-keying. Silently discarding a person's writing is the worst behavior available.

Consequences

The renderer reads a written contract instead of an ad-hoc shape. #1338 loads .protean/annotations.toml by FQN, merges each note into every slice that draws its element, and appends the unmatched-annotation report. A reviewer of that PR, or of a project's committed annotations file, has this ADR to check the shape against.

A note is coupled to the element's FQN, so a rename breaks the link. Anyone renaming an annotated aggregate has to re-key its note, and the unmatched-annotations report is how they find out. This is the trade the FQN key makes: a note stays attached across content changes and breaks on identity changes.

The field set is small and fixed, so a project cannot invent structure the renderer will not read. Adding a field (a link to a ticket, a status) changes this ADR and #1338's loader together, so the file's shape and the code that reads it stay consistent.

The FQN must be quoted in TOML. An unquoted [annotations.myproj.example.aggregate.Order] parses as a chain of nested tables, not one FQN key, so the note attaches to nothing and is reported as unmatched. The generated example and the reference documentation for the file show the quoted form.

Alternatives Considered

Write the notes into the generated model. Simplest to render, and destroyed on the next regeneration. That is the problem #1338 exists to solve, so co-locating notes with the disposable output is the one option ruled out from the start.

Key by a stable annotation id instead of the FQN. An id decoupled from the element would survive renames. An id also needs a second mechanism that binds it to an element. That binding would be stored in the generated model or in the source. Either place brings back the coupling problem. The FQN is already the element's identity in the IR and needs no separate registry. A note keyed by the FQN stops matching when its element is renamed, which is the behavior we want.

A top-level table per FQN, with no [annotations] section. The file could key FQN tables at the top level directly. Putting the FQN tables under [annotations] matches .protean/config.toml, where [domains] is likewise a map keyed by name. The [annotations] table also leaves the top level free for file-level metadata (a format version, say). A bare top-level key then cannot be mistaken for an FQN.

Drop unmatched annotations, or fail on them. Dropping loses a person's writing in silence. Failing turns one stale key into a render that produces nothing, so one rename stops the whole model from rendering. Reporting them keeps the render working and surfaces the staleness in the same output.