hub_kernel-api 0.9.0 → 0.10.0

data/the_local/agents/hub_kernel-api-develop.md

@@ -1,33 +1,87 @@
 ---
 name: hub_kernel-api-develop
-description: Use PROACTIVELY for calling a served hub over HTTP — listing the methods a caller may call at a hub's address, calling a read with GET, calling a write with POST, sending its values, and reading its answer or error status — MUST BE USED instead of hand-writing a controller or endpoint per hub method, or guessing at the API's responses.
+description: Use PROACTIVELY for calling a served hub over HTTP — listing every served hub's methods and the version at the API's root address, listing the methods a caller may call at a hub's address, reading the JSON Schema of each method's answer from a listing, calling a read with GET, calling a write with POST, sending its values, naming the major version a client was built for with Accept-Version, reading the Api-Version a call was answered at, noticing from Api-Newest-Version that a newer major is served, noticing from Deprecation and Sunset that the pinned major is deprecated, when it was deprecated and when it stops being served, reading its answer or error status, handling a call refused because it names a retired major, writing each major's description file with the describe task, checking in CI that no major removes, renames or silently adds to what its committed description file holds, handling a BreakingChangeError from the check or describe task, checking a recorded answer against a description file without a running host, and testing in the host that a method's answer still matches its declared answer shape at a major — MUST BE USED instead of hand-writing a controller or endpoint per hub method, versioning the URL by hand, hand-writing a schema or type for a method's answer, hand-writing an API description file, hand-diffing description files to spot a breaking change, hand-rolling a JSON Schema check of an answer in a host test, or guessing at the API's responses.
 tools: Read, Write, Edit, Grep
 scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 ---
 
-This local writes client code against the three endpoints below and follows the steps in
-order. Where a step names a decision, it asks the developer and does not pick.
+This local writes client code against the four endpoints, the six headers, the answer
+shapes, the describe task and the description files below, runs the breaking change check
+on those files, writes host tests with the answer shape assertion, and follows the steps in
+order.
+Where a step names a decision, it asks the developer and does not pick.
 
 ## What hub_kernel-api is
 
 A Rails engine that answers HTTP calls to the exposed methods of the hubs a host serves,
 each call made after the host's sign-in and checked and scoped by the permission check and
-account scope that hub_kernel-interface holds. Use this local when writing a front end,
-mobile app, service or request test that calls those methods, or when working out why a
-call answered as it did. Adding the gem, choosing the served hubs and mounting the engine
-belong to the install local.
+account scope that hub_kernel-interface holds. When the host lists major versions, every
+method answers at the same address at every major, and the caller picks the major with a
+request header. A host can keep a major listed but mark it retired, and then every call
+naming it is refused as gone. A host can also mark a major it still serves deprecated, and
+must give the date it was deprecated and the date it stops being served, and every answer
+at it then carries headers giving those dates. Every
+answer at a major older than the newest carries a header naming the newest. A listing can give the JSON Schema of each method's answer at that major,
+and a rake task writes the same description for each major into a file a client can use
+without reaching a running host. A second rake task fails when a major's current
+description removes or renames something its committed file holds, or adds something
+without the major's minor being raised. A call never checks its answer against its declared
+shape, so the gem gives the host a test assertion that does. Use this local when writing a
+front end, mobile app, service or request test that calls those methods, when generating
+client types from the answer shapes, when writing or using the description files, when
+checking a hub change for a breaking change or handling a failed check, when
+testing in the host that a method's answer matches its shape, or when working out why a
+call answered as it did. Adding the gem, choosing the served hubs, listing the majors, deprecating
+or retiring a major, declaring
+answer shapes and mounting the engine belong to the install local.
 
 ## Interface
 
+- `GET /` — lists every served hub's methods the signed-in caller may call, keyed by the
+  hub's address, with the full version the listing describes, as
+  `{ "version", "hubs": { "<hub>": [...] } }`.
 - `GET /<hub>` — lists the methods the signed-in caller may call on the hub at that
-  address, for the caller's account, each as `{ "name", "takes", "verb" }`.
+  address, for the caller's account, each as `{ "name", "takes", "verb", "answer_shape" }`.
 - `GET /<hub>/<method>` — calls an exposed read with the values sent in the query string
   and answers `{ "answer": <return value> }`.
 - `POST /<hub>/<method>` — calls an exposed write with the values sent in the request body
   or query string and answers `{ "answer": <return value> }`.
