@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/documentation/io.md

@@ -1,9 +1,9 @@
 # I/O restrictions
 
 The Exposition comes with `io` directives to control access to the operation's input and output
-properties.
+properties, and to let an operation state the status of its reply.
 
-## `io:input`
+## Input
 
 The `io:input` optional directive contains a list of properties that are allowed to be specified in
 the request body.
@@ -22,7 +22,7 @@ not in the list, the request will be rejected with a `400` status code.
 > Therefore, `io:input` is only applicable to operations which input is an object or an
 > array of objects.
 
-## `io:output`
+## Output
 
 The `io:output` mandatory directive contains a list of properties that are allowed to be included in
 the response body.
@@ -53,4 +53,115 @@ GET:
   io:output: false
 ```
 
-Output restrictions are not applied to stream responses and errors.
+Output restrictions are not applied to stream responses, nor to a reply the gateway built out of an
+exception — an operation that returns an error is answered with a code and a message of the
+gateway's own, and a list of permitted properties has nothing to say about those. A reply the
+operation returned is restricted whatever status it carries, see [Status](#status).
+
+## Status
+
+The `io:status` optional directive names a property of the reply that carries the status of the
+response. The property is removed from the body.
+
+```yaml
+POST:
+  endpoint: register
+  io:status: status
+  io:output: [client_id, client_name, error, error_description]
+```
+
+```javascript
+return { status: 400, error: 'invalid_redirect_uri' }
+```
+
+```http
+400 Bad Request
+
+error: invalid_redirect_uri
+```
+
+A reply that does not carry the property is answered with the status it would have been. A property
+that is not a number is an error.
+
+This is for an outcome the operation knows and the transport does not — a protocol that states its
+error as a body rather than as a status of its own, or a request that created where it might have
+updated. Such an operation returns no error: both replies are its output, and `io:output` permits
+the properties of both. An operation that does return an error is unaffected — that reply is the
+gateway's, and is not restricted.
+
+## Throttling
+
+The `io:throttle` directive limits the rate of requests meeting the specified criteria.
+
+```yaml
+exposition:
+  /:
+    io:throttle:
+      key:
+        - route
+        - ip
+      condition:
+        status: 404
+      requests: 500
+      interval: 30
+```
+
+Requests are metered per `key`. A key may spend `requests` at once, and earns them back at a rate of
+`requests` per `interval` seconds. A request carrying a key with nothing left to spend is answered
+`429 Too Many Requests`, with a `Retry-After` saying how long until one would be admitted again.
+`interval` is in seconds.
+
+So `requests` is the burst, and `requests / interval` the rate it is repaid at. There is no window to
+save a budget up in and spend twice across the edge of, and no lockout to sit out: a key that has
+overspent is admitted again as soon as it has earned a single request back, and a client that keeps
+asking meanwhile is not penalised for it.
+
+`requests` is a budget for the **whole group** of gateway instances, not for one of them. Instances
+reconcile through Redis on a timer, so they converge on one number rather than each enforcing the
+limit separately. Between two of those, an instance goes on what it alone has spent — so the group
+can overshoot by what the other instances admit within that window, and by no more. The window is a
+tenth of `interval`, between a quarter of a second and two seconds, whatever `interval` is. Precise
+per-request enforcement is not what this is for.
+
+An instance that cannot reach Redis keeps throttling on what it has seen itself and keeps serving,
+and reports what it could not the next time it gets through.
+
+### Key components
+
+What a request is metered against. Give one, or a list — a list keys on the combination, so
+`[route, ip]` meters each address separately on each route.
+
+- `ip` — the client address, as the request context resolved it. See [Client address](ip.md) for
+  where it is read from and why.
+- `path` — the path the request came in on, `/users/1`.
+- `route` — the route as declared, `/users/:id`. Every path matching the route shares one budget,
+  which `path` cannot do: keyed on `path`, walking ids is a way around the limit.
+- `identity` — the authenticated identity. Requests carrying none share a single budget between
+  them, so pair it with `ip` if that matters.
+- `segment: <name>` — the value bound to a named route segment, `1` for `:id` in `/users/:id`.
+
+### Conditions
+
+What is metered, as opposed to what it is metered against. A request that fails a condition is served
+and costs nothing. Conditions are evaluated against the response, so they cannot decide whether to
+refuse a request — only whether it is charged for, once it has been answered.
+
+- `status: <code>` — charge only for responses with this status.
+
+```yaml
+io:throttle:
+  key: ip
+  condition:
+    status: 404
+  requests: 20
+  interval: 600
+```
+
+An address may probe for twenty missing paths at once, and thereafter for one every thirty seconds.
+Requests that find something are served and never counted against it.
+
+## Introspection
+
+What these admit is what [`OPTIONS`](introspection.md) states: `io:input` restricts the input
+schema, `io:output` the output schema, and a method declaring no `io:output` states no output at
+all — nothing of the reply is sent.

package/documentation/ip.md

@@ -0,0 +1,24 @@
+# Client address
+
+The address a request comes from is resolved once, into the request context, and read from there
+by whatever keys on it: the meter of [failed authentications](identity.md#failed-authentications)
+and the `ip` key of [`io:throttle`](io.md#key-components).
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  ip: cf-connecting-ip
+```
+
+`ip` names the header the address is read from. In production the gateway sits behind a load
+balancer, an ingress or a CDN: the connection it accepts comes from that machine, so every client
+shares one address and nothing tells them apart. The edge is the one that saw the client connect,
+and it writes the client's address into a header of its own, `CF-Connecting-IP`, `X-Real-IP` or
+`X-Forwarded-For`, depending on the infrastructure. A client may send any of these headers too, so
+the gateway trusts none of them on its own: the deployment names the one its edge overwrites, and
+where the header holds a list, the last value is the one the edge appended.
+
+The connection's address is never used. Without `ip`, or for a request that does not carry the
+header, the request has no address: the bouncer and a throttle keyed on `ip` let it through and
+say so in the log, once per hundred seconds rather than once per request.

