feat: the API the approved client designs need

.github/workflows/ci.yml

@@ -57,6 +57,11 @@ jobs:
       - name: Prose
         run: python3 bin/check_prose.py
 
+      # Stdlib only as well. These cover the scripts in bin/, which have
+      # no dependency manager and no Django to test them with.
+      - name: The bin/ scripts
+        run: python3 -m unittest discover -s bin/tests
+
       - name: No migration is missing
         run: |
           docker compose -f docker-compose.test.yml run --rm --entrypoint sh pytest \

.pre-commit-config.yaml

@@ -9,10 +9,9 @@ repos:
     rev: v0.42.0
     hooks:
       - id: markdownlint
-        # Two approved documents have never passed this hook: the design
-        # spec and the plan it was built from. Reflowing either would be
-        # a huge diff on prose nobody asked to rewrite.
-        exclude: ^docs/(specs|superpowers)/
+        # Specs and plans have never passed this hook. Reflowing prose
+        # nobody asked to rewrite would be a huge diff.
+        exclude: ^docs/(specs|plans)/
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Must match the ruff in api/uv.lock. On different versions the hook
     # and `just lint` format differently and undo each other, so a commit

AGENTS.md

@@ -4,7 +4,7 @@
 
 Comments, docstrings, commit messages and documentation follow ASD-STE100.
 
-- One idea per sentence. Under 20 words.
+- One idea per sentence. 20 words or fewer.
 - Active voice. Present tense.
 - No em dashes. A qualifier goes in brackets: `GitHub (2026-08-30 15:32)`.
 - A standalone `—` is allowed as an empty-cell marker. It is a placeholder,
@@ -27,6 +27,9 @@ Delete a comment when the reason it recorded stops being true.
 - No sample output. It goes stale and nobody re-runs it.
 - No section nobody asked for.
 - A README describes the repository as it is now, not as it changed.
+- A spec describes the system, so it moves with the code. A plan
+  records what somebody intended, so it stays as written. That includes
+  the places where the plan turned out to be wrong.
 
 ## Engineering
 
@@ -54,6 +57,28 @@ edit that worked. Open the page. Read the value back.
 template that overrides it. An override patches one instance of a
 problem; the setting fixes the class.
 
+## Layout
+
+Which file a piece of code goes in, by what it is.
+
+- An app keeps one `views.py` until it serves more than one resource.
+  Then it becomes `views/`, one module per resource or per long-lived
+  operation. `catalog` serves three resources, and `imports.py` is an
+  operation on `Service`. A sub-resource stays with its parent, so an
+  event's update log is not a second module.
+- A **queryset method** is chainable vocabulary. It lives on the
+  queryset in `models.py`, because a caller chains it onto a query.
+- A **bare expression** is handed to `annotate()`. It lives in
+  `queries.py`, because nothing chains it.
+- `queries.py` is row-scoped and `aggregates.py` is collection-scoped.
+  One lands in a serialized row. The other lands in the `aggregates`
+  key beside `results`.
+- `common` holds no expression that describes an app. `common/ordering.py`
+  records this as a scar. The domain subqueries lived there, and the base
+  layer imported the app it describes. Naming an app's choices to publish
+  them is another thing, and it is fine: `/meta/` lists every enum, and
+  one place has to.
+
 ## Settings
 
 The split is by who named the setting.
@@ -91,11 +116,45 @@ Every behaviour change carries a test. The suite runs with no network:
 adapters are tested against recorded fixtures.
 
 A test's comment says what would break if the assertion failed.
+If the answer is "nothing", the test does not earn its place.
+
+**Assert on behaviour, not arrangement.** Field order, section titles and
+`list_display` contents change for cosmetic reasons. A test that pins
+them fails on a harmless edit and catches no defect. One pinned the four
+component fieldsets in order. Moving two lines then cost a test edit, and
+it had never caught a bug.
+
+**A test fails only when something is broken.** A reasonable refactor
+breaks a wrong test and nothing else.
+
+**Never restate the implementation.** A test that computes its expected
+value the way the code does passes while both are wrong. Write the
+expected value out.
+
+**No test-only production code.** No argument, method, flag or branch
+exists so that a test can reach something. A path no caller reaches is a
+path the test should not reach either.
+
+**Enter through the front door.** Use the API client, the admin client or
+the management command. Call an internal directly only when no pathway
+reaches it.
+
+**Every assertion can fail.** Watch it fail once, before the code exists.
+`assert fieldsets[3] is not None` held on every possible input.
+
+**Test what this project decided.** Django and DRF are already tested.
+That a `CharField` stores a string is theirs. That a poller claims an
+incident inside the window is ours.
+
+**In the admin, test the logic, not the form.** Worth pinning: a
+read-only field the model maintains, a queryset the page filters, what
+`list_editable` writes, which user `created_by` records. Not which
+fields appear, or in what order.
 
 ```sh
-just test        # the suite
-just test-cov    # with the coverage gate
+just test        # the suite, host and bin/ scripts together
 just lint        # ruff check and format
+just check       # every check CI runs, coverage gate included
 ```
 
 ## Database
