Topology DSL — Notes (inline notes)

# Topology DSL — Notes (inline notes)

A **note** is a light-yellow inline note pinned to a topology **work-system
node**. Unlike the external Navigation / organizational-decision-record entities that point *into*
a topology from their own frontmatter, a note is authored **inside the topology
document it annotates**, in a doc-level `notes:` section. It is the **first
inline annotation surface** — the note and the node it annotates live in the same
file.

Notes are for the *conversation around the topology* — a facilitation note, an
open question about a work system. They follow the established **marker + shared
drawer** pattern: a compact light-yellow marker on the anchored node box, its full
text in the shared drawer, never a readable note square painted on the canvas.

> **This page documents the topology delta only. It POINTS TO the shared
> [locator grammar](../locator-grammar.md) — it does not restate it.** The
> note's `locator:` is the **inline (position-only) form** defined there
> (§2 — no `[[file]]` head, resolved against the same document). On topology the
> locator addresses a **work-system node** by name.

## The `notes:` section

`notes:` is a **doc-level** key holding a **list** of note entries. Each entry
is a `{ locator, text, resolved? }` object:

```dwsd-topology
mode: declared
work-systems:
  - { name: "Squad Aurora", flightlevel: 2 }
  - { name: "Platform Engineering", flightlevel: 1 }
notes:
  - on: "Squad Aurora"
    text: "This work system is the focal one — watch its load."
  - on: "Platform Engineering"
    text: "Agreed to split this into two teams next quarter."
    resolved: true
```

| Field | Required | Format | Meaning |
|-------|----------|--------|---------|
| `locator` | yes | inline (position-only) locator | Which work-system node on **this** topology the note pins — the node **name** (bare, or a `[[wikilink]]` to the work system). **No `[[file]]` head prefix** for the same-doc pin (D-02). |
| `text` | yes | string (inline markdown-lite) | The note content. The drawer renders a **safe, non-nesting** `**bold**` / `*italic*` / `` `code` `` subset (parsed to `<strong>`/`<em>`/`<code>` — never raw HTML). Links (`[[wikilink]]` / `[text](url)`) are **not** rendered in a note: a note row is already navigable to its locator, and note text is untrusted (G5). |
| `resolved` | no | boolean (default `false`) | The open/resolved lifecycle flag (see below). |
| `author` | no | string | **Optional, drawer-only** (D-04). Git blame is the authorship record — `author:` is a convenience label shown in the drawer, never required. |

An empty `text` is preserved; an absent or malformed `notes:` value degrades
to *no notes* rather than throwing — the rest of the topology still renders
(the shared *"never blank, never break"* contract).

## The topology locator — the work-system node

A topology note pins to a **work-system node** by matching the node **name**,
**case-insensitively**. Both the bare form (`Squad Aurora`) and the wikilink form
(`[[Squad Aurora]]`) address the same node — the workspace keys work systems by
name. Resolution is **exact-one**: a name that matches no declared work system
does **not** resolve (it becomes an *orphan*, see below).

A note may also anchor a **purely-inferred node** — a node discovered via the
workspace lookup in `mode: infer` rather than declared in `work-systems:`. Such a
note previously orphaned wrongly; it now **resolves correctly** and renders a
marker on the inferred node.

## The `.` document-root note (whole topology)

A note can anchor to the **whole topology** instead of a single node by using
the document-root locator `.`:

```dwsd-topology
mode: declared
work-systems:
  - { name: "Squad Aurora", flightlevel: 2 }
  - { name: "Platform Engineering", flightlevel: 1 }
notes:
  - on: "."
    text: "This whole topology is a draft for the org review."
```

`on: "."` resolves to **document scope** (an empty path), so the note is not
pinned to any work-system node — it renders as **one marker in the topology
header**, to the **left of the doc-tag chips**. When two or more `.` doc-notes
exist, they **collapse to a single header marker with a count badge** — the same
rule every anchor follows: two or more notes on ONE anchor always collapse to one
marker showing how many. A leading `.` on a
longer path is a path *from* the document root and is **equivalent to the bare
path** — see the [locator grammar](../locator-grammar.md#3-typed-path-segments).

## Open / resolved lifecycle (D-10)

A note is **open** by default. Setting `resolved: true` marks it done — and the
**marker itself changes** (departing from the ODR `status`, which stayed
drawer-only):

- **On the canvas** — a resolved note **fades / desaturates** (lower opacity,
  muted yellow) on its node box, so open notes stand out.
- **In the drawer** — resolved notes group under a dedicated **"Resolved"**
  subsection, separated from the still-open notes.

The lifecycle state lives **where the entry is authored** — right on the inline
`notes:` entry.

## Orphan behavior — never silently dropped (D-11)

When a note's `locator:` no longer resolves (the work system was renamed or
removed from the local view), the note is **not** silently lost — the deliberate
departure from the usual degrade-to-no-marker: *a reviewer's note is data, not
decoration.* An orphaned note is surfaced **both** ways:

1. **In the drawer** — it drops into a dedicated **"Orphaned notes"** tray inside
   the Notes bucket, with its **text preserved**.
2. **At the source** — an **authoring diagnostic** (a squiggle) is raised on the
   offending `notes:` entry.

Belt-and-suspenders: the preview reader *and* the author both see an orphan.

## The "Notes" drawer bucket (D-13)

Notes render into their **own** top-level drawer bucket labeled **"Notes"**
(single type = own bucket, the ODR precedent). The "Orphaned notes" tray is a
subsection **within** the Notes bucket. The marker is styled with a
**light-yellow note anmutung** on both the pill and the drawer entries.

> The exact marker shade, glyph, and DV-3 treatment are locked by Thomas at the
> EDH walk (D-09) — this page deliberately hard-codes **no** hex value that could
> drift from the anchor registry. On topology the note renders in its **own**
> light-yellow color (the note reads best un-tinted), matching the pin /
> organizational-decision-record precedent rather than the FL-tint chip family.

## Worked example

A topology with one open note on the focal node and one resolved note on a
contributor:

```dwsd-topology
mode: declared
work-systems:
  - { name: "Squad Aurora", flightlevel: 2 }
  - { name: "Platform Engineering", flightlevel: 1 }
notes:
  - on: "Squad Aurora"
    text: "Focal system — is it **overloaded**? Check flow."
  - on: "[[Platform Engineering]]"
    text: "Team split agreed at the org review."
    resolved: true
    author: "Thomas"
```

- The first note renders a light-yellow marker on the `Squad Aurora` node,
  open.
- The second renders a **faded** marker on the `Platform Engineering` node and
  appears in the drawer's **"Resolved"** subsection.
- If `Platform Engineering` were removed from the local view, the second note
  would move to the **"Orphaned notes"** tray (text preserved) and raise a
  diagnostic on its entry.

## See also

- [Locator grammar](../locator-grammar.md) — the authoritative locator reference;
  the inline (position-only) form is §2.
- [Topology reference](./index.md) — the work-system node model this note pins
  to.
- [Board notes](../board/notes.md) · [Route notes](../route/notes.md)
  — the same `notes:` surface on the other two DSLs.