+- `Accept-Version` request header — names the major version the client was built for, as
+  the bare major number, such as `Accept-Version: 1`.
+- `Api-Version` response header — the full major.minor.patch version the call was answered
+  at, such as `1.4.0`, absent on a 406 or 410.
+- `Api-Newest-Version` response header — the full version of the newest major the host
+  lists, such as `2.0.1`, sent only when the answer was given at an older major.
+- `Deprecation` response header — the date the major was deprecated, as `@` and the Unix
+  seconds of that date's midnight UTC, such as `@1790726400`, sent only when the answer was
+  given at a major the host marked deprecated.
+- `Sunset` response header — the date a deprecated major stops being served, as an HTTP
+  date such as `Wed, 31 Mar 2027 00:00:00 GMT`, sent only when the answer was given at a
+  major the host marked deprecated.
+- `Vary` response header — `Accept-Version` on every answer from a host that lists majors,
+  refusals included, so a cache keeps one copy per major.
+- `answer_shape` listing field — the JSON Schema of a method's answer at the major the
+  listing describes, present only when one is declared for that major.
+- `bin/rails hub_kernel_api:describe` — run in the host, writes one description file for
+  each major the host lists that is not retired into the host's `api_descriptions` folder,
+  and writes none while any major removes or renames something its committed file holds,
+  or adds something without its minor being raised.
+- `bin/rails hub_kernel_api:check_descriptions` — run in the host, usually in CI, fails
+  when a major that is not retired and has a committed file removes or renames something
+  that file holds, or adds something without its minor being raised above the file's.
+- `HubKernel::Api::BreakingChangeError` — the error both tasks raise, naming every
+  problem at once, one to a line.
+- `api_descriptions/v<major>.json` — one major's description, written for no retired major, `{ "version", "hubs":
+  { "<hub>": [...] } }`, holding every served method at that major whatever any caller may
+  call.
+- `HubKernel::Api::TestHelper` — a module a host's Minitest test case includes, after
+  `require "hub_kernel/api/test_helper"`, to get `assert_answer_shape`.
+- `assert_answer_shape(hub, name, answer, major:)` — translates a method's own answer down
+  to the named major as a call does, and fails the test when it does not match the method's
+  answer shape at that major.
 
-Every path is relative to the path the host mounted the engine at, such as
-`/api/v1/hubs`.
+Every path in an endpoint is relative to the path the host mounted the engine at, such as
+`/api/v1/hubs`. The `api_descriptions` folder is relative to the host's root.
 
 ## How to use it
 
@@ -37,63 +91,295 @@ Every path is relative to the path the host mounted the engine at, such as
 2. Find the hub's address. A hub answers at its module name underscored, so `Supplies`
    answers at `supplies`, unless the host listed it under a name of its own, such as
    `{ "money" => Billing::Ledger }`, in which case it answers only at `money`. Read the
-   host's served hubs list in its initializer to find it.
+   host's served hubs list in its initializer to find it, or read the keys of the root
+   address listing in step 6.
 
-3. Authenticate the request the way the host's sign-in requires, such as a session
+3. Find the majors the host lists in its initializer, where each is listed by its full
+   version, such as `"2.0.1"`, and its major is the first number. A major listed with
+   `retired: true` is retired: it stays listed, but every call naming it is refused with a
+   410. A major listed with `deprecated: true` is still served in full, and always carries
+   a `deprecated_on:` date on which it was deprecated and a `sunset:` date on which the host
+   plans to stop serving it. A host whose majors hold a mistake, such as a deprecated major
+   missing either date, a major listed twice, or every major retired, does not start, so at
+   least one listed major is always served. The error of a 406 answer
+   also names every major listed that is not retired, and the error of a 410 names the
+   newest major listed.
+
+   - If the host lists no majors, skip step 4. The API ignores any `Accept-Version`
+     header on every endpoint, the root address included, every call answers with the
+     method's own answer, every listing gives each method's own answer shape, no answer
+     carries a version header or a `version` key, and the describe task writes no files.
+   - If the host lists majors, go to step 4.
+
+4. Choose the major the client is built for, and send it on every request, both listings
+   included:
+
+   ```
+   Accept-Version: 2
+   ```
+
+   Which major to pin is the developer's decision: ask. A new client normally pins the
+   newest major listed. Never pin a retired major, since every request naming it is
+   refused with a 410. Avoid pinning a deprecated major in a new client, since the host
+   plans to retire it. A request with no `Accept-Version` header is answered at the oldest
+   major listed that is not retired, so a client that omits it silently gets that major's
+   answer shape, and moves to a newer one when the host retires it. Send the major alone,
+   never the full version: `2`, not `2.0.1`.
+
+   At an older major, a method answers in the shape it had at that major. A method whose
+   answer changed declares its earlier answers on the hub, and the API converts the
+   newest answer down to the major named. At the newest major, the method's own answer is
+   returned. Write the client against the shape of the major it pins.
+
+5. Authenticate the request the way the host's sign-in requires, such as a session
    cookie or a bearer token. Ask the developer which one the client uses. A request the
    host's sign-in refuses is answered by the host, with the host's own status, and
    reaches no hub.
 
-4. List what the caller may call:
+6. To discover everything the caller may call in one request, list the root address:
+
+   ```
+   GET /api/v1/hubs/
+   Accept-Version: 1
+   ```
+
+   ```json
+   { "version": "1.4.0",
+     "hubs": { "supplies": [{ "name": "shelf_of", "takes": ["item"], "verb": "GET",
+                              "answer_shape": { "type": "object", "required": ["shelf"] } }],
+               "money": [] } }
+   ```
+
+   Each key under `hubs` is a served hub's address, and its list is that hub's listing as
+   step 7 gives it. A served hub on which the caller may call nothing is listed with an
+   empty list. `version` is the full version of the major the listing describes, and it is
+   absent when the host lists no majors.
+
+7. To list one hub, list its address:
 
    ```
    GET /api/v1/hubs/supplies
