taler-docs

endpoint-documentation-requirements.rst (57481B)

---

 .. _endpoint-documentation-requirements:
 
 ==============================================
 Endpoint and Method Documentation Requirements
 ==============================================
 
 .. contents:: Table of Contents
    :local:
    :depth: 2
 
 Status: proposed convention.  Applies to: every per-endpoint ``.rst`` file
 under ``taler-docs/core/`` (HTTP APIs: exchange, merchant, bank-\*,
 corebank, challenger, taldir, mailbox, donau, auditor, sync, terminal,
 ...) and every per-operation ``.rst`` file under
 ``taler-docs/core/wallet-core/`` (wallet-core methods).
 
 This document is the normative format specification.  Design intent and
 rationale, the diagnostic of the current corpus, the migration plan, and
 worked examples live in :doc:`DD 105
 <../design-documents/105-machine-readable-endpoint-documentation>`.
 
 The format is language-agnostic.  The shape layer describes wire-level
 types (JSON objects exchanged between client and server) via the
 historically named ``ts:def`` / ``ts:op`` directives; nothing in this
 specification ties the documented semantics to any implementation
 language, and generated artifacts may target any language.
 
 
 1. Purpose
 ==========
 
 Each endpoint/method is documented in **exactly one** ``.rst`` file that is
 **completely machine-readable**: every semantic claim a client, a doc lint,
 or a use-case generator could need is expressed in a directive option, a
 field, or a typed block — never only in prose.  Prose remains for human
 readers, but it is *rendering*, not *source of truth*.
 
 The goal is that the following can be **derived** from the doc corpus
 without reading prose:
 
 * per-entity state tables (states, transitions, timers, failure exits),
   with every transition naming its trigger and guard,
 * per-actor observation projections (who can see which state, through
   which endpoint field or notification channel),
 * cross-component flows (which call creates an identifier, which calls
   carry or consume it, which watched source moves an entity),
 * sequence diagrams (happy-path messages from transition edges,
   ``alt`` blocks from guards, ``loop`` blocks from timers).
 
 The docs are **authoritative**: implementations conform to them.  To make
 that enforceable, the machine-readable shape layer (``ts:def`` types,
 request/response schemas) should be used to generate as much source code
 as possible (types, validators, stubs), with drift caught by CI in the
 implementation repositories.
 
 One design philosophy runs through everything below: **derive edges,
 declare anchors.**  Anything that is an *edge* (a transition, an arming,
 an observation, a carriage of a value) is written once, on the edge
 itself — the transition, the method, the effect.  Anything that acts as
 a *resolution anchor* (an entity, a timer name, an identifier, a
 notification channel) is declared once, minimally, so that the edges can
 be checked against it.  If a fact can be derived from edges, it is never
 also declared; if a name must be resolvable, it is never left implicit.
 
 
 2. File organization
 ====================
 
 R2.1  One file per method.  No file documents two unrelated methods; no
       method is documented in two files.  Two declared exceptions exist:
 
       * *Variant groups*: one logical method may be documented as
         several directive instances in one file when the variants differ
         only in a path parameter's value domain (per-record-type delete
         endpoints, per-provider webhook entry points) or in long-poll
         parameter dialect.  The file is linted as one method with
         variants.
       * *Proxy stanzas*: wildcard delegation declarations
         (``.. http:any::`` with wildcard paths, e.g. reverse-proxy
         pass-throughs) are not methods; they carry no request/response
         semantics and follow only the naming rules of R2.2.
 
 R2.2  Naming (required):
 
       * HTTP endpoints: ``<method>-<path-segments>.rst``, lowercase,
         path variables in upper case without ``$``
         (``get-withdrawal-operation-WITHDRAWAL_ID.rst``),
         placed in the per-API directory (``core/exchange/``,
         ``core/merchant/``, ``core/bank-integration/``, ...).
       * wallet-core operations: ``<op-name>.rst`` in kebab-case inside
         the category directory (``core/wallet-core/balances/``).
 
 R2.3  Chapter files (``api-*.rst``) keep version history, shared
       conventions, and ``.. include::`` of per-method files.  They carry
       **no** per-method semantics that the method file itself lacks.
 
 R2.4  Cross-method information lives in exactly two places outside the
       method files: the **entity registry** (§4: entities, lifecycles,
       timers, identifiers) and the **per-component notification pages**
       (§5: real-time channels).  Method files *reference* these; they
       never restate them.
 
 
 3. The method file format
 =========================
 
 A compliant file contains the sections below **in this order**.
 Requirement levels: **REQ** (must be present), **COND** (present when
 applicable), **OPT**.
 
 3.1 Method header — REQ
 -----------------------
 
 The header is the method's machine-readable identity card.  Every option
 exists because a specific consumer needs it: the lint (vocab checks),
 the use-case generator (persona closures, observation bindings), the
 code generator (shape extraction), or the exclusion filter (drafts).
 
 HTTP endpoints keep the existing identity directive, extended with new
 options:
 
 .. code-block:: rst
 
    .. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
       :since: v1
       :maturity: stable
       :idempotency: readonly
       :observes-state: withdrawal-operation.status
       :visible-to: wallet-user, bank-customer (capability withdrawal-id)
       :wait: long-poll(timeout_ms, old_state)
 
    One-line summary usable standalone (no markup that breaks extraction).
 
    Longer prose description...
 
 wallet-core operations keep ``ts:op``, extended the same way:
 
 .. code-block:: rst
 
    .. ts:op:: getBalances
       :read-only:
       :since: v4
       :maturity: stable
       :idempotency: readonly
       :visible-to: wallet-user
       :wait: none
 
 Options:
 
 ``:since:`` (REQ)
   Protocol/API version introducing the method, exactly ``v<N>``.
   Needed so derived artifacts can be sliced by protocol version (an old
   wallet talking to a new exchange sees a genuinely different machine).
 
 ``:deprecated:`` (COND)
   Version of deprecation, exactly ``v<N>``; presence implies
   ``:maturity: deprecated`` unless ``:maturity:`` says otherwise.
 
 ``:maturity:`` (REQ, default ``stable``)
   One of: ``stable``, ``experimental``, ``draft-no-consumers``,
   ``proposed-unimplemented``, ``deprecated``.
   Methods marked ``draft-no-consumers`` or ``proposed-unimplemented``
   are excluded from use-case derivation (their files exist to document
   intent, not behavior).  Examples in the current corpus: wads and
   reserve-control endpoints in the exchange API, ``/seed`` in donau,
   the apns/account-directory/ebisync APIs.
   (The option is named ``:maturity:`` and not ``:status:`` because the
   HTTP domain already uses ``:status:`` as a field-name alias for
   status codes.)
 
 ``:idempotency:`` (REQ)
   One of: ``readonly``, ``replay-safe``, ``keyed:<field>``, ``unsafe``.
   See §3.5 and §7.1.
 
 ``:observes-state: <entity>.<field>`` (COND)
   The response field (dotted path into the response ``ts:def``) that
   carries an entity's machine-readable state value
   (e.g. ``withdrawal-operation.status``, ``order.order_status``,
   ``transaction.state``).  The field's type must be a string union or
   an object with an enumerated discriminator — the lint resolves every
   union member against the entity's lifecycle (§4).  This is the
   **observation binding**: it states that this method's response *is* a
   view onto that entity's machine.  Without it, the per-actor state
   projections ("who can see which state, where") cannot be computed —
   the generator would have to guess the binding from type names or
   enum-member spelling, which collides across APIs (``pending``
   appears in half a dozen unions).
 
 ``:visible-to:`` (REQ)
   Comma-separated actor surfaces that may legitimately call or observe
   through this method (§7.3).  This is the single authorization fact of
   the file: the actor value implies the credential mechanism (§7.3
   table), so no separate ``:auth:`` field exists.  Where access is
   gated by an unguessable identifier rather than credentials, the
   capability is named in parentheses:
   ``merchant-staff, tax-auditor (capability wtid)``.
   Persona projections are computed as closures over this field.
 
 ``:timer-ref: <entity>.<timer>`` (COND, repeatable)
   References a timer **declared at the entity** (§4.3), with a ``:role:``
   describing this method's relationship to it:
 
   * ``arms`` — a successful call starts the clock, typically via a
     request field named in ``:field:`` (``POST /private/orders`` arms
     ``order.refund-deadline`` via ``refund_delay``).
   * ``exposes`` — the response carries the timer's current value, in
     the field named by ``:field:``
     (``ValidationChallengeInfo.solve_expiration``).
   * ``affected-by`` — the method's behavior changes once the timer
     fires (``.../challenge/$ID/confirm`` fails with
     ``TAN_CHALLENGE_EXPIRED``).
 
   The timer's semantics are declared once at the entity; the firing
   edges live in the lifecycle's transitions.  Method files only declare
   their *relationship* to the clock.
 
 ``:wait:`` (REQ)
   ``none``, or ``long-poll(<param1>, <param2>, ...)`` listing this
   method's long-poll request parameters.  This acknowledges that the
   endpoint can rendezvous with a state change.  It stays at the method
   because the parameter dialects are per-endpoint and differ
   (``timeout_ms`` alone, ``timeout_ms`` + ``old_state``, the merchant's
   ``lp_status``/``lp_not_etag`` algebra).  Real-time *push* channels
   are **not** declared here — they live in the component's notification
   page (§5).
 
 3.2 Request — REQ
 -----------------
 
 **Why this section is strict:** the request block is what the code
 generator turns into client stubs and validators, and what the lint
 cross-checks ``:wait:`` parameters against.  A parameter that exists
 only in prose is invisible to both.
 
 .. code-block:: rst
 
    **Request:**
 
    :query timeout_ms:
      *Optional.*  Timeout in milliseconds for :ref:`long-polling
      <long-polling>`.  Since protocol **v3**.
    :header Taler-Purse-Signature:
      *Conditionally required.*  Purse signature over the request.
    :body:
      The request body must be a `WithdrawRequest` object.
 
    .. ts:def:: WithdrawRequest
      ...
 
 Rules:
 
 R3.2.1  Every parameter appears exactly once as ``:query:``,
         ``:header:``, ``:path:``, or inside the ``ts:def`` body type.
         Optionality (``*Optional.*``, ``*Conditionally required.*``)
         starts the description; version annotations use ``@since`` /
         ``@deprecated`` in the existing style.
 
 R3.2.2  Every type referenced is defined in a ``ts:def`` block in this
         file or in a reachable common file.  No anonymous prose types.
 
 3.3 Response — REQ
 ------------------
 
 **Why the discipline:** HTTP status codes in this ecosystem do not
 follow the naive "2xx = success, else failure" rule (see §3.4).  The
 response section declares the *shape* of each outcome; the **Errors**
 section declares its *semantics*.  Keeping the two apart is what lets
 the generator distinguish a failure edge from a state report.
 
 .. code-block:: rst
 
    **Response:**
 
    :http:statuscode:`200 OK`:
      :schema: BankWithdrawalOperationStatus
      The withdrawal operation is known to the bank...
    :http:statuscode:`404 Not found`:
      :error:
      The operation was not found.
 
 Rules:
 
 R3.3.1  Every documented status code carries ``:schema: <TypeName>``
         (a success-shaped body defined in ``ts:def``), ``:error:``
         (standard `ErrorDetail` body), or both.  "Both" happens for
         non-2xx codes whose body reports state rather than failure —
         those additionally get an **Errors** entry with
         ``:temporality: progress`` (§3.4).
 
 3.4 Errors — REQ (explicitly empty if none)
 -------------------------------------------
 
 **Why this section exists:** error codes are overloaded across flows,
 and the overloads are not inferable.  A 404 on an unfunded reserve
 means "wait, the wire hasn't arrived" (transient); a 404 on an expired
 order means "gone forever" (terminal).  A 402 on the order status page
 is the *normal unpaid state* (progress); a 402 on purse merge is a
 fixable rejection.  Same codes, opposite meanings.  The two fields per
 entry — ``:temporality:`` (what kind of outcome this is) and
 ``:recovery:`` (what moves the flow forward) — are what make the
 failure and timer columns of derived state tables computable instead
 of guessed.
 
 Every non-2xx outcome gets a structured entry — including codes that
 are **not failures** (progress signals such as 402-unpaid, 202-pending):
 
 .. code-block:: rst
 
    **Errors:**
 
    :error 404 TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN:
      :temporality: transient-state
      :recovery: long-poll
      The reserve is unknown; the wire transfer may not have arrived.
      The wallet should long-poll the reserve status and repeat the
      exact same request.
    :error 409 TALER_EC_EXCHANGE_WITHDRAW_INSUFFICIENT_FUNDS:
      :temporality: fixable
      :recovery: retry-modified
      The reserve balance is too low; retry withdrawing less.
    :error 451 TALER_EC_EXCHANGE_KYC_REQUIRED:
      :temporality: gate
      :recovery: start-kyc
      The account must pass KYC before this call can succeed.
    :error 402 none:
      :temporality: progress
      :recovery: none
      The order is unpaid; the body carries the ``taler_pay_uri`` the
      wallet uses to proceed.  This is the normal waiting state of the
      flow, not a failure.
 
 Rules:
 
 R3.4.1  ``:temporality:`` (REQ per error) — one of ``transient-state``,
         ``terminal``, ``fixable``, ``rate-limited``, ``gate``,
         ``progress`` (§7.4).  ``progress`` entries are how the
         generator knows *not* to derive a failure edge: the code is the
         state signal.
 
 R3.4.2  ``:recovery:`` (REQ per error) — the client action that can
         move the flow forward, from §7.5.  For ``progress`` entries this
         is usually ``none`` or ``poll-later``.
 
 R3.4.3  The human-readable condition follows the fields.  Multiple
         error codes for one status get one entry each.  Where the error
         is caused by a timer firing, the condition references the
         entity timer (``:timer-ref:`` in the header makes the method's
         relationship explicit).
 
 3.5 Idempotency — COND (mutating methods)
 -----------------------------------------
 
 **Why this is a first-class field:** retries are the universal response
 to network failure, and a request that arrived-but-lost-its-response is
 indistinguishable from one that never arrived.  Whether a verbatim
 replay is *safe* therefore decides whether the client's failure branch
 exists at all — and whether the derived sequence diagram draws a retry
 loop or an abort.  This is not guessable: ``POST /withdraw`` is
 replay-safe by careful design (repeat the exact request, get the same
 response, coins are never lost to a network cut), while
 ``POST /private/orders`` without an explicit ``order_id`` creates a
 duplicate.  The label also flags design smells: an ``unsafe`` mutating
 method in a system built on at-least-once networking deserves review.
 
 Covered by the ``:idempotency:`` header option (§3.1, vocabulary in
 §7.1).  For ``keyed:<field>`` the file additionally documents the key
 field's reuse semantics in prose (existing good examples: bank-wire
 ``/transfer`` ``request_uid``, cashout ``request_uid``).  The lint
 requires: ``POST``/``PATCH``/``DELETE`` without
 ``:idempotency: unsafe | replay-safe | keyed:*`` is an error.
 
 3.6 Lifecycle linkage — COND
 ----------------------------
 
 **Why two bindings and not one:** a method relates to entity machines
 (§4) in two fundamentally different ways, and conflating them breaks
 different consumers:
 
 * **Mutators** declare their transitions in **Effects** (§3.7).  The
   lint diffs these against the entity's lifecycle: an effect naming an
   undeclared transition is a doc bug in one of the two places.  This is
   the two-sided check — the lifecycle says "call X drives A→B", the
   method file says "I drive A→B on entity E", and the disagreement
   surfaces.  One-sided declarations silently rot; that is the lesson
   of every doc-versus-code audit on this corpus.
 * **Readers** declare the observation binding via ``:observes-state:``
   (§3.1).  This is what makes the per-persona "user sees" column of a
   state table *generated* rather than authored.
 
 R3.6.1  Every entity named in either place is registered in the entity
         registry with: owner, transitions, terminal states, timers,
         identifiers.
 
 R3.6.2  State values named anywhere in the file resolve to the
         entity's lifecycle states (the set inferred from its
         transitions).
 
 3.7 Effects — COND (mutating methods)
 -------------------------------------
 
 **Why this section exists:** request/response documentation describes
 what the *caller* gets back — it says nothing about what changed in the
 *world*.  ``POST /private/orders`` returns an order id; the state that
 matters — "a wallet can now claim this order" — is a side effect
 visible through a *different* endpoint by a *different actor*.  A
 mutation is not documented until you have said who else can now see
 what.  The Effects block is also the generator's source for the
 *messages* of a sequence diagram: each effect edge is a signal to
 another lifeline.
 
 .. code-block:: rst
 
    **Effects:**
 
    :effect:
      :entity: order
      :transition: none -> unpaid
      :observable-by: :http:post:`/orders/$ORDER_ID/claim`
      Creates the order; a wallet can now claim it.
 
 Field by field:
 
 ``:entity:``
   The lifecycle entity whose machine moves (resolves to §4).
 
 ``:transition:``
   The exact edge performed, in the lifecycle's own notation.  Must
   agree with the entity's declared transitions (the two-sided check
   of §3.6).
 
 ``:observable-by:``
   The endpoint through which another actor observes the change.  This
   is the join that lets a generator draw the *next* message in the
   sequence diagram.
 
 R3.7.1  One ``:effect:`` entry per world-change beyond the response.
 
 R3.7.2  Real-time signals caused by the change (wallet notifications,
         merchant webhooks) are **not** listed here; they follow from the
         transition and are documented in the component's notification
         page (§5).
 
 3.8 Identifiers — COND
 ----------------------
 
 **Why this section exists:** methods do not exist in isolation — a
 value created by one call shows up in another component's API three
 hops later.  This block declares, per *identifier*, the method's role
 in that value's life.  Identifiers are the handles and join keys of the
 system (``reserve_pub``, ``wtid``, ``order-id``, claim nonces);
 ``order-id`` *names* an order entity, but the identifier itself is a
 value, not a machine.
 
 From the union of all method-side tags, the generator derives the
 identifier's full life story (created-by / carried-by / read-by /
 consumed-by), draws the cross-component value-flow graph, and the lint
 gets its two-sided join checks.  The registry (§4.4) holds only the
 anchor: the name, the capability property, and prose.
 
 .. code-block:: rst
 
    **Identifiers:**
 
    :identifier reserve_pub:
      :role: carries
      :registry: :ref:`identifier-reserve-pub`
      Wallet-generated reserve key; delivered to the bank here, becomes
      the wire subject of the funding transfer.
 
 The four roles, from the method's perspective:
 
 * ``creates`` — the value begins to exist here.  ``POST
   /private/orders`` creates ``order-id``; the wallet's withdrawal
   preparation creates ``reserve_pub``.
 * ``carries`` — transports a value created elsewhere: in the URL, body,
   response, or wire subject.  The bank-integration selection POST
   carries ``reserve_pub`` from wallet to bank; ``POST
   /private/transfers`` carries ``wtid`` from the bank statement into
   the merchant backend.
 * ``reads`` — uses the value as a lookup key.  ``GET
   /reserves/$RESERVE_PUB`` reads ``reserve_pub``; ``GET
   /transfers/$WTID`` reads ``wtid``.
 * ``consumes`` — validity ends here (single-use values): the
   challenger's ``/token`` consumes the authorization grant; a
   successful ``/orders/$ID/pay`` consumes the claim nonce.
 
 One method can play several roles on several identifiers: ``POST
 /orders/$ID/pay`` *reads* ``order-id``, *consumes* the claim nonce, and
 *carries* ``h_contract_terms`` onward to the exchange.
 
 R3.8.1  ``:role:`` vocabulary is §7.8.  The ``:registry:`` ref must
         resolve to the identifier's registry entry (§4.4).
 
 3.9 Details/Notes — OPT
 -----------------------
 
 Free prose for anything genuinely not expressible above (rationale,
 privacy notes, examples).  Must not introduce semantics that contradict
 or extend the structured sections; the lint greps for state names and
 error codes appearing *only* here.
 
 
 4. Entities and lifecycles
 ==========================
 
 **Why a registry:** state lives *between* methods.  A method file can
 honestly describe its own request and response, but the machine the
 methods collectively implement — the states, the transitions, the
 clocks — is a property of the *entity*, not of any endpoint.  The
 registry (``core/entities.rst``, with per-API chapters linking in) is
 where that machine is declared once.  Per the design philosophy, the
 registry declares anchors (names, owners, terminal states, timer names,
 identifier properties) and the edges (transitions) carry their own
 facts.
 
 Each entity has exactly one declaration:
 
 .. code-block:: rst
 
    .. entity:: tan-challenge
       :owner: corebank
 
       A TAN challenge issued for multi-factor confirmation of a
       corebank operation.
 
       .. lifecycle::
          :terminal: solved, expired, exhausted
 
          :transition none -> unsolved:
            :trigger: call <any MFA-gated call returning
              202 + ChallengeResponse>
            The challenge is created as part of an MFA-gated operation.
          :transition unsolved -> solved:
            :trigger: call POST /accounts/$U/challenge/$ID/confirm
            Correct TAN submitted.
          :transition unsolved -> expired:
            :trigger: timer tan-challenge.solve-expiration
            The challenge was not solved in time.
          :transition unsolved -> exhausted:
            :trigger: call POST /accounts/$U/challenge/$ID/confirm
            :if: the failed-confirmation counter reaches zero
            Too many wrong TANs submitted.
 
       .. timer:: solve-expiration
          The clock by which the challenge must be solved.  (Armed by
          challenge creation — derived from the ``arms`` timer-refs of
          the creating methods; exposed in
          ``ValidationChallengeInfo.solve_expiration`` — derived from
          ``exposes`` timer-refs; fires the ``unsolved -> expired``
          transition — derived from the lifecycle.)
 
       .. timer:: retransmission-cooldown
          Throttles TAN retransmission; calls while it is active fail
          with 429 (derived from the ``affected-by`` timer-ref and the
          error entry of the (re)send endpoint).
 
       .. identifier:: challenge-id
          :capability: no (owner-authenticated)
          Identifies the challenge on the challenge endpoints.
 
 4.1 Owner
 ---------
 
 ``:owner:`` (REQ) names the **component holding authoritative state and
 executing the transitions** — not merely where the entity is documented
 or displayed.  Ownership determines which component's answer is truth;
 every other component's view is a projection that may lag (the wallet's
 balance is a projection of exchange-owned coin-spend state; the
 wallet's order status display is a projection of merchant-owned order
 state).  An entity may be *exposed* through several APIs of the owner
 (``withdrawal-operation``: bank-integration, corebank, terminal) — name
 them in prose under the owner.  Where state is genuinely shared across
 components (KYC requirement and legitimization state is projected into
 the exchange, the merchant, the bank, and the wallet), the owner is
 the component whose answer is authoritative and the projections are
 named as such; ownership is about who executes transitions, not about
 which trigger kind dominates — a wallet transaction entity is owned by
 wallet-core even though its transitions are driven by watches, timers,
 and local user actions rather than incoming calls (§6).
 
 4.2 Lifecycle
 -------------
 
 The lifecycle is the transition list.  **States are inferred**: the
 state set is exactly the names appearing as transition sources or
 targets (plus the pseudo-state ``none`` for pre-existence, which is
 never a real state).  ``:terminal:`` (REQ) is **declared**, not
 inferred — it is the absorbing set:
 
 * it anchors use-case success conditions ("done" = reaching a declared
   terminal state);
 * it makes the absorbing property checkable: a transition *leaving* a
   declared terminal state is a lint error;
 * it turns incompleteness into signal: a declared-non-terminal state
   with no outgoing transitions is a lint warning (a silently truncated
   machine becomes visible).
 
 ``:final-reactivatable:`` (COND) declares states that anchor success the
 same way but from which declared reactivation edges are legal (a paid
 order later refunded; a ``done`` wallet transaction reactivated by a
 refund query).  Transitions leaving a ``final-reactivatable`` state are
 permitted but must be listed explicitly.  See §6 for the wallet
 transaction entities that need this.
 
 Each ``:transition: A -> B:`` has:
 
 ``:trigger:`` (REQ, repeatable)
   What causes the transition (§7.7).  This is the causality layer —
   the part of the system that no per-endpoint doc can see locally:
 
   * ``call <method>`` — an external call to the owner's API
     (resolvable to a method file).  Example: the wallet's selection
     POST drives ``pending -> selected``.
   * ``timer <entity>.<timer>`` — a declared entity timer fires.
     Example: ``solve-expiration`` drives ``unsolved -> expired``.
   * ``watch <component>.<observable>`` — the owner watches an external
     source (the exchange's wirewatch watching the bank's incoming
     history; the merchant backend tracking exchange wire arrivals).
     This is where **cross-component causality** lives: the transition
     names the other component's observable, which is the join the old
     prose never made.
   * ``external <description>`` — a human or off-API action (bank-UI
     2FA confirmation, cash inserted at a terminal, an offline key
     ceremony).  Non-API actors enter the machine here, honestly marked
     as outside every API.
 
 ``:if:`` (COND)
   The guard: the config/data condition under which this transition
   exists at all, referencing observable fields
   (``:if: /keys.kyc_enabled and the amount crosses the withdrawal
   threshold``).  Guards are how context forks (KYC on/off, thresholds,
   feature flags) enter the machine without multiplying machines — one
   canonical machine, guarded edges, instead of a combinatorial family
   of near-identical diagrams.
 
 Prose (REQ)
   One or two sentences of human explanation.
 
 4.3 Timers (slim anchors)
 -------------------------
 
 A timer is declared as a **name plus semantics in prose** — nothing
 more, because everything structural is derivable from edges:
 
 * *fires-to*: from the lifecycle transition whose ``:trigger:`` is this
   timer;
 * *armed-by*: from the method whose ``:timer-ref:`` has role ``arms``;
 * *exposed-in*: from the method whose ``:timer-ref:`` has role
   ``exposes`` (its ``:field:``);
 * *gates*: from the ``429``/``rate-limited`` error entry of the method
   whose ``:timer-ref:`` has role ``affected-by``.
 
 The block survives at all for three reasons: it is the **lint anchor**
 every ``:trigger: timer`` / ``:timer-ref:`` resolves against (free
 strings across hundreds of files would drift); it is the home of
 **config-armed** timers no method arms (``:armed-by:`` is present only
 in that case — e.g. ``purse_timeout`` comes from ``GET /keys`` global
 fees, not from any call); and it is the **gap marker**: an entity whose
 timers are not yet specified records the gap here once (see the
 ``withdrawal-operation`` example in DD 105), instead of silence
 scattered across N method files.
 
 4.4 Identifiers (slim anchors)
 ------------------------------
 
 An identifier is declared as **name + ``:capability:`` + prose**:
 
 .. code-block:: rst
 
    .. identifier:: reserve_pub
       :capability: yes
       Reserve public key; possession authorizes reserve-status reads.
       Wallet-generated; becomes the wire subject of the funding
       transfer.
 
 ``:capability:`` (REQ: ``yes``/``no``) records whether possession
 alone authorizes (unguessable: ``wtid``, ``withdrawal-id``, purse/claim
 links) — the property that distinguishes "public by design" (``GET
 /keys``) from "public but unguessable" (``/transfers/$WTID`` is usable
 by tax auditors *because* of it).  It is a property of the *value*, not
 of any method, so it has no other home; it is also what the
 ``:visible-to:`` capability annotations resolve against (V3).
 
 Everything else is derived from the method files' **Identifiers:**
 blocks (§3.8): *created-by*, *carried-by*, *read-by*, *consumed-by*.
 One exception needs prose: identifiers created **internally** (``wtid``
 is minted by the exchange's aggregator process — no method tags
 ``creates``) get a created-by sentence here, mirroring config-armed
 timers.  The registry also serves as the canonical naming list — the
 single place where ``reserve_pub`` is one concept, so that hundreds of
 files of tags can be checked for spelling drift.
 
 
 5. Per-component notification pages
 ===================================
 
 **Why these pages exist:** how an actor *learns* that a state changed
 is as much a part of the use case as the state change itself — and it
 was historically documented in prose scattered across chapters.  The
 doctrine of this system is *signals are hints; reads are truth*: a
 notification tells you something changed, an authoritative read tells
 you what is.  The notification page is where a component declares its
 channels, their delivery semantics, and — critically — the read that
 backs each signal.
 
 Every component that offers real-time signals documents them in a
 single notification page: ``core/wallet-core/notifications.rst``
 (exists today as a flat list of notification types; to be restructured
 into the channel form below), a merchant notification page (webhooks,
 currently prose in ``api-merchant.rst``), an exchange notification page
 (will honestly declare: none — pull + long-poll only), and so on.
 
 Each channel declaration:
 
 .. code-block:: rst
 
    .. notification-channel:: webhook
       :component: merchant
       :registration: POST /private/webhooks
       :delivery: at-least-once
       :events: order_created, pay, refund, order_settled,
                category_created, category_update, category_delete,
                inventory_update, inventory_product_created, ...
 
       Every event is a hint about an entity transition; the
       authoritative read is named per event:
       ``pay``/``refund``/``order_settled`` ->
       ``GET /private/orders/$ORDER_ID``.
 
 Rules:
 
 R5.1  ``:delivery:`` is one of ``lossy-hint`` (no delivery guarantee;
       re-read for truth — the wallet notification doctrine),
       ``at-least-once`` (duplicates possible, recipient must
       deduplicate), ``rendezvous`` (the channel itself blocks until the
       state is available).  If the implementation's delivery semantics
       are not specified today, write ``unspecified`` — a visible gap,
       not silence.
 
 R5.2  Every event names its **authoritative read** (the endpoint whose
       response is the truth).  The lint rejects a channel without a
       read reference per event family.
 
 R5.3  Method files never declare push channels.  The method whose
       effect *causes* a signal is linked automatically: effect
       transition (§3.7) + channel event mapping (here).
 
 R5.4  Long-poll is **not** a notification channel; it is a property of
       the read endpoint and is declared via ``:wait:`` (§3.1).  A
       long-poll response is authoritative state delivered late, not a
       hint.
 
 
 6. wallet-core method variant
 =============================
 
 ``ts:op`` files follow the same requirements with this mapping:
 
 .. list-table::
    :header-rows: 1
 
    * - HTTP concept
      - wallet-core op equivalent
    * - ``:visible-to:``
      - ``wallet-user`` (local message protocol, no credentials)
    * - ``:http:statuscode:`` responses
      - **Response** ``ts:def`` + **Expected errors**
    * - ``:error`` entries
      - **Expected errors** entries, same ``:temporality:`` /
        ``:recovery:`` fields
    * - ``:wait:``
      - ``long-poll(...)`` for blocking ops (``waitTransactionState``,
        ``waitExchangeReady``, ...), ``none`` otherwise; the wallet's
        push channel is documented in ``notifications.rst`` (§5)
    * - effects
      - transitions on transaction-group entities
        (``transaction-withdrawal``, ...) with states from the DD37
        machine
 
 ``TransactionState`` values used in ``:transition:`` fields must match
 ``major[:minor][/working]`` notation of DD37 and resolve against
 ``core/wallet-core/transactions/get-transaction-by-id.rst``.
 
 Wallet transaction entities extend the lifecycle model of §4 in four
 ways (rationale in DD 105):
 
 * **Final-reactivatable states.**  DD37's ``done`` is not absorbing
   (refund queries, ``rebind-session``, and late KYC requirements can
   reactivate a transaction).  Transaction entities declare
   ``:final-reactivatable:`` (§4.2) for such states and list the
   reactivation edges explicitly.
 * **Orthogonal modifiers instead of state explosion.**  The DD37
   ``working`` flag and the ``suspended`` / ``suspended-aborting`` /
   ``suspended-finalizing`` shadow states are declared as modifiers
   (same mechanism as ``:modifiers:`` on other entities), not as
   literal states.  A ``:standard-edges: suspend-retry`` declaration on
   the lifecycle implies the suspend/resume/retry edge family on every
   non-final state, so the inferred state and edge sets include them
   without authoring each one.  DD37 state *expressions*
   (``pending:*``, ``pending:-``, ``/idle``, comma alternation) are
   accepted wherever a state set is matched.
 * **Absence as signal.**  The ``deleted`` state exists only in
   notifications; its observation is the absence of the record (a
   not-found error from ``getTransactionById``).  ``:observes-state:``
   bindings may name this explicitly (``transaction.state,
   absence-signal: deleted``).
 * **Actions are not derived.**  ``txActions`` are computed per state
   *and* context; no "possible actions" column is generated from the
   lifecycle.
 
 The registry entries for transaction entities are the canonical
 machine-readable form of the DD37 machines; DD37's per-type state
 tables are generated from the registry.
 
 
 7. Controlled vocabularies
 ==========================
 
 Controlled vocabularies are where machine-readability lives or dies.
 A field whose values come from a closed list can be checked, counted,
 and closed over by tooling; a field with free text is prose wearing a
 costume.  Every value below is part of the contract: **adding a value
 is a specification change** (tooling must learn its meaning), and using
 a non-listed value is a lint error (M8.3).  For each value we give the
 definition, a real example from the corpus, and what the derivation
 tooling does with it.
 
 7.1 ``:idempotency:`` values
 ----------------------------
 
 The question this field answers is the most frequent operational
 question a client faces: *"the network ate my request or its response —
 may I send the exact same bytes again?"*  The answer determines whether
 the failure branch of a use case exists at all, and what the sequence
 diagram draws at every network boundary.
 
 * ``readonly`` — the call mutates nothing: no entity transition, no
   world-change.  (Logging and caching on the server side do not count
   as mutation.)  Examples: ``GET /keys``, ``getBalances``.
   *Consumers:* the generator expects no **Effects** section; the lint
   warns if a ``readonly`` method declares one (V6's inverse).
 
 * ``replay-safe`` — the server has recorded the request and its
   response; a byte-identical repeat returns the same response with no
   additional effect.  Examples: ``POST /withdraw`` (repeating the exact
   request yields the same blinded signatures — coins are never lost to
   a network cut), donau batch-issue (keyed on the recorded request
   hash).  *Failure mode prevented:* value loss when the response is
   lost after the server committed.  *Consumers:* the generator draws
   retry self-loops for free.  Note that replay means *byte-identical*;
   a modified request is a new operation, and conflicts there belong to
   **Errors** (e.g. ``TALER_EC_EXCHANGE_WITHDRAW_IDEMPOTENT_PLANCHET``).
 
 * ``keyed:<field>`` — the client supplies an idempotency key; reuse of
   the key with the same body suppresses duplicate effects, reuse with a
   *different* body is rejected (409).  Examples: bank-wire
   ``/transfer`` (``request_uid``), corebank cashouts (``request_uid``,
   including the rule that a corrected quote needs a fresh nonce).
   *Why it exists:* lets the client retry safely *and* lets the server
   detect client bugs.  §3.5 requires prose on the key's reuse
   semantics.
 
 * ``unsafe`` — retries may duplicate effects.  Example:
   ``POST /private/orders`` without an explicit ``order_id`` creates a
   second order.  Must be justified in prose.  *Consumers:* derivation
   tooling surfaces ``unsafe`` mutating methods prominently — in a
   system built on at-least-once networking, an unsafe mutation is a
   design smell.  *Guidance:* prefer having the client supply the
   identifier (``order_id``), which turns ``unsafe`` into
   ``keyed:order_id`` by construction.
 
 7.2 ``:maturity:`` values
 -------------------------
 
 Why this field exists: derivation must know which methods describe
 *behavior* and which describe *intent*.  A documented-but-unimplemented
 endpoint is not a fact about the system; deriving use cases from it
 manufactures fiction.
 
 * ``stable`` — implemented and conformant; fully derivable.
 * ``experimental`` — implemented, but may change without a version
   bump.  Derivable, but derived artifacts are marked experimental.
   Example: nearly all auditor diagnostic endpoints ("still
   experimental" throughout ``api-auditor.rst``).
 * ``draft-no-consumers`` — a spec nothing implements or consumes.
   Examples: the apns relay, ebisync, the bank account directory (all
   self-declared "nothing depends on this API"); sync in practice.
   Excluded from derivation; renders with a banner.
 * ``proposed-unimplemented`` — a documented proposal, explicitly not
   implemented.  Examples: wads, and the reserve-control endpoints
   (``/reserves/$PUB/open|close|attest``) in the exchange API.  Excluded
   from derivation; kept for design reference.
 * ``deprecated`` — still functional, but new derived artifacts must not
   use it; the replacement should be named in prose (and
   ``:deprecated:`` carries the version).
 
 7.3 ``:visible-to:`` values (actor ⇒ implied credential)
 --------------------------------------------------------
 
 This field is the file's single authorization fact.  The design
 decision: the *actor* is declared and the *mechanism* is implied by the
 table below, because declaring both would duplicate one fact in two
 drift-prone places.  Persona projections are computed as closures over
 this field: a persona is a set of actors; its visible surface is the
 set of methods whose ``:visible-to:`` intersects it.
 
 .. list-table::
    :header-rows: 1
 
    * - Actor
      - Implied mechanism
    * - ``wallet-user``
      - wallet-core local message protocol (no credentials; "visibility"
        is possession of the device running the wallet)
    * - ``merchant-staff`` or ``merchant-staff:<scope>``
      - ``Authorization: Bearer secret-token:...`` with the named
        permission scope (``orders-read``, ``transfers-write``, ...)
    * - ``aml-officer`` / ``aml-officer:readonly``
      - ``Taler-AML-Officer-Signature`` header; the ``:readonly``
        variant maps to the officer's read-only access level (the
        ``read_only`` flag in ``GET /aml/$OFFICER_PUB``)
    * - ``exchange-operator``
      - master-key signature (management operations)
    * - ``auditor``
      - auditor API authentication (see ``api-auditor.rst``)
    * - ``tax-auditor``
      - none — capability identifiers only (``wtid``); this actor has
        *no* credentials anywhere in the system
    * - ``bank-customer``
      - external bank UI; on APIs, capability ``withdrawal-id``
    * - ``bank-admin``
      - corebank bearer token (admin scope)
    * - ``kyc-provider``
      - provider webhook credentials
    * - ``any-unauthenticated``
      - none — public by design (``GET /keys``).  Do not confuse with
        capability-gating: public-by-design means the *content* is
        meant for everyone; capability-gated means the *identifier* is
        the secret.
    * - ``external``
      - outside any API (bank statements, PoS displays, offline
        ceremonies) — the honest escape hatch for non-API actors
 
 Capability-gated access is annotated in the field:
 ``:visible-to: merchant-staff, tax-auditor (capability wtid)`` means
 the listed actors hold the unguessable identifier; the lint resolves
 the identifier against the registry (§4.4) and checks its
 ``:capability: yes`` (V3).
 
 7.4 ``:temporality:`` values
 ----------------------------
 
 The classification of an outcome's *kind* — the input that decides
 which column of the derived state table (happy / timer / failure) an
 edge lands in, and whether a non-2xx is a failure at all.
 
 * ``transient-state`` — the condition resolves without the client
   changing anything; the identical request may succeed later.
   Example: 404 ``RESERVE_UNKNOWN`` on an unfunded reserve.
   *Derived as:* a wait/retry edge, not a failure exit.
 * ``terminal`` — will never succeed; abandon or restart the flow.
   Examples: 410 expired purse; 410 already-solved challenge.
   *Derived as:* a failure exit to a terminal documentation state.
 * ``fixable`` — a *modified* request can succeed.  Examples: 409
   insufficient funds (withdraw less); 400 parameter malformed.
   *Derived as:* a failure edge with a return loop after modification.
 * ``rate-limited`` — retry only after the documented delay.  Examples:
   mailbox 429 with the machine-readable ``retry_delay`` field; TAN
   retransmission cooldown.  *Derived as:* a retry edge annotated with
   the delay's source field.
 * ``gate`` — blocked on an action by the user or a third party, outside
   this call.  Examples: 451 KYC required; 202 MFA challenge; 402
   payment-required at sync.  *Derived as:* a gate edge into the
   relevant sub-flow (KYC legitimization, MFA solving).
 * ``progress`` — **not an error**: the non-2xx code is the happy-path
   state signal.  Examples: 402 unpaid + ``taler_pay_uri`` on the order
   status endpoint; 202 pending on deposit tracking; 304 unchanged
   during long-poll.  *Derived as:* **no failure edge** — the code *is*
   the waiting state's observation.
 
 Classification guide (ask in order): Is it actually a failure?  →
 ``progress``.  Can the caller fix the request?  → ``fixable``.  Does
 the condition resolve by itself?  → ``transient-state``.  Does it only
 need a delay?  → ``rate-limited``.  Does it need an outside action?
 → ``gate``.  Will it never succeed?  → ``terminal``.
 
 7.5 ``:recovery:`` values
 -------------------------
 
 The client's forward action — the label on the edge that *leaves* this
 outcome.  ``:temporality:`` says what kind of outcome it is;
 ``:recovery:`` says what to do about it.
 
 * ``retry-same`` — safe verbatim replay (pairs with
   ``:idempotency: replay-safe`` / ``keyed:``; pairing an unsafe method
   with ``retry-same`` is a contradiction the lint should flag).
 * ``retry-modified`` — change the request per the error's guidance
   (lower the amount; add the missing field; set ``max_age`` per the
   ``maximum_allowed_age`` hint).
 * ``retry-after`` — wait the documented delay, then ``retry-same``
   (429 + ``retry_delay``).
 * ``long-poll`` — wait on the status endpoint's rendezvous parameters
   (reserve status long-poll).
 * ``poll-later`` — re-read after some time, without rendezvous (the
   sync backup cadence; usual companion of ``progress``).
 * ``refresh-config`` — re-fetch ``/keys`` or ``/config`` first
   (denomination unknown ⇒ outdated keys).
 * ``start-kyc`` — enter the legitimization sub-flow (451 responses
   carry the requirement).
 * ``user-action`` — the human must act outside this API (confirm in the
   bank app; insert cash).
 * ``abort`` — invoke the flow's own abort path (abort the withdrawal;
   delete the purse).
 * ``give-up`` — terminal; no forward action exists.
 * ``none`` — informational; nothing to recover from.
 
 7.6 ``:timer-ref:`` roles
 -------------------------
 
 A method's relationship to an entity clock comes in three kinds, and
 each feeds a different derivation:
 
 * ``arms`` — a successful call starts the clock; ``:field:`` names the
   arming request field (``POST /private/orders`` arms
   ``order.refund-deadline`` via ``refund_delay``).  *Feeds:* the
   "armed when" column of timer tables.  (Config-armed clocks are the
   exception — declared ``:armed-by:`` at the anchor, §4.3.)
 * ``exposes`` — the response carries the clock's current value;
   ``:field:`` names the response field
   (``ValidationChallengeInfo.solve_expiration``).  *Feeds:* the
   observation layer — where an actor reads the time remaining.
 * ``affected-by`` — the method's behavior changes once the clock fires
   (challenge confirm fails with ``TAN_CHALLENGE_EXPIRED``).
   *Feeds:* the join between the timer's firing edge and this method's
   error table.
 
 One method may reference several timers (one ``:timer-ref:`` each); one
 reference carries one role.
 
 7.7 ``:trigger:`` kinds
 -----------------------
 
 A transition without a cause is narrative; the trigger is what makes
 the machine causal — and what makes the sequence diagram drawable,
 since every trigger kind maps to a diagram element (message, timer
 edge, external note).
 
 * ``call <method>`` — an external call to the owner's API.  Resolvable
   to a method file (V13).  The most common kind.  Example: the wallet's
   selection POST drives ``pending -> selected``.
 * ``timer <entity>.<timer>`` — a declared entity timer fires.
   Resolvable to the §4.3 anchor.  Example: ``solve-expiration`` drives
   ``unsolved -> expired``.
 * ``watch <component>.<observable>`` — the owner watches an external
   source.  This is where *cross-component* causality lives: the
   exchange's wirewatch watching ``bank.incoming-history``; the merchant
   backend tracking the exchange's outgoing wires.  Naming form is
   ``component.observable`` so the join stays checkable.
 * ``external <description>`` — a human or off-API action: bank-UI 2FA
   confirmation, cash inserted at a terminal, an offline key ceremony.
   Non-API actors enter the machine here, honestly marked as outside
   every API.  Deliberately not lint-resolvable.
 
 Triggers are repeatable: one transition may have several (``selected ->
 confirmed`` via the confirm endpoint *or* the bank UI).
 
 7.8 Identifier roles
 --------------------
 
 The method↔identifier relationship declared in **Identifiers:**
 (§3.8): ``creates`` (the value begins to exist here), ``carries``
 (transports it onward in URL/body/response/wire subject), ``reads``
 (uses it as a lookup key), ``consumes`` (its validity ends here).
 Definitions and examples are in §3.8.  The roles are always from the
 *method's* perspective: the same ``reserve_pub`` is created by the
 wallet, carried by the bank-integration selection, read by the exchange
 — and the union of those tags is what V21 checks joins with (exactly
 one creator per carried/read value, or an internal-creation note at the
 anchor).
 
 
 8. Machine-readability rules
 =============================
 
 These rules are the contract between authors and tooling.  Each exists
 because a specific derivation or lint check depends on it; breaking one
 does not merely make the docs sloppy — it makes a specific derived
 artifact silently wrong.  Each rule below states the requirement, why
 it exists, a typical violation, and what checks it.
 
 M8.1  One method per file, one identity directive per file (declared
       variant groups excepted, §2).
 
       *Why:* the file is the unit of indexing — filename conventions
       (§2.2), lint scoping, and generated cross-references all assume
       the path↔method mapping is one-to-one.
       *Violation:* two endpoints documented in one file "because they
       are similar" — their semantics can no longer be addressed
       separately, and backfill tools cannot target them.
       *Checked by:* V1 (count identity directives per file).
 
 M8.2  Every element in §3 marked REQ is present; COND is present or
       the absence is obvious from method kind (e.g. GET ⇒ no Effects).
 
       *Why:* the REQ fields are the minimum derivation set — a missing
       REQ field means the generator must guess (the exact failure this
       specification exists to eliminate).  The COND absence rule exists
       so the lint doesn't cry wolf on legitimately absent sections.
       *Violation:* a POST without ``:idempotency:``.
       *Checked by:* the REQ lint rules (V2, V3, V5, V11, ...).
 
 M8.3  All field values come from the §7 vocabularies — free text is a
       lint error.
 
       *Why:* a misspelled value (``rate_limited`` for
       ``rate-limited``) is invisible to a human reviewer but silently
       removes the entry from every derived table.
       *Violation:* ``:temporality: transient`` (missing ``-state``).
       *Checked by:* V2, V3, V5, V10, and the vocabulary checks.
 
 M8.4  Every name that must resolve, resolves: entity names → registry;
       state values → lifecycle transitions (inferred set); ``:schema:``
       types → ``ts:def`` blocks; ``:timer-ref:`` targets → entity timer
       anchors; ``:identifier:`` names → identifier anchors;
       ``:trigger: call`` refs → method files; ``:trigger: timer`` refs
       → entity timers; notification channels → the component's
       notification page.
 
       *Why:* this rule is what turns the corpus from a pile of pages
       into a graph.  Every derived artifact (state tables, persona
       projections, sequence diagrams) is a traversal of these edges; a
       dangling reference is a broken join that no amount of prose
       repairs.
       *Violation:* ``:observes-state: withdrawal-operation.state``
       (the field is ``status``) — the persona projection for the bank
       customer silently loses the withdrawal states.
       *Checked by:* V7, V8, V9, V10, V12, V13, V21.
 
 M8.5  State values and error codes appear in structured positions
       first; prose mentions are decoration.
 
       *Why:* prose is unparseable.  A state or error that exists only
       in a sentence is invisible to every consumer — the machine has a
       state the tooling cannot see.
       *Violation:* "returns 410 when the purse is gone" in the
       description, with no 410 entry in **Errors**.
       *Checked by:* V14 (grep prose for known state names and
       ``TALER_EC_*`` codes absent from the structured fields).
 
 M8.6  Version annotations follow the single style ``@since **vN**`` /
       ``@deprecated **vN**``.
 
       *Why:* derived artifacts must be sliceable by protocol version —
       an old wallet talking to a new exchange sees a genuinely
       different machine, and only uniform field-level versioning makes
       that computable.  The style already exists as a convention; this
       rule makes it enforceable.
       *Violation:* "since v3" (unparseable variant), missing
       annotations on newer fields.
       *Checked by:* V16 (warn-only until backfilled).
 
 M8.7  Draft APIs carry ``:maturity: draft-no-consumers`` and a visible
       banner; derivation tooling skips them.
 
       *Why:* documented intent is not behavior.  Deriving use cases
       from an API nothing implements manufactures fiction with the
       false authority of a generated artifact.
       *Violation:* a use-case table that includes apns device
       registration as if it were a live flow.
       *Checked by:* V17.
 
 M8.8  The ``ts:def`` layer is the codegen source of truth: type
       definitions must be complete enough to generate client/server
       types and validators without consulting prose.
 
       *Why:* the shape layer is what the spec-first model generates
       code from (§1).  A field that exists only in a sentence ("the
       response also contains X when...") produces a generator-visible
       type that disagrees with the documented behavior — the
       documentation-drift disease, now with a compiler.
       *Violation:* optional fields described only in running text;
       union variants mentioned in prose but absent from the
       ``ts:def``.
       *Checked by:* partially by V4 (every outcome needs a schema);
       fully only by codegen dry-runs diffed against implementations.
 
 
 9. Validation rules (lint specification)
 =========================================
 
 A doc lint (to live in ``taler-docs/_exts/``) enforces, as build
 warnings/errors:
 
 .. list-table::
    :header-rows: 1
 
    * - ID
      - Rule
    * - V1
      - Identity directive present exactly once per documented method
        (variant groups: one directive per variant, §2); options parse.
    * - V2
      - ``:since:`` / ``:deprecated:`` match ``v\d+``; ``:maturity:`` in
        vocab.
    * - V3
      - ``:visible-to:`` present; actors and capability annotations in
        vocab; capability identifiers resolve to identifier anchors.
    * - V4
      - Every ``:http:statuscode:`` has ``:schema:`` and/or ``:error:``;
        non-2xx codes with ``:schema:`` have a ``progress`` or ``gate``
        entry in **Errors**.
    * - V5
      - Every non-2xx outcome has an entry with ``:temporality:`` and
        ``:recovery:`` in vocab.
    * - V6
      - Mutating methods have non-``readonly`` ``:idempotency:`` and at
        least one ``:effect:`` (or explicit "no observable effect" note).
    * - V7
      - Entity names (in Effects, ``:observes-state:``,
        ``:timer-ref:``) resolve to entity anchors; identifier names in
        **Identifiers:** blocks resolve to identifier anchors.
    * - V8
      - State values resolve to the named entity's inferred state set
        (including modifier-expanded sets for wallet transaction
        entities, §6).
    * - V9
      - ``:observes-state:`` path exists in the response ``ts:def`` and
        its type is an enumerated union.
    * - V10
      - ``:timer-ref:`` targets exist among the named entity's declared
        timers; roles in vocab; ``:field:`` present when the role is
        ``arms`` or ``exposes``; every declared timer has at least one
        ``arms`` reference or an ``:armed-by:`` in its anchor.
    * - V11
      - ``:wait:`` present; long-poll parameters match the method's
        documented ``:query:`` parameters.
    * - V12
      - Every real-time channel of a component is declared in that
        component's notification page; no push-channel metadata appears
        in method files.
    * - V13
      - Transition triggers resolve (``call`` → method file, ``timer``
        → declared entity timer, ``watch`` → ``component.observable``
        form); **Effects** transitions and lifecycle transitions agree
        (two-sided check); ``:observable-by:`` refs resolve.
    * - V14
      - No ``TALER_EC_*`` or state value appears only in prose.
    * - V15
      - Filename and location follow §2.2.
    * - V16
      - ``@since`` present on every ``ts:def`` field of public types
        (grandfathered: warn-only until backfilled).
    * - V17
      - ``draft-no-consumers`` / ``proposed-unimplemented`` methods
        render a banner and are excluded from derived artifacts.
    * - V18
      - wallet-core ``:transition:`` values match DD37 notation, resolve
        against the ``TransactionMajorState`` / ``TransactionMinorState``
        enums documented in ``get-transaction-by-id.rst``, and edges
        resolve against the transaction entity lifecycles in the
        registry.
    * - V19
      - Lifecycle integrity: every declared terminal state is reachable
        from ``none`` and absorbing (no outgoing transitions); every
        ``final-reactivatable`` state's outgoing transitions are
        explicitly declared reactivation edges; every inferred
        non-terminal state has at least one outgoing transition; every
        inferred state is reachable from ``none``.
    * - V20
      - ``:if:`` guards reference documented config/data fields
        (best-effort resolvability: ``/keys`` fields, request fields,
        documented config).
    * - V21
      - Identifier joins: every identifier with a ``carries`` /
        ``reads`` tag has exactly one ``creates`` across the corpus or
        an internal-creation note in its anchor; every ``creates`` is
        carried or read somewhere.