@@ -117,6 +176,31 @@ does not help answer it does not belong there.
 One theme, dark. `UNFOLD["THEME"]` forces it, so a class with no `dark:`
 variant still lands on the right ground.
 
+**The change view holds every field.** A model field missing from every
+fieldset is invisible and unreachable, and a changelist column with no
+place on the form makes opening a row answer less than the list did.
+`Service.source` recorded how a service arrived and reached no form at
+all. A value computed from related rows lands as a readonly field, not
+nowhere. So does provenance: a field recording how a row arrived is
+shown and never typed, because an editable one can be made to lie.
+
+**A column header is the name of its field.** The list and the form show
+the same data, so they use the same word. A column headed `State` over
+`is_archived` sent a reader looking for a field of that name. When the
+two disagree the header gives way: the field name is what the model, the
+API, the filters and every query already say.
+
+**A column that only redraws a field is the field.** Put the field name
+in `list_display`. Django draws a boolean as a tick, takes the header
+from the model and sorts the column, none of it asked for. Hand-rolling
+those three is where the header `State` came from. Keep a method only
+where it does what a field cannot: composing several, following a
+relation, or building a link.
+
+**A column the list shows, the list filters.** If it is worth a column,
+it is worth narrowing by. The converse does not hold: a filter may
+narrow by something no column shows.
+
 ## Commits
 
 A lowercase conventional prefix, then a declarative clause.

README.md

@@ -20,13 +20,14 @@ Each worktree gets its own ports and database.
 | | |
 | --- | --- |
 | `just init` | services, dependencies, migrations, admin, hooks |
-| `just dev` | server and poller together |
+| `just dev` | postgres, redis, migrations, then the server and poller |
 | `just test` | the suite, on the host |
 | `just check` | everything CI runs, in the image CI runs it in |
 | `just lint` | fix and format |
 | `just info` | this worktree's ports and database |
 | `just reset` | drop the database and build it again |
-| `just check-pages` | probe every recorded status page |
+| `just clean` | stop this checkout's containers |
+| `just probe-pages` | probe every recorded status page |
 | `just release v0.1.0` | tag, build, sign, deploy |
 | `just deploy` | redeploy the current image |
 

api/api/defaults.py

@@ -69,24 +69,27 @@ def parse(cls, value):
             ) from error
 
 
-# Which deployment this is. We named it, so it is resolved here, and
-# `debug` and `secret_key` in `settings.py` read it rather than being
-# handed it.
+# Which deployment this is. We named it, so `debug` and `secret_key`
+# in `settings.py` read it here rather than being handed it.
 ENVIRONMENT = Environment.parse(os.environ.get("ENVIRONMENT"))
 
 
 class Throttle(StrEnum):
     """A rate this deployment enforces.
 
-    A view names its scope and `settings.py` gives it a rate, so the
-    string was written twice and had to match. DRF names the first two;
-    we named the rest.
+    A view names its scope and `settings.py` gives it a rate. The two
+    spellings had to match. DRF names the first two; we named the
+    rest.
     """
 
     ANONYMOUS = "anon"
     SIGNED_IN = "user"
     IMPORT = "import"
     MAGIC_LINK = "magic-link"
+    # Its own bucket, not IMPORT's. Add-by-URL tries an import, and on
+    # a miss sends the same URL here. One scope would let the first
+    # call spend the second's budget.
+    SERVICE_REQUEST = "service-request"
 
 
 # Reading the catalog is the point, so the plain rates are wide. Each of
@@ -97,6 +100,7 @@ class Throttle(StrEnum):
     Throttle.SIGNED_IN: "600/min",
     Throttle.IMPORT: "6/min",
     Throttle.MAGIC_LINK: "5/hour",
+    Throttle.SERVICE_REQUEST: "6/min",
 }
 
 
