@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/examples/docs/services/payment-service/spec.md

@@ -0,0 +1,88 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/
+---
+
+# payment-service
+
+Owns payment authorization and capture. This is the **living spec** — the complete current
+state. Feature deltas (ADDED/MODIFIED/REMOVED requirements) merge in here on `loam archive`;
+`features/archive/` keeps every one of those deltas, so "which change introduced this
+requirement" stays a search rather than a record somebody has to maintain.
+
+## Requirements
+
+### Requirement: Authorize a payment
+
+Requirement-ID: PAY-AUTHORIZE
+The service SHALL reserve funds for an order before capture, and SHALL treat an authorization
+request as idempotent by order id so that a caller's timeout-and-retry never reserves twice.
+
+Operations: authorizePayment
+Publishes: payment.PaymentAuthorized
+Realizes: checkout#CHECKOUT-CHARGE-ONCE
+
+#### Scenario: Successful authorization
+- **Given** an order with a valid payment method
+- **When** authorization is requested
+- **Then** funds are reserved and a `PaymentAuthorized` event is emitted
+
+#### Scenario: A retry of the same authorization returns the first result
+- **Given** an authorization already reserved for order "A-1"
+- **When** the same request arrives again after a caller timeout
+- **Then** the original authorization is returned and no second reservation is made
+
+#### Scenario: A second authorization for the same order with a different amount is refused
+- **Given** an authorization already reserved for order "A-1" of 100.00 USD
+- **When** an authorization of 120.00 USD is requested for the same order
+- **Then** the request is refused with 409 and the first reservation stands
+
+### Requirement: Capture an authorized payment
+
+Requirement-ID: PAY-CAPTURE
+The service SHALL settle a previously authorized payment, and SHALL refuse to capture a payment
+it never authorized.
+
+Operations: capturePayment
+Publishes: payment.PaymentCaptured
+Requires: service/payments:capture
+
+#### Scenario: Capture an authorized payment
+- **Given** an authorized payment
+- **When** capture is requested
+- **Then** the payment is settled and a `PaymentCaptured` event is emitted
+
+#### Scenario: Capturing an unknown payment is refused
+- **Given** a payment id no authorization ever created
+- **When** capture is requested for it
+- **Then** the request is refused with 404 and nothing is settled
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+The service SHALL return captured funds to the customer's payment method, SHALL reconcile the
+refund against the acquirer before reporting it complete, and SHALL refuse a second refund of a
+payment it has already refunded.
+
+Operations: refundPayment
+Publishes: payment.PaymentRefunded
+Requires: user/payments:refund
+
+#### Scenario: Refund a captured payment in full
+- **Given** a captured payment of 100.00 USD
+- **When** a refund is requested for it
+- **Then** 100.00 USD is returned to the customer's payment method
+- **And** the payment is recorded as refunded
+
+#### Scenario: A second refund of the same payment is refused
+- **Given** a payment already refunded in full
+- **When** a refund is requested for it again
+- **Then** the request is refused with 409 and no second refund is issued
+
+#### Scenario: The refund is announced only after the acquirer reconciles
+- **Given** a refund accepted by the acquirer but not yet reconciled
+- **When** the reconciliation completes
+- **Then** `payment.PaymentRefunded` is published exactly once for that payment

package/examples/docs/services/platform/identity-service/adrs/0001-token-introspection-over-local-validation.md

@@ -0,0 +1,60 @@
+---
+id: ADR-identity-service-0001
+status: accepted
+date: 2026-06-02
+service: identity-service
+---
+
+# 1. Introspect tokens centrally instead of validating them locally
+
+## Context
+Every service in the fleet has to decide whether a caller's token is good. The
+original answer was `GET /tokens/{token}/valid` (`validateToken`): a boolean, cheap
+to call, and cheap to cache — which is precisely what made it wrong.
+
+The endpoint answered from the token's signature and expiry, so it could only ever
+say "this was issued by us and has not expired yet". It could not say "this client
+was revoked eleven minutes ago". A revoked client therefore kept transacting until
+its token's natural expiry, and lengthening token lifetimes — the obvious fix for the
+load this endpoint put on the key store — made the revocation window longer in exact
+proportion.
+
+The boolean was also a dead end for authorization: a caller that needs the subject
+and the scopes has to fetch them somewhere, and every consumer had begun decoding the
+token itself to get them. Two services were already trusting claims they had not
+verified.
+
+## Decision
+`POST /tokens/introspect` (`introspectToken`) is the single answer, in the shape of
+RFC 7662: it returns `active` computed from **revocation state**, together with the
+subject and scopes, and an unknown, expired or revoked token is `{"active": false}`
+with a 200 rather than a 4xx — the caller asked a question and got an answer.
+
+`validateToken` is marked `deprecated: true` in `openapi.yaml` and keeps working. Its
+verdict is now computed the same way as introspection's, so the two can never
+disagree; only its response shape stays frozen.
+
+Introspection is gated on `service/tokens:introspect` and served from a short-TTL
+cache. Both obligations are written down where a test can be generated from them —
+`IDN-INTROSPECT` in `spec.md` for the permission, `ARCH-INTROSPECT-CACHE` in
+`arch.spec.md` for the cache's TTL, its invalidation on revocation, and its fallback.
+
+## Consequences
+- Revocation propagates within the cache TTL instead of within a token lifetime.
+- Every consumer now makes a network call where it used to decode locally, which is
+  why the cache and its single-flight behaviour are architecture requirements rather
+  than an implementation detail; the stampede failure mode is in `runbook.md`.
+- `validateToken` is deprecated rather than deleted, and that is a deliberate,
+  visible state rather than a decision postponed. payment-service still calls it —
+  the landscape edge `paymentService -> identityService` carries
+  `metadata { op 'validateToken' }` — so deleting the operation would break a
+  consumer with nothing having proposed the break. Instead the flag makes the
+  migration legible to `loam validate`: `spine.op-deprecated` names the consumer that
+  has not moved, and `api.requirement-deprecated` names `IDN-VALIDATE-LEGACY` as
+  behaviour on its way out. Both warnings stay until the migration is finished, and
+  they are how anyone can see it is not.
+- Retirement is an explicit change, not a cleanup: a feature delta carries
+  `x-loam-remove: true` inside the operation in
+  `features/<FEAT>/specs/identity-service/openapi.yaml` plus a `REMOVED` requirement
+  naming `validateToken`, and `loam archive` deletes the operation and the
+  requirement together. That is the step that ends this ADR's transitional state.

package/examples/docs/services/platform/identity-service/arch.spec.md