package/documentation/map.md

@@ -0,0 +1,123 @@
+# HTTP context mapping
+
+The `map` directive family is used to map HTTP request parts to operation call input properties.
+
+[Features](../features/map.feature).
+
+## TL;DR
+
+```yaml
+exposition:
+  /:group:
+    languages: [en, fr] # supported languages
+    GET:
+      map:authority: hostname # request authority (e.g., hostname)
+      map:language: lang # requested language
+      map:headers: # raw header values
+        token: x-access-token
+      map:buffer: body # unparsed request body
+      map:segments: # route parameters
+        group: group
+      map:claims: # Bearer token claims
+        address: email
+        verified: email_verified
+      endpoint: observe
+```
+
+The operation input type must be an object.
+If the input already contains the specified keys, they will be overwritten.
+
+## Authority
+
+The `map:authority` directive maps the [authority identifier](authorities.md) to an operation call
+input property specified by the directive value.
+
+### Language
+
+The `map:language` mapping sets the [most matching](https://github.com/jshttp/negotiator) language
+code based on the `accept-language` request header and a list of supported languages defined by
+the `map:languages` directive, and also adds `accept-language` to the `Vary` HTTP response header
+value.
+
+If none of the supported languages match, the first supported language is used.
+
+> `map:languages` has a shorthand form: `languages: [en, fr]`.
+
+## Header values
+
+The `map:headers` directive maps the values of HTTP request headers to operation call input
+properties.
+The value of the directive is a map where keys are the names of the input properties and values are
+the names of the HTTP request headers.
+
+The names of these headers are then included in the `Vary` HTTP response header
+and [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
+of the [CORS](protocol.md#cors).
+
+[Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are combined
+as a comma-separated list.
+
+## Raw body
+
+The `map:buffer` directive maps the unparsed request body to an operation call input property.
+The directive value is the name of the input property.
+
+```yaml
+/webhook:
+  POST:
+    map:buffer: body
+    map:headers:
+      signature: x-signature
+    endpoint: verify
+```
+
+The body is read from the request stream as raw bytes and delivered as a UTF-8 string.
+
+Body parsing is bypassed, so the route does not depend on a supported `Content-Type` or format decoding. The request stream is consumed; a route with `map:buffer` cannot also receive a parsed body from the same request.
+
+## Route parameters
+
+The `map:segments` directive maps the values of route parameters to operation call input properties.
+The value of the directive is a map where keys are the names of the input properties, and values are
+the names of the route parameters.
+
+Parameter name may be prefixed with `~`
+to indicate that the parameter should not be available to the
+remaining directives or used as criteria in the operation call.
+
+```yaml
+/:id/:tag:
+  POST:
+    map:segments:
+      id: id
+      tag: ~tag
+    endpoint: create
+```
+
+Wildcard routes are supported by using `**` as the parameter name.
+
+```yaml
+/path/to/**:
+  GET:
+    map:segments:
+      path: '**'
+    endpoint: observe
+```
+
+## Bearer token claims
+
+The `map:claims` directive maps the values of
+the [token claims](https://datatracker.ietf.org/doc/html/rfc7519#section-4).
+The value of the directive is a map where keys are the names of the input properties and values are
+the names of the claims.
+
+If the claim is not present in the token or the request is not authenticated using
+the [`Bearer` scheme](identity.md#bearer-scheme), the input properties are not set.
+
+## Introspection
+
+A property a mapping fills is not the caller's to send, so [`OPTIONS`](introspection.md) takes it
+out of the input. `map:headers` states it under `headers`, naming the header it is read from, and
+`map:segments` under `route`, named as the property rather than as the segment. The rest —
+`map:claims`, `map:authority`, `map:language`, `map:buffer` — come from the request itself, and a
+caller has nowhere to put one.

package/documentation/mcp.md

@@ -0,0 +1,183 @@
+# Model Context Protocol
+
+An application annotates it, and the methods it names as tools are what a model may call.
+
+```yaml
+exposition:
+  mcp:
+    name: Teapots
+    instructions: A pot is read by its id. A pot that is brewing cannot be emptied.
+    origins: [https://claude.ai]
+```
+
+<dl>
+<dt><code>name</code></dt>
+<dd>Required. What the server calls itself, which a client shows a user.</dd>
+<dt><code>instructions</code></dt>
+<dd>What a model is told before it calls anything here.</dd>
+<dt><code>origins</code></dt>
+<dd>Browser origins the endpoint answers. A request carrying an <code>Origin</code> that is not
+listed is <code>403</code>, and an empty list admits none; a request carrying none is unaffected.</dd>
+<dt><code>anonymous</code></dt>
+<dd>Whether the endpoint answers without a credential. It does not unless it says so.</dd>
+</dl>
+
+Without the annotation `/.mcp` is a path like any other, and nothing answers there. The path is
+fixed: one an application could choose is one it could collide with a route of its own.
+
+## What a tool is
+
+A tool is an RTD method that says it is one, named as the [procedure](rpc.md#the-name) it is:
+
+```yaml
+/pots:
+  GET:
+    mcp:tool: true
+    help:method: Every pot there is, newest first.
+    endpoint: enumerate
+  /hot:
+    GET:
+      query: { criteria: temperature=gt=80 }
+      mcp:tool: true
+      help:method:
+        title: Hot pots
+        description: The pots that are too hot to pour.
+      endpoint: enumerate
+```
+
+A default denies, and a tree holds everything an application serves — its identity endpoints, its
+uploads, the machinery of the authorization flow the model already came through. Publishing all of
+it would spend a model's context on what it has no business calling.
+
+`mcp:tool` says only whether the method is published. What the tool is called and what it is for is
+[`help:method`](help.md), which is what describes the method everywhere else as well — a tool a
+model cannot read the purpose of is one it cannot choose, so declare one beside the other.
+
+A declaration is inherited by everything below it, as every directive is, and the nearer one wins —
+so a node publishes a subtree, and `mcp:tool: false` withdraws one method of it.
+
+A route whose name a client [cannot spell](rpc.md#what-has-a-name) is refused where the directive
+is built, rather than served as a tool that is quietly never listed.
+
+`tools/list` answers every published method this caller may reach — a method whose directives refuse
+them is not listed, and a route with [no name](rpc.md#what-has-a-name) is not either. `tools/call`
+answers `404` to a name that is not published, whether or not a route would have taken it: what an
+application did not publish is not reachable by guessing what it would have been called.
+
+`annotations` are read from the verb: `GET` and `HEAD` are `readOnlyHint`, `DELETE` is
+`destructiveHint`, `PUT` and `DELETE` are `idempotentHint`.
+
+## What a tool takes
+
+`inputSchema` is the procedure's `params`, which is what the method
+[says of itself](introspection.md): a route variable by the name the template gives it, the
+querystring under `query`, and what is left is the body. `io:input` restricts it, and a property
+`map` fills is not there — a call carries no headers of its own.
+
+`query` carries what selects records — `criteria`, `sort`, `limit`, `omit`, `search` — beside the
+parameters the resource declares. `OPTIONS` states only the latter, because the former is the same
+of every queryable resource; here it is stated, because here it is something the caller sends.
+
+```yaml
+type: object
+properties:
+  id: { type: string, pattern: ^[a-fA-F0-9]{32}$ }
+  query:
+    type: object
+    properties:
+      criteria: { type: string }
+      sort: { type: string }
+      limit: { type: integer, minimum: 1, maximum: 100, default: 10 }
+      omit: { type: integer, minimum: 0, maximum: 1000, default: 0 }
+required: [id]
+additionalProperties: false
+```
+
+## What a tool answers
+
+`content` carries one `text` block holding the reply's JSON, and `structuredContent` the reply
+itself. A reply of nothing is an empty `content`.
+
+`outputSchema` is what the operation declares, restricted by `io:output`. An operation's `output` is
+optional and normalizes to `{}`, which describes nothing, and none is stated for it — an
+application that wants the schema declares the operation's `output`.
+
+An operation that refuses answers a result with `isError: true` carrying its message, not an error
+of the protocol: it is something a model reads and may correct itself by.
+
+## Two revisions
+
+Both are answered from one endpoint that remembers nothing between requests.
+[`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28) carries the version and
+the client's capabilities in every request; `2025-11-25` opens with `initialize`. Which one a
+request is, is read from `MCP-Protocol-Version`, or from
+`_meta['io.modelcontextprotocol/protocolVersion']` where the header is absent; `initialize` is one
+by itself, and a request naming no version is of a revision that sent none.
+
+| method                      |                                                                            |
+| --------------------------- | -------------------------------------------------------------------------- |
+| `server/discover`           | what is served, and who serves it                                          |
+| `tools/list`                | every tool this caller may reach, in a stable order                        |
+| `tools/call`                | the call the tool is                                                       |
+| `initialize`                | the same as `server/discover`, in the shape a client of `2025-11-25` reads |
+| `notifications/initialized` | `202`, and nothing done                                                    |
+| `ping`                      | `{}`                                                                       |
+
+`POST` only, one message per request; `GET` and `DELETE` are `405`. An `Mcp-Session-Id` is ignored
+and none is minted, a `Last-Event-ID` is ignored, and `accept` is negotiated as everywhere else.
+
+Of the modern revision, `MCP-Protocol-Version` and `Mcp-Method` are required, and `Mcp-Name` for a
+`tools/call`; each must say what the body says. `_meta` states the protocol version and the client's
+capabilities. Every result carries `resultType` and names the server in its own `_meta`, and a
+`server/discover` or a `tools/list` carries how long it may be held: half an hour, `public` for the
+first and `private` for the second, which is filtered by the identity that asked.
+
+Neither `listChanged` nor a subscription is declared: both are a stream held open, and this endpoint
+holds none.
+
+## Authorization
+
+The endpoint is a protected resource, and an application advertises it as one:
+
+```yaml
+exposition:
+  oauth:
+    authorize: https://app.example.com/oauth/authorize
+    resources: ['/.mcp']
+```
+
+Its RFC 9728 document is then read at `/.well-known/oauth-protected-resource/.mcp`, and the
+canonical URI of the resource is `https://api.example.com/.mcp`. See [OAuth](oauth.md).
+
+A request without a credential is `401`, carrying the challenge that names that document — which is
+where the flow starts. A call the identity is not authorized to make is `403` with
+`error="insufficient_scope"`. Each tool is authorized as the resource it is, against the path and
+the verb its name states.
+
+A route that is [`anonymous`](access.md#anonymous) is reached here whatever the client presented:
+the rule that refuses a credentialed request is about a cacheable reply, and what a tool answers is
+not one. So a resource that is public over HTTP is a public tool, and nothing in a manifest has to
+say it twice.
+
+## What refuses
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| `-32700` | the body is not readable                               |
+| `-32600` | the body is not one JSON-RPC message                   |
+| `-32601` | no method of that name, at `404`                       |
+| `-32602` | the arguments do not fit, or `_meta` states too little |
+| `-32603` | anything the gateway did not mean to answer            |
+| `-32020` | a header says one thing and the body another           |
+| `-32022` | a revision neither served, naming both                 |
+
+The codes MCP reserves for itself are `-32020` to `-32099`, and it has an implementation use none of
+`-32000` to `-32019` — which is where [JSON-RPC](rpc.md#what-refuses) has this gateway's own, so none
+of those is answered here.
+
+## References
+
+- [The specification](https://modelcontextprotocol.io/specification/2026-07-28)
+- [JSON-RPC](rpc.md), where a procedure gets its name
+- [Introspection](introspection.md), which is what a tool's schemas are
+- [Features](../features/mcp.feature)

package/documentation/notes/peers.md

@@ -0,0 +1,59 @@
+# Distributed Peer Discovery
+
+## Problem
+
+Modulo partitioning algorithm `taks.id % replicas == index` requires
+to know the number of task processing instances running in the cluster,
+and the own index of the current instance.
+
+## Forces
+
+1. Static configuration is not an option (due to dynamic scaling / failover).
+2. In a distributed system, there is no concept of a _global current time_.
+
+## Solution
+
+An algorithm that emits `(index, replicas)` once per `interval` seconds, using common Redis
+key and atomic increment.
+
+Define the following parameters:
+
+- `name`: a name of the task processing (e.g. `mail-sender`)
+- `interval`: indexing interval that is deliberately greater than the expected clock skew among
+  instances
+
+At the start of each `interval` in [Unix epoch](https://en.wikipedia.org/wiki/Unix_time):
+
+1. Calculate an ordinal number of the current interval: `number = ceil(now() / interval)`
+2. Compose a `key` as `{name}:{number}`
+3. Atomically increment a `key` in Redis ([INCR](https://redis.io/docs/latest/commands/incr/))
+4. If `index` is defined (see 5)
+
+- get the value of previous key `{name}:{number-1}` as `replicas`
+- if the `replicas` is defined, emit `(index, replicas)` **algorithm result**
+
+5. Store the response (3) in `index`.
+
+## Safe index transition
+
+If the `index` or `replicas` changes, the algorithm consumer must stop consuming new tasks
+and execute _safe index transition_, to prevent task duplication or loss.
+
+The transition can be implemented in a manner similar to the described algorithm, using a dedicated
+`{name}:transition` key.
+However, this process is considered outside the scope of this document.
+
+## Extension
+
+If the system clocks are too precisely synchronized (skew is less than a round-trip time to Redis),
+this may result in continuous [index transitions](#safe-index-transition).
+
+To mitigate this, the algorithm can be extended with a random delay:
+
+1. Before starting the algorithm, define a random constant clock skew, significantly smaller than
+   `interval`: `skew = random() * (interval / 2)`
+2. Start the algorithm at each `interval + skew`.
+
+## Caveats
+
+- The first result will become known between `interval` and `interval × 2` seconds.

package/documentation/notes/throttling.md

@@ -0,0 +1,122 @@
+# Decentralized Request Throttling
+
+> **Superseded.** The design below was never implemented. `io:throttle` is now a
+> [GCRA](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm) deciding in each process, with
+> its state periodically reconciled through Redis by way of the `atom` aspect's `meter`. It
+> answers the same forces the same way — decide locally, reconcile in the background, never fail the
+> request path — and the section below records what it does instead. The problem statement and the
+> forces have not changed.
+
+## Problem
+
+To prevent an unnecessary load, API requests should be throttled when made maliciously or due to an
+error.
+
+## Context
+
+1. The [API Gateway](https://microservices.io/patterns/apigateway.html) of a distributed system runs
+   in multiple instances, each with an in-memory state that does not allow tracking the current
+   quota usage.
+2. Precise quota enforcement (per request, per second) is not critical; the goal is to prevent
+   significant overuse.
+3. Quota configuration is static.
+
+## Forces
+
+1. No per request IO is allowed (centralized solutions do not fit).
+2. In a distributed system, there is no concept of a _global current time_.
+3. Failure to retrieve the quota state should not result in Gateway failure.
+
+## Solution
+
+Implement in-memory quotas in each process, periodically synchronizing them asynchronously using
+Redis.
+
+Consider a basic throttling rule:
+
+1. No more than `MAX_REQUESTS` within `INTERVAL` time for any API route (`KEY`).
+2. If the limit is exceeded, block requests to `KEY` for `COOLDOWN` seconds.
+
+### Concept
+
+1. Divide `INTERVAL` into `N` spans (`N >= 2`).
+2. At the end of each span,
+   atomically increment the value in Redis ([INCRBY](https://redis.io/docs/latest/commands/incrby/))
+   by the number of requests received for each `KEY`, using a key composed of the `KEY` and the
+   current ordinal number of `INTERVAL`
+   in [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+3. If the returned value exceeds `MAX_REQUESTS`, block access to `KEY`, remove after `COOLDOWN`.
+4. If the write operation fails and `REQUESTS > MAX_REQUESTS / N` (i.e., the quota is exceeded
+   locally), block access to `KEY`, remove after `COOLDOWN`.
+
+Each API Gateway instance will generate the `KEY` based on its own local time,
+which, in general, will lead to simultaneous writes (from Redis’s local time perspective) to
+different `KEY`s. However, the total contribution of each node to each `KEY` will correspond to the
+actual request rate experienced by that node.
+
+<img src="desync.jpg" alt="Desynchronization" />
+
+Dividing the `INTERVAL` into spans smooths the desynchronization effect.
+
+### Extension
+
+Introduce `nodes`, the approximate number of active API Gateway instances, to improve the algorithm.
+
+1. Initially, `nodes` equals to `1`.
+2. During each `INTERVAL`, sum the total request count for each `KEY`, keep current and previous
+   values.
+3. At the end of each interval:
+
+- Read the value from the `KEY` for the previous interval. At this point, it is assumed that all
+  nodes have switched to the next interval.
+- Update the `nodes` value by dividing response form Redis by the number of `REQUESTS` counted for
+  the previous interval.
+- Set the previous value to the current value.
+- Set the current value to `0`
+
+4. Update point 4 of the [Concept](#concept): `REQUESTS * nodes > MAX_REQUESTS / N`.
+   This will increase the precision of the local quota enforcement.
+5. Add a new step: if `REQUESTS * nodes > MAX_REQUESTS`, block access to `KEY`, remove after
+   `COOLDOWN`.
+
+When nodes are added or removed, the algorithm will adapt in the upcoming intervals.
+
+### Caveats
+
+1. In the worst case scenario (really, really unlikely), the quota is exceeded by `MAX_REQUESTS / N`
+   in a span on each node.
+2. Time desynchronization between nodes should be insignificant for the selected `INTERVAL` (i.e.,
+   `INTERVAL` >> desync). See Extension point 3.
+
+## What was implemented instead
+
+Windows were dropped for a GCRA. A key holds one theoretical arrival time: the moment it would be
+back at zero if nothing more arrived. An admitted request pushes it `interval / requests`
+milliseconds further out, time drags it back, and a request is admitted while it stays within
+`interval` of now. So `requests` is what a key may spend at once and `requests / interval` the rate
+it earns back, with no window edge to burst across and no lockout to time out of — which is why
+`cooldown` is gone.
+
+Deciding reads nothing but a local map, so the request path stays free of I/O, exactly as force 1
+demands. What the other gateways have spent arrives on a timer, as **debt**: the milliseconds a key
+owes, draining at a millisecond a millisecond. Debt is the right thing to send for two reasons.
+
+1. It is a duration, not a moment, so processes exchanging it need not agree on the time — force 2,
+   answered by not needing an answer. The one clock that matters is Redis', read inside the script.
+2. It is additive in admissions, so a process reports only its own increments and Redis keeps the
+   running total. Nothing has to be divided by a number of nodes, which is as well: the gateway
+   cannot observe how many of it there are.
+
+The consequences worth knowing:
+
+- **Reconciling is decoupled from `interval`.** The timer runs at a tenth of `interval`, clamped
+  between 250ms and 2s, so a minute-long budget is no staler than a second-long one. The overshoot
+  is bounded by what the other instances admit within one tick — the caveat that replaces the old
+  note's `MAX_REQUESTS / N` per span.
+- **The cost is one round trip a tick**, not one per key. Every quota in the process flushes into a
+  single script call, which matters because a limiter keyed on `ip` watches as many keys as it has
+  clients.
+- **Redis keys expire on their own**, after the debt on them plus a grace, so nothing sweeps them.
+- **Failure degrades, as force 3 demands.** A tick that cannot reach Redis leaves its debt to the
+  next one rather than losing it; until then the instance throttles on what it alone has seen, and
+  keeps serving.