@@ -120,6 +124,13 @@ class Throttle(StrEnum):
 # Long enough to read a week of failures, and no longer.
 POLL_RUN_RETENTION_DAYS = 30
 
+# How far back a provider's event may start and still claim one we
+# opened. Providers back-date `starts_at` to when an incident really
+# began, which is before our poll saw it.
+EVENT_CLAIM_WINDOW = timedelta(
+    seconds=int(os.environ.get("EVENT_CLAIM_WINDOW_SECONDS", "3600"))
+)
+
 # Who the system writes as. RFC 2606 reserves the domain. No mail leaves
 # for it, and nobody can hold the address.
 SYSTEM_EMAIL = "system@statusboard.invalid"

api/api/settings.py

@@ -13,6 +13,7 @@
     APP_URL,
     DEFAULT_PAGE_SIZE,
     ENVIRONMENT,
+    EVENT_CLAIM_WINDOW,
     MAGIC_LINK_TTL,
     MAX_PAGE_SIZE,
     POLL_COOLDOWN_SECONDS,
@@ -146,9 +147,6 @@
         "rest_framework.filters.OrderingFilter",
         "common.filters.FieldsBackend",
     ],
-    # The contract calls it `q`, and DRF's SearchFilter calls it
-    # `search`. One name, and the schema documents it.
-    "SEARCH_PARAM": "q",
     # The contract has always answered 429, and nothing raised one. See
     # `Throttle` for what each rate is protecting.
     "DEFAULT_THROTTLE_CLASSES": [
@@ -279,15 +277,18 @@
     "COMMAND": {"search_models": True, "show_history": True},
     # The sidebar is two levels deep. It cannot nest an item under an
     # item, so tabs carry the relationship. A component belongs to a
-    # service, and a status history to a component. All four are one
-    # page. The sidebar entry stays active on any of its tabs.
+    # service, and a status history to a component. A service request
+    # names something the catalog lacks, so it lives beside the catalog
+    # too. All five are one page. The sidebar entry stays active on any
+    # of its tabs.
     "TABS": [
         {
             "models": [
                 "catalog.service",
                 "catalog.servicecomponent",
                 "status.serviceevent",
                 "status.componentstatus",
+                "catalog.servicerequest",
             ],
             "items": [
                 {
@@ -306,6 +307,10 @@
                     "title": _("Status history"),
                     "link": reverse_lazy("admin:status_componentstatus_changelist"),
                 },
+                {
+                    "title": _("Service requests"),
+                    "link": reverse_lazy("admin:catalog_servicerequest_changelist"),
+                },
             ],
         },
         {
@@ -333,6 +338,26 @@
                 },
             ],
         },
+        {
+            # A magic link belongs to a user. It has no reason to be
+            # findable on its own.
+            "models": [
+                "authentication.user",
+                "authentication.magiclinktoken",
+            ],
+            "items": [
+                {
+                    "title": _("Users"),
+                    "link": reverse_lazy("admin:authentication_user_changelist"),
+                },
+                {
+                    "title": _("Magic links"),
+                    "link": reverse_lazy(
+                        "admin:authentication_magiclinktoken_changelist"
+                    ),
+                },
+            ],
+        },
     ],
     "SIDEBAR": {
         "show_search": True,
@@ -350,7 +375,9 @@
                         "link": reverse_lazy("admin:index"),
                     },
                     {
-                        "title": _("Services"),
+                        # Five models across catalog and status answer
+                        # here now, not only the services themselves.
+                        "title": _("Catalog"),
                         "icon": "lan",
                         "link": reverse_lazy("admin:catalog_service_changelist"),
                     },
@@ -380,11 +407,17 @@
     "VERSION": "1.0.0",
     "SERVE_INCLUDE_SCHEMA": False,
     "COMPONENT_SPLIT_REQUEST": True,
+    # EventUpdate.source and ServiceEvent.detected_by share one choice
+    # set. Without this, the generator names the same enum twice.
+    "ENUM_NAME_OVERRIDES": {
+        "EventSourceEnum": "status.choices.EventSource",
+    },
     "TAGS": [
         {"name": "meta"},
         {"name": "auth"},
         {"name": "me"},
         {"name": "catalog"},
+        {"name": "status"},
         {"name": "board"},
     ],
 }

api/api/urls.py

@@ -17,4 +17,5 @@
     path("", include("authentication.urls")),
     path("", include("catalog.urls")),
     path("", include("dashboards.urls")),
+    path("", include("status.urls")),
 ]