@@ -0,0 +1,117 @@
+---
+service: identity-service
+status: draft
+owner: platform-identity
+sources:
+  - internal/tokens/
+  - cmd/
+---
+
+# identity-service — architecture spec
+
+The **living architecture spec**: the obligations no business scenario was ever going
+to carry. Nothing in `spec.md` mentions key rotation or a cache TTL, because a caller
+exchanging credentials for a token cannot observe either — and those are exactly the
+places a coding agent cuts a corner unless the obligation is written where a test can
+be generated from it.
+
+Same grammar as `spec.md`, and one line more: `Covers:` is the architecture analog of
+`Operations:`. Where a business requirement declares the operations it governs, an
+architecture requirement declares the model objects its scenarios exercise — a C4
+element id, an edge `source -> target`, or a health signal `sli:<id>` / `alert:<id>`.
+`loam validate` grades the join in both directions: an entry that resolves to nothing
+is `covers.unknown` (a mistyped id silently costs exactly the coverage it was written
+for), and an SLI or alert in `health.yaml` that no requirement here covers is
+`health.uncovered`. Every id below comes from `model.likec4` or `health.yaml` in this
+directory; nothing here reaches for the landscape, because everything this service
+touches is inside its own boundary.
+
+## Requirements
+
+### Requirement: Signing keys rotate without invalidating live tokens
+
+Requirement-ID: ARCH-KEY-ROTATION
+The service SHALL keep the previous signing key verifiable for at least one full
+token lifetime after promoting a new one, and SHALL never sign with a key that is
+not already readable, from the key store, by every instance that answers
+introspection. Rotation that flips both halves at once invalidates every token in
+flight — an outage of the whole fleet, produced by a routine maintenance job, which
+is why the overlap is a requirement and not a runbook note. The second half is the
+one a single-instance test never catches: the signer and the verifier are different
+processes reading the same store, and a key promoted before it lands there makes
+one instance mint tokens the others report inactive.
+
+Covers: identityService.keyStore, identityService.tokens -> identityService.keyStore
+
+#### Scenario: A rotation keeps tokens minted a minute earlier verifiable
+- **Given** the active key K1 and tokens issued under it with thirty minutes of life left
+- **When** K2 is promoted to active
+- **Then** new tokens are signed with K2
+- **And** tokens signed with K1 keep verifying until the last of them has expired
+
+#### Scenario: A key is readable by every instance before it signs anything
+- **Given** a newly generated key that is not yet in the key store the other instances read
+- **When** the rotation job runs
+- **Then** the key is written to the key store first and only then promoted to active
+- **And** no token is ever signed with a key another instance could not verify
+
+#### Scenario: Rotation is refused while the key store is unreachable
+- **Given** the key store is unavailable
+- **When** the rotation job runs
+- **Then** it fails without promoting anything and the previous active key stays in use
+- **And** the fleet keeps issuing tokens rather than half-rotating
+
+### Requirement: Introspection is cached, and the cache cannot outlive a revocation
+
+Requirement-ID: ARCH-INTROSPECT-CACHE
+The service SHALL answer introspection from a cache whose entries expire within the
+revocation propagation budget, SHALL delete a token's entry when that token is
+revoked, and SHALL fall back to the key store when the cache is unavailable. The
+cache holds derived state only: losing it costs latency, never correctness, and any
+design where a cache miss can produce a *different verdict* is the bug this
+requirement exists to prevent.
+
+Covers: identityService.introspectionCache, identityService.tokens -> identityService.introspectionCache
+
+#### Scenario: A revocation invalidates the cached verdict immediately
+- **Given** a token whose active verdict is cached
+- **When** its client is revoked
+- **Then** the cached entry is deleted as part of the revocation
+- **And** the next introspection of that token reports inactive
+
+#### Scenario: A cache entry cannot outlive the propagation budget
+- **Given** a cached verdict written thirty seconds ago
+- **When** it is read after its TTL has elapsed
+- **Then** it is treated as a miss and the verdict is recomputed from revocation state
+
+#### Scenario: The cache being down degrades latency, not the answer
+- **Given** the introspection cache is unreachable
+- **When** a token is introspected
+- **Then** the verdict is computed from the revocations in the key store and is unchanged
+- **And** the service stays available, paying for the miss in introspection latency alone
+
+### Requirement: Token issuance is measured and paged
+
+Requirement-ID: ARCH-ISSUE-HEALTH
+The service SHALL export an availability and an issuance-latency SLI, and SHALL page
+the identity on-call when issuance starts returning server errors. Issuance failing
+is the one fault every other service in the fleet experiences as its own, so it is
+paged rather than dashboarded.
+
+Covers: sli:availability, sli:token_issue_latency_p99_ms, alert:token_issue_5xx
+
+#### Scenario: Both SLIs are exported while the service serves traffic
+- **Given** the service is serving token requests
+- **When** its metrics endpoint is scraped
+- **Then** `availability` and `token_issue_latency_p99_ms` report values against their SLOs
+
+#### Scenario: Sustained issuance errors page the identity on-call
+- **Given** more than 0.5% of token issuance requests return a server error over five minutes
+- **When** the alert rules are evaluated
+- **Then** `token_issue_5xx` pages the identity on-call
+
+#### Scenario: An instance that cannot sign takes no traffic
+- **Given** an instance whose active signing key failed to load
+- **When** the readiness check is evaluated
+- **Then** it reports not ready and is removed from the pool
+- **And** the failure never reaches a caller as a server error

package/examples/docs/services/platform/identity-service/health.yaml

@@ -0,0 +1,70 @@
+# Service health model: the signals this service promises to emit and the pages it
+# promises to send. Targets and queries are authored here; the dependency graph
+# comes from C4. Planned: `loam health` composes these across the fleet into a
+# cascade / blast-radius view.
+#
+# `loam validate` reads exactly three things out of this file, all of them ids:
+#
+#   * each `slis[].name` — every one wants a `Covers: sli:<id>` line in
+#     arch.spec.md, or `health.uncovered` says nothing tests the signal, and a
+#     signal nothing tests is dashboard decoration;
+#   * each `alerts[].name` — same obligation, through `Covers: alert:<id>`;
+#   * each `dependencies[]` id — which must resolve in this service's OWN
+#     model.likec4, or `health.dependency-unmodelled` fires.
+#
+# Queries, thresholds, pages and the checks below are authored prose that no check
+# reads. They are here because the on-call engineer reads them.
+service: identity-service
+status: draft
+
+slis:
+  - name: availability
+    # Every service that accepts a token calls this one, so this number is a
+    # ceiling on the fleet's: the 0.05% it permits is spent by every consumer at
+    # once. That is why it is set a notch tighter than payment-service's 0.999
+    # rather than matching it — a shared dependency cannot hold the same budget
+    # as the services depending on it and leave them any of their own.
+    query: "sum(rate(http_requests_total{job='identity-service',code!~'5..'}[5m])) / sum(rate(http_requests_total{job='identity-service'}[5m]))"
+    slo: 0.9995
+  - name: token_issue_latency_p99_ms
+    # Issuance alone, not introspection: minting signs with the active key and is
+    # the slow path, while introspection answers from cache. Averaging the two
+    # would let a signing stall hide behind cache hits.
+    query: "histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{job='identity-service',path='/tokens'}[5m]))) * 1000"
+    slo: 150
+
+alerts:
+  - name: token_issue_5xx
+    # Pages on issuance failing, which is the failure every other service feels as
+    # its own: a caller that cannot get a token cannot call anybody.
+    #
+    # A RATIO, not a raw error rate: ARCH-ISSUE-HEALTH promises a page at "more
+    # than 0.5% of token issuance requests", and `rate(5xx) > 0.005` would instead
+    # page at one error every 200 seconds — a threshold that means one thing at
+    # 10 rps and something else entirely at 1000. The five minutes the scenario
+    # names live in the range vector, so there is no second `for:` delay under it
+    # making the page later than the requirement says it comes.
+    expr: "sum(rate(http_requests_total{job='identity-service',path='/tokens',code=~'5..'}[5m])) / sum(rate(http_requests_total{job='identity-service',path='/tokens'}[5m])) > 0.005"
+    page: identity-oncall
+
+checks:
+  liveness: GET /healthz
+  # Readiness fails while the active signing key cannot be loaded: an instance that
+  # is up and cannot sign should take no traffic, because it turns every issuance
+  # into a 5xx and burns the alert above instead of being rolled out of the pool.
+  readiness: GET /readyz
+
+# There is deliberately NO `dependencies:` key here, and this comment is the
+# difference between that fact and a forgotten section. identity-service is the
+# fleet's root of trust: it calls no other service, publishes to no broker and
+# reaches no third party, so it is named in other services' dependency lists
+# (payment-service carries it as `degradable`) and names none of its own. Its two
+# stores are inside its own boundary in model.likec4 (a private store nested in
+# the service, never a fleet-level peer) and share its lifecycle rather than being
+# something it depends on across a boundary.
+#
+# The day that stops being true, the new entry has to be drawn in
+# services/identity-service/model.likec4 as well — resolution is against this
+# service's own model and never the landscape, because the landscape carries only
+# what crosses the service boundary while the model carries everything the service
+# touches, and the model is the set an on-call file has to agree with.

package/examples/docs/services/platform/identity-service/model.likec4