+   Accept-Version: 2
    ```
 
    ```json
-   [{ "name": "price_of", "takes": ["item"], "verb": "GET" },
+   [{ "name": "price_of", "takes": ["item"], "verb": "GET",
+      "answer_shape": { "type": "object", "required": ["cents"] } },
     { "name": "reorder", "takes": ["item", "quantity"], "verb": "POST" }]
    ```
 
    The list holds only the methods this caller is permitted on this account. Use `verb`
    to choose GET or POST, and `takes` for the value names the method accepts.
 
-5. Call a read with GET, sending its values as query parameters:
+8. Read each method's `answer_shape`, when present, as the JSON Schema of its `answer` at
+   the major the listing was asked at. At the newest major it is the method's own declared
+   shape. At an older major it is the shape declared for the nearest earlier answer at or
+   after that major, or the method's own when it declares no earlier answer at or after
+   that major. A method with no shape declared at that major has no `answer_shape` key, so
+   treat its answer as untyped rather than reusing another major's shape.
+
+   Whether the client validates answers against the shape or generates types from it is
+   the developer's decision: ask. Fetch the shapes with the same `Accept-Version` the
+   client sends on its calls, since a listing at another major gives another major's
+   shapes.
+
+9. To have every method's shape at each major without a request, write the description
+   files in the host:
 
+   ```sh
+   bin/rails hub_kernel_api:describe
    ```
-   GET /api/v1/hubs/supplies/price_of?item=42
+
+   The task creates the host's `api_descriptions` folder if it is missing and writes one
+   file per major the host lists that is not retired, named after the major, such as `api_descriptions/v1.json`
+   for a major listed as `"1.4.0"`:
+
+   ```json
+   { "version": "1.4.0",
+     "hubs": { "supplies": [{ "name": "shelf_of", "takes": ["item"], "verb": "GET",
+                              "answer_shape": { "type": "object", "required": ["shelf"] } }] } }
    ```
 
-   Query values arrive as strings.
+   `version` is the major's full version. Each key under `hubs` is a served hub's address,
+   and each method is given as the root address listing gives it at that major, with
+   `answer_shape` chosen by the rule in step 8 and absent when none is declared at that
+   major. Unlike a listing, a file holds every method each served hub exposes, whatever
+   any caller may call, and names no caller, so never read it as what a given caller may
+   call. Use a listing for that.
 
-6. Call a write with POST, sending its values as a JSON body with
-   `Content-Type: application/json`, keyed directly by value name with no wrapping key:
+   Run the task again after any change to a hub's exposed methods, their answer shapes,
+   their earlier answers, the served hubs or the listed majors. Running it with no change
+   writes identical files. The task overwrites the file of every major listed that is not
+   retired and deletes no file, so delete by hand the file of a major the host has retired
+   or no longer lists.
 
-   ```
-   POST /api/v1/hubs/supplies/reorder
-   Content-Type: application/json
+   Whether the host commits the files is the developer's decision: ask.
 
-   { "item": 42, "quantity": 3 }
-   ```
+   The task refuses to write any file while a major removes or renames something its
+   committed file holds, or adds something without its minor being raised, and raises
+   `HubKernel::Api::BreakingChangeError` naming each problem, as step 10 describes.
+
+10. To catch a breaking change before it ships, run the check in the host, and in the
+    host's CI, against the committed description files:
+
+    ```sh
+    bin/rails hub_kernel_api:check_descriptions
+    ```
+
+    It compares each major that is listed, is not retired and has a file in
+    `api_descriptions` with that major's current description, and passes or raises
+    `HubKernel::Api::BreakingChangeError` naming every problem at once, one to a line:
+
+    ```
+    Major 2 removes or renames supplies.shelf_of.answer_shape.required.shelf, which its committed file holds
+    Major 2 adds supplies.shelf_of.takes.size without raising its minor above 2.1.0
+    ```
+
+    Each problem names the major and a dotted path into its file: the hub's address, the
+    method's name, then `takes`, `verb` or `answer_shape` and the keys and values below
+    it. A changed value shows as the old value removed, so a method moved from GET to
+    POST shows as `verb.GET` removed, and a rename shows as the old name removed. An
+    object in a list that has no `name` key, such as a choice in an `anyOf`, is named by
+    its position in the list, such as `answer_shape.anyOf.2`.
+
+    - A removal or rename breaks clients pinned to that major. Whether to keep the old
+      hub, method, value, verb or shape key at that major, or to make the change only in a
+      new major, is the developer's decision: ask. Never delete or edit the committed file
+      to make the check pass.
+    - An addition without a raised minor is fixed by raising the minor of that major's full
+      version in the host's version list above the minor the problem names, such as
+      `"2.1.0"` to `"2.2.0"`, then running `bin/rails hub_kernel_api:describe` to rewrite
+      the file. Ask the developer before changing the version.
+    - A change that keeps every key and value but changes what a value means passes, so
+      the check does not replace reviewing such a change.
+    - A retired major, a major the host no longer lists, and a major with no committed
+      file are not compared.
+
+    The describe task refuses to write while the check would fail, so fixing every
+    problem the check names comes before rewriting the files.
+
+11. To check answers in a client repo without reaching a running host, copy in the file
+    for the major the client pins, and check a recorded `answer` against the method's
+    `answer_shape` from that file with a JSON Schema library. Which library to use is the
+    developer's decision: ask. Copy the file again whenever the host rewrites it.
+
+12. Call a read with GET, sending its values as query parameters:
+
+    ```
+    GET /api/v1/hubs/supplies/price_of?item=42
+    Accept-Version: 2
+    ```
+
+    Query values arrive as strings.
+
+13. Call a write with POST, sending its values as a JSON body with
+    `Content-Type: application/json`, keyed directly by value name with no wrapping key:
+
+    ```
+    POST /api/v1/hubs/supplies/reorder
+    Content-Type: application/json
+    Accept-Version: 2
+
+    { "item": 42, "quantity": 3 }
+    ```
+
+    Query parameters on a POST are sent to the method as well. Do not send a value whose
+    name is not in `takes`.
+
+14. Read the response by status:
+
+    | Case | Status | Body |
+    | --- | --- | --- |
+    | The method answers, or a listing is given | 200 | `{"answer": <return value>}` for a call, the listing for a listing |
+    | The hub is not served, the method is not exposed, the verb is wrong, or the permission check refuses the caller | 404 | `{"error": "Not found"}` |
+    | The hub refuses the call, or a required value is missing | 422 | `{"error": "<reason>"}` |
+    | A permitted call sends a value the method does not take | 422 | `{"error": "<method> does not take <values>"}` |
+    | A record the call names does not exist | 404 | `{"error": "No <record> has the id <id>"}` |
+    | `Accept-Version` names a major the host does not list, on any endpoint | 406 | `{"error": "Major <n> is not served, the majors served are <majors>"}` |
+    | `Accept-Version` names a retired major, on any endpoint, whether or not the hub is served | 410 | `{"error": "Major <n> is no longer served, the newest major is <newest>"}` |
+
+    Show the `error` text of a 422 to the user, since it is the hub's reason. Treat
+    `Not found` as a method that does not exist for this caller. Treat a 406 as a client
+    pinned to a major the host does not list, and a 410 as a client pinned to a major the
+    host has retired. Fix the pinned major for either rather than retrying, and ask the
+    developer which major to move the client to.
+
+15. Read the response headers from a host that lists majors:
+
+    - `Api-Version` holds the full version the answer was given at, such as `2.0.1`, on
+      every answer except a 406 or a 410. Use it to log or show which version served the
+      call.
+    - `Api-Newest-Version` holds the full version of the newest major listed, such as
+      `2.0.1`, on every answer given at an older major except a 406 or a 410. Its presence
+      means a newer major is served than the one the client pins.
+    - `Deprecation` holds the date the pinned major was deprecated, as `@` and the Unix
+      seconds of that date's midnight UTC, such as `@1790726400` for 30 September 2026, as
+      RFC 9745 defines it. It is on every answer given at a deprecated major except a 406
+      or a 410. Its presence means the host plans to stop serving the pinned major.
+    - `Sunset` holds the date the deprecated major stops being served, as an HTTP date such
+      as `Wed, 31 Mar 2027 00:00:00 GMT`. It is on every answer that carries `Deprecation`,
+      and on no other. After that date the host may retire the major, and calls naming it
+      are then refused with a 410.
+    - None of these headers changes the body of an answer. An answer at the newest major
+      carries no `Api-Newest-Version`, and carries `Deprecation` and `Sunset` only when the
+      newest major is itself deprecated.
+    - `Vary: Accept-Version` is on every answer, the 406 and 410 included. Any cache between the
+      client and the API must honour it.
+
+    What the client does on `Api-Newest-Version` or `Deprecation`, such as logging a
+    warning, showing a notice, or failing a check in CI, is the developer's decision: ask.
+    Never move the pinned major automatically from these headers, since the answer shapes
+    differ between majors.
+
+16. For a request test in the host, sign in as a person with and without the permission,
+    and assert the 200 answer for one and the `Not found` 404 for the other. When the
+    host lists majors, also assert the `Api-Version` header for a named major, the
+    answer shape at an older major for a method that declares earlier answers, the
+    `answer_shape` a listing gives at that major, the root address listing's `version`,
+    the `Api-Newest-Version` header at an older major and its absence at the newest, the
+    `Deprecation` and `Sunset` header values at a deprecated major, the 406 for a major the
+    host does not list, and the 410 for a retired major.
+
+17. To test in the host that a method's answer still matches its declared shape, add the
+    json_schemer gem to the host's test group, since the assertion needs it and the gem
+    does not depend on it:
+
+    ```ruby
+    group :test do
+      gem "json_schemer"
+    end
+    ```
+
+    Then include the helper in a Minitest test case and assert one method's answer at one
+    major:
 
-   Query parameters on a POST are sent to the method as well. Do not send a value whose
-   name is not in `takes`.
+    ```ruby
+    require "hub_kernel/api/test_helper"
 
-7. Read the response by status:
+    class SuppliesShapeTest < ActiveSupport::TestCase
+      include HubKernel::Api::TestHelper
 
-   | Case | Status | Body |
-   | --- | --- | --- |
-   | The method answers | 200 | `{"answer": <return value>}` |
-   | The hub is not served, the method is not exposed, the verb is wrong, or the permission check refuses the caller | 404 | `{"error": "Not found"}` |
-   | The hub refuses the call, or a required value is missing | 422 | `{"error": "<reason>"}` |
-   | A permitted call sends a value the method does not take | 422 | `{"error": "<method> does not take <values>"}` |
-   | A record the call names does not exist | 404 | `{"error": "No <record> has the id <id>"}` |
+      test "shelf_of answers in its shape at major 1" do
+        assert_answer_shape(Supplies, :shelf_of, Supplies.shelf_of(item: "flour"), major: 1)
+      end
+    end
+    ```
 
-   Show the `error` text of a 422 to the user, since it is the hub's reason. Treat
-   `Not found` as a method that does not exist for this caller.
+    - `hub` is the hub module, and `name` is the exposed method's name as a symbol.
+    - `answer` is the method's own answer, the value the hub returns, never an answer
+      already converted to an older major. The assertion converts it down to `major:`
+      through the earlier answers the hub declares, as a call does.
+    - `major:` is a bare major number the host lists, such as `1`, not a full version.
+    - The shape checked is the one a hub listing gives at that major, by the rule in step 8.
+    - A failure names the method and the major, then each place the answer differs from
+      the shape, one to a line.
+    - It also fails, naming the major and the method, when the host lists no such major,
+      which includes every major on a host that lists none, or when the method declares no
+      shape at that major.
+    - Without json_schemer installed it raises a `LoadError` naming the gem to add.
 
-8. For a request test in the host, sign in as a person with and without the permission,
-   and assert the 200 answer for one and the `Not found` 404 for the other.
+    Which methods and which majors to assert, and which inputs to call each method with,
+    are the developer's decision: ask.
 
 ## Conventions
 
@@ -101,10 +387,26 @@ Every path is relative to the path the host mounted the engine at, such as
   never as a method error.
 - A forbidden method and a missing one both answer `Not found`, so a client cannot tell
   them apart, and must not try.
-- The `answer` is the method's return value as JSON; nothing else is added to it.
+- The `answer` is the method's return value as JSON, converted to the named major's shape
+  when the host lists majors; nothing else is added to it.
+- The major is chosen by the `Accept-Version` header alone; never put a version in the
+  path after the mount point or in a query parameter.
+- A client against a host that lists majors always sends `Accept-Version`, and never
+  relies on the default, and never sends a retired major.
+- An `answer_shape` describes one major only; never apply a shape fetched at one major to
+  answers at another, and never hand-write a shape the listing or a description file
+  already gives.
+- A call never checks its answer against its shape; check it in a host test with
+  `assert_answer_shape`, never with a hand-written JSON Schema check of the declared shape.
+- A description file is written by the describe task only; never edit one by hand, and
+  never use one to decide what a caller may call.
+- A breaking change is found by `bin/rails hub_kernel_api:check_descriptions` against the
+  committed files; never pass it by deleting or editing a committed file.
 - The account a call is made for comes from the host's sign-in, never from a value in the
   request.
 - Only the methods a hub exposes are reachable; adding a method to the API means exposing
   it on the hub, not adding a route.
-- Installing the gem, configuring it and choosing the served hubs are out of scope here;
-  they belong to the install local.
+- `Api-Newest-Version`, `Deprecation` and `Sunset` are notices only; never treat an
+  answer carrying them as an error, and never switch majors at runtime because of them.
+- Installing the gem, configuring it, choosing the served hubs, listing the majors,
+  deprecating or retiring a major, declaring a method's earlier answers and declaring answer shapes are out of scope here.

data/the_local/agents/hub_kernel-api-info.md

@@ -1,6 +1,6 @@
 ---
 name: hub_kernel-api-info
-description: Use to learn what hub_kernel-api offers — serving a hub's exposed methods as a JSON API, the served hubs and their addresses, reads and writes, and how sign-in, permission and account scope apply to each call.
+description: Use to learn what hub_kernel-api offers — serving a hub's exposed methods as a JSON API, the served hubs and their addresses, reads and writes, the listings at a hub's address and at the root address with each method's answer shape, the major versions a host serves, deprecates with the date it was deprecated and the date it stops, and retires, the headers telling a caller its major is not the newest or is deprecated, the description file written for each served major, the check that fails when a major removes something its file holds or adds something without raising its minor, the test assertion that checks an answer against its shape, and how sign-in, permission and account scope apply to each call.
 tools: Read
 scope: hub JSON API — serving a hub_kernel hub's exposed methods as a JSON API in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope
 ---
@@ -11,9 +11,9 @@ This local explains hub_kernel-api and makes no changes.
 
 hub_kernel-api is a Rails engine that serves the exposed methods of hub_kernel hubs
 as a JSON API inside a host Rails app. The host lists which hubs it serves, and the
-gem answers HTTP calls to their exposed methods and to a listing of them. It adds no
-business logic of its own: every answer is the return value of a method the hub
-already exposes.
+gem answers HTTP calls to their exposed methods, a listing of one hub's methods, and a
+listing of every served hub's methods at the API's root address. It adds no business
+logic of its own: every answer is the return value of a method the hub already exposes.
 
 It depends on hub_kernel-interface alone, not on hub_kernel. hub_kernel-interface
 holds the permission check and the account scope, and the host sets both.
@@ -22,24 +22,48 @@ Reach for it when a hub's exposed methods need to be called over HTTP, by a mobi
 app, another service or a front end, without writing a controller per method. Each
 call runs the host's own sign-in first, then hub_kernel-interface's permission check
 and account scope, so the API never shows a caller more than the app itself would.
+A client can learn from the listings what it may call and what shape each answer
+takes. A host can also serve several major versions of the API at the same addresses,
+so an older client keeps getting the answers it was built for after a method's answer
+changes. It can mark a major it plans to stop serving as deprecated, with the date it
+was deprecated and the date it stops, so callers at that major are told on every
+answer, and can retire a major it no longer serves so callers naming it are told it is
+gone. It can write a JSON description of each served major into the app, so the API at
+each major can be read and compared without calling it, and its CI can fail a change that
+breaks a major's file. A host's tests can check that a
+method's answer still matches the shape it declares at a major, since a call never checks
+that itself.
 
 ## Interface
 
 This local declares no commands. The surface is split between the other two locals:
 
 - **hub_kernel-api-install** owns adding the gem to a host, the configuration that
-  names the base controller, the person and account methods and the served hubs, the
-  startup check that rejects a hub that cannot be served, and mounting the engine.
-- **hub_kernel-api-develop** owns the HTTP endpoints a client calls: the listing at a
-  hub's address and the call to one exposed method, with their verbs, request values,
-  responses and error statuses.
+  names the base controller, the person and account methods, the served hubs, the
+  majors served, which of them are deprecated, when each was deprecated and when each
+  stops, and which are retired, the startup check that rejects a hub that cannot be served
+  or a list of majors with a mistake in it, the errors a host can meet, and mounting the
+  engine.
+- **hub_kernel-api-develop** owns the HTTP endpoints a client calls: the listing at
+  the root address, the listing at a hub's address, and the call to one exposed
+  method, with their verbs, request values, the headers that name and report a
+  version, the headers that report a newer major and a deprecated one, the answer
+  shapes the listings give, responses and error statuses, the task that writes each
+  served major's description file and where those files go, the check that compares
+  each major with its file and the error it raises, and the test assertion
+  that checks an answer against its shape.
 
 ## How to use it
 
-- To put the API into a Rails app, or to serve another hub from one that has it, use
-  the install local.
-- To write a client against the API, or to work out why a call answered as it did,
-  use the develop local.
+- To put the API into a Rails app, to serve another hub from one that has it, to
+  list the majors a host serves, to deprecate one, or to retire one, use the install
+  local.
+- To write a client against the API, to discover what it may call and the shape of
+  each answer, to call it at a particular major, to notice that its major is
+  deprecated or has a newer one, to work out why a call answered
+  as it did, to write and read the description files, to have CI fail a breaking
+  change to a major, or to test that a method's
+  answer matches its shape, use the develop local.
 
 ## Conventions
 
@@ -58,9 +82,74 @@ This local declares no commands. The surface is split between the other two loca
 - **Person and account** — who is calling and which account the call is made for,
   both supplied by the host's base controller after its own sign-in. Every call and
   every listing is scoped to them.
+- **Hub listing** — the methods of one served hub the caller may call, each with its
+  name, the values it takes, its verb and its answer shape.
+- **Root address listing** — every served hub's listing keyed by the hub's address,
+  given at the API's root address, together with the full version of the major it
+  describes.
 - **Answer** — a successful call returns the method's return value under the
   `answer` key.
+- **Answer shape** — the JSON Schema a method declares for its answer, through
+  hub_kernel-interface. A listing gives each method's shape at the major the caller
+  named, and a method with no declared shape at that major is listed with no shape.
 - **Not found and refused** — a call the permission check denies is answered as not
   found, so a caller cannot tell a forbidden method from a missing one. A call the hub
   itself refuses, or one missing a required value, is answered as unprocessable with
   the reason.
+- **Major and full version** — the host lists each major it serves by a full version
+  in major.minor.patch form, and the major is that version's first part. Every
+  method answers at the same address at every major, and a call or listing that names
+  no major is answered at the oldest one listed that is not retired.
+- **Earlier answer** — a hub method always answers in the newest major's shape. A
+  method whose answer changed declares, through hub_kernel-interface, how to turn its
+  answer back into an older major's shape, and may declare that older shape too. A
+  call at an older major gets the answer passed through each of those from the newest
+  down to the major named.
+- **Newest major** — the listed major with the highest number. Every answer at an
+  older major carries a header giving the newest major's full version, so a caller
+  learns a newer major exists without asking.
+- **Deprecated major** — a major the host still serves but plans to stop serving, given
+  the date it was deprecated and the date it stops, both as dates. Every answer at it is
+  given as usual, and carries a header giving each of those dates. The headers never
+  change an answer's body, and a deprecated major can still be the one a call that names
+  no major is answered at.
+- **Unserved major** — a call or listing naming a major the host does not list is
+  answered as not acceptable, with a message naming the majors that are served.
+- **Retired major** — a major the host still lists but has marked as no longer served.
+  A call or listing naming it is answered as gone, with a message naming the newest
+  major, whether or not the hub it names is served. A retired major is never the one
+  a call that names no major is answered at.
+- **No majors listed** — a host that lists no majors does no versioning: every call
+  gets the method's own answer, every listing gives each method's own shape, no
+  version is reported, no description file is written, and the startup check checks
+  no majors.
+- **Startup check** — run when the host boots, it refuses to let the app start while a
+  served hub cannot be served or the listed majors hold a mistake, and names every
+  problem it found. A mistake in the majors is a version not a string in major.minor.patch form,
+  a major listed twice, a deprecated major missing either date, a date given as
+  something other than a date, every major retired, or a hub declaring an earlier answer
+  for a major the host does not list or for the newest major.
+- **Description file** — one JSON file per listed major that is not retired, written into the host app on
+  request and named after the major. It gives the major's full version and every served
+  hub's methods, keyed by address, each with its values, verb and answer shape at that
+  major. Unlike a listing, it is written for no caller, so it holds every exposed method
+  of every served hub with no permission check or account scope applied. Writing the
+  files again with nothing changed writes identical files. Writing them is refused, with
+  nothing written, while any major removes or renames something its existing file holds,
+  or adds something without raising its minor.
+- **Breaking change check** — a check a host's CI runs that compares each major that is
+  not retired with the description file it already has, and fails naming every problem
+  at once. A major breaks its file when its current description no longer holds a hub, a
+  method, a value the method takes, its verb, or a key or value in its answer shape that
+  the file holds, and a rename counts as the old name removed. An object in a list that
+  has no name, such as a choice in an `anyOf`, is matched by its position. It also breaks its file
+  when it adds something the file does not hold while the minor of its full version is no
+  higher than the minor in the file. A change that keeps every key and value but changes
+  what a value means passes, and a retired major or a major with no file is not compared.
+- **Shape assertion** — a test assertion a host includes in its own tests. It takes a
+  hub, a method's name, the method's own answer and a listed major, turns the answer
+  down to that major as a call would, and checks it against the method's shape at that
+  major. It fails naming the method, the major and each place the answer differs, and
+  also fails when the host lists no such major or the method declares no shape at it.
+  It needs a JSON Schema gem in the host's test group, and hub_kernel-api loads that
+  gem only when the assertion runs, so a host without it still loads hub_kernel-api.