@@ -0,0 +1,83 @@
+// The identity-service C4 model: the containers behind the token API and the
+// two stores they reach.
+//
+// The `specification` block is repeated in every .likec4 file on purpose. loam
+// parses each document ALONE — it never stitches this file to
+// architecture/landscape.likec4 before reading it — so a kind declared only in
+// the landscape would resolve in the LikeC4 workspace and fail here, and the
+// failure surfaces as `c4.invalid` on a file whose text looks perfect.
+specification {
+  element softwareSystem
+  element container
+  element database
+}
+
+model {
+  identityService = softwareSystem 'identity-service' {
+    description 'Issues the access tokens the rest of the fleet presents, and answers whether one is still good'
+    // The binding — not the title — is what ties this element to
+    // services/identity-service/. With a title alone, renaming the box to
+    // 'Identity' would silently stop every join that reads this file (health
+    // dependencies, `Covers:` entries, the landscape spine) while `loam
+    // validate` stayed green, because a title that fails to match is only a
+    // guess at a binding and is graded as one.
+    metadata {
+      service 'identity-service'
+    }
+
+    api = container 'api' {
+      description 'HTTP surface: POST /tokens, POST /tokens/introspect, GET /tokens/{token}/valid'
+      technology 'Go'
+    }
+    tokens = container 'tokens' {
+      description 'Mints and signs tokens, and turns a recorded revocation into an inactive verdict'
+      technology 'Go'
+    }
+    // Everything durable is in ONE store on purpose, and the description says
+    // which things, because two documents downstream depend on it: the cache
+    // requirement in arch.spec.md falls back HERE for a verdict, and the
+    // stampede in runbook.md is issuance and introspection contending for this
+    // store's connection pool. Naming only the signing keys here would leave
+    // both of them reaching for state nothing in this model holds.
+    keyStore = database 'key-store' {
+      description 'Signing keys and their rotation state, the client registry, and the revocations a verdict is computed from — the only durable state this service owns'
+      technology 'PostgreSQL'
+    }
+    // Derived state, so a plain container rather than a `database`: losing every
+    // byte in here costs latency and never correctness, and ARCH-INTROSPECT-CACHE
+    // in arch.spec.md is the requirement that says so in a scenario.
+    //
+    // Both stores stay NESTED inside the service boundary. Lifting either into
+    // architecture/landscape.likec4 as a peer is `landscape.datastore-private`:
+    // drawn at fleet level a store reads as a system in its own right, available
+    // for somebody else's service to depend on, which is the one coupling that is
+    // hardest to undo once a second team believes the picture.
+    introspectionCache = container 'introspection-cache' {
+      description 'Short-TTL introspection verdicts, keyed by token id'
+      technology 'Redis'
+    }
+
+    api -> tokens 'Issues tokens, answers introspection and the legacy check'
+    // These three edges are the WHOLE runtime graph of this service:
+    // identity-service is the fleet's root of trust and calls nothing outside
+    // its own boundary, which is why health.yaml carries no `dependencies:`
+    // key. They still have to be drawn — with four nested elements and no edge
+    // joining any of them this model is `c4.no-relationships`, on the grounds
+    // that parts which reach nothing are almost never the truth. (The check is
+    // evidence-gated: one lone container proves nothing and stays silent, which
+    // is why the warning is about a model this shape and not about any model.)
+    tokens -> keyStore 'Signs with the active key; rotation promotes the next; introspection reads keys and revocations back'
+    tokens -> introspectionCache 'Caches introspection verdicts, invalidates on revocation'
+  }
+}
+
+// Views belong to LikeC4's renderer; no loam check reads anything below. One
+// view is enough here because the whole model fits inside one boundary — the
+// landscape splits its views only because a fleet-wide `include *` is the page
+// nobody can read.
+views {
+  view identity_service of identityService {
+    title 'identity-service — containers'
+    include *
+  }
+}

package/examples/docs/services/platform/identity-service/openapi.yaml

@@ -0,0 +1,197 @@
+# The HTTP contract. `operationId` is the join token that ties this file to the
+# other two axes: a landscape edge says `metadata { op 'introspectToken' }` and a
+# requirement says `Operations: introspectToken`, and all three spellings must be
+# byte-identical or the join is silently empty.
+#
+# loam reads operationIds from the eight HTTP methods of a path item and nowhere
+# else — an id parked under a vendor extension (`x-legacy:`) does not exist as far
+# as every check here is concerned, because a phantom id would mask a real
+# contract break rather than document one.
+openapi: 3.1.0
+info:
+  title: identity-service
+  version: "2.0"
+  description: >-
+    Token issuance and introspection for the marketplace fleet. Every service that
+    accepts a caller's token resolves it here; nothing in this contract calls out.
+
+paths:
+  /tokens:
+    post:
+      operationId: issueToken
+      summary: Exchange client credentials for a signed access token
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenRequest'
+      responses:
+        "201":
+          description: A signed token, valid until its stated expiry
+          # Every operation needs at least one response declaring
+          # `content: <media>: schema:` — without one, `openapi.response-undescribed`
+          # says the contract names the operation and nothing about what it
+          # returns, so a reader still has to open the code. 204 and 304 are the
+          # only codes excused, since neither carries a body.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccessToken'
+        "401":
+          description: The credentials did not authenticate
+          # A declared 4xx/5xx is a promise about a refusal, and loam grades it as
+          # one: this exact number must appear as a bare number inside the body of
+          # a scenario belonging to a requirement whose `Operations:` line names
+          # issueToken, or `api.response-ungoverned` fires. IDN-ISSUE's
+          # "unknown client" and "revoked secret" scenarios are where 401 is paid
+          # for — written as scenarios rather than prose, because a scenario is
+          # what `loam gherkin` turns into a test.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthError'
+
+  /tokens/introspect:
+    post:
+      operationId: introspectToken
+      summary: Report whether a token is currently active and what it grants
+      description: >-
+        The authoritative answer, computed from revocation state — not from the
+        token's signature, which stays valid for the whole of a revoked token's
+        remaining lifetime.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/IntrospectionRequest'
+      responses:
+        # RFC 7662's shape, deliberately: an unknown, expired or revoked token is
+        # `{"active": false}` with a 200, never a 4xx. There is consequently no
+        # failure code to govern here, and `api.response-ungoverned` has nothing
+        # to say about this operation.
+        "200":
+          description: The verdict for the presented token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Introspection'
+
+  /tokens/{token}/valid:
+    get:
+      operationId: validateToken
+      summary: Legacy boolean validity check
+      # `deprecated: true` is standard OpenAPI, and loam turns it into lifecycle
+      # visibility on the spine rather than leaving migration state to a wiki.
+      # Two findings come out of this one line, both warnings, both wanted here:
+      #
+      #   * `spine.op-deprecated` — the landscape's
+      #     `paymentService -> identityService` edge carries
+      #     `metadata { op 'validateToken' }`, and payment-service has not moved
+      #     yet. The finding is filed against the PROVIDER (this service, the
+      #     edge's target) because the contract lives here, and it names the
+      #     consumer that still has to migrate — one warning per inbound edge, so
+      #     a deprecated operation nobody calls stays silent.
+      #   * `api.requirement-deprecated` — IDN-VALIDATE-LEGACY governs only this
+      #     operation, so the behaviour it describes is on its way out.
+      #
+      # Deprecation is the FIRST step of retiring an operation, never the removal
+      # itself: the op stays defined and callable, because deleting it here would
+      # break payment-service's edge with nothing having proposed the break. The
+      # step that ends this state is a feature delta, and its recipe is written
+      # once, in adrs/0001-token-introspection-over-local-validation.md.
+      deprecated: true
+      parameters:
+        - name: token
+          in: path
+          required: true
+          description: The opaque token id being checked
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Whether the token is currently valid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LegacyValidity'
+
+components:
+  # Every schema this document references lives here, in the same file. An
+  # external `$ref` is out of scope on this axis — it does not travel with the
+  # contract when the contract is read on its own — and an internal one that
+  # points at nothing is `openapi.ref-unresolved`: the operation validates while
+  # its payload is silently absent, which reads exactly like a complete contract.
+  schemas:
+    TokenRequest:
+      type: object
+      required: [clientId, clientSecret]
+      properties:
+        clientId:
+          type: string
+        clientSecret:
+          type: string
+          format: password
+        scope:
+          type: string
+          description: Space-separated scopes; the issued token carries the intersection with what the client is granted
+    AccessToken:
+      type: object
+      required: [accessToken, tokenType, expiresIn]
+      properties:
+        accessToken:
+          type: string
+        tokenType:
+          type: string
+          const: Bearer
+        expiresIn:
+          type: integer
+          description: Seconds until expiry, counted from issuance
+        scope:
+          type: string
+    AuthError:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+          # One value, on purpose: the refusal must not tell a caller whether the
+          # client id exists. IDN-ISSUE's two 401 scenarios are what hold that
+          # promise, and this enum is what makes breaking it a contract change.
+          enum: [invalid_client]
+        errorDescription:
+          type: string
+          description: Human-readable, never distinguishing an unknown client from a bad secret
+    IntrospectionRequest:
+      type: object
+      required: [token]
+      properties:
+        token:
+          type: string
+    Introspection:
+      type: object
+      required: [active]
+      properties:
+        active:
+          type: boolean
+        sub:
+          type: string
+          description: The client the token was issued to; absent when inactive
+        scope:
+          type: string
+        exp:
+          type: integer
+          description: Expiry as seconds since the epoch; absent when inactive
+    LegacyValidity:
+      type: object
+      required: [valid]
+      properties:
+        valid:
+          type: boolean
+        expiresAt:
+          type: string
+          format: date-time
+          description: >-
+            The only field this legacy shape carries beyond the boolean. Callers that
+            need scope or subject have to use introspectToken; this schema is frozen.