@@ -176,6 +176,10 @@ jobs:
       - name: Install Python dependencies
         run: |
           pip install -r requirements.txt
+          # pytest: the "Run the unit tests" step below needs it, and nothing else installs it.
+          # setup-python gives a clean interpreter, so the runner image's own packages are not
+          # on this path - without this line that step dies on `No module named pytest`.
+          pip install pytest
 
       - name: Build the Pebble renderer
         run: |
@@ -197,7 +201,13 @@ jobs:
           sqlite3 documentation.db "SELECT 1;" > /dev/null
           echo "DB_SIZE=$(stat -c%s documentation.db 2>/dev/null || stat -f%z documentation.db)" >> "$GITHUB_ENV"
 
+      # dry_run-gated, and paired with the release below. The baton stands for the lock on the
+      # shared file this workflow rewrites, so a dry run - which rewrites nothing - should never
+      # take it. Before this was gated, the default dispatch (dry_run is true) grabbed a baton
+      # that the release, gated on dry_run being false, then never dropped.
       - name: 'Notify Slack: build started'
+        id: slack_baton_taken
+        if: ${{ !inputs.dry_run }}
         env:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
@@ -303,8 +313,14 @@ jobs:
           cp "$STAGED_DB" "$DB_PATH"
           echo "Wrote updated documentation.db back to $DB_PATH"
 
+      # always(), keyed off whether the acquire actually ran rather than off dry_run again.
+      # Everything from the checkout to the Drive download can fail before "build started" is
+      # reached, and a release gated only on dry_run announces a drop for a baton nobody took;
+      # without always(), a failure after it leaves the baton held. The acquire's own conclusion
+      # answers both - 'skipped' on a dry run and on an early failure, 'success' exactly when
+      # Slack was told the baton had been taken.
       - name: 'Notify Slack: build complete'
-        if: ${{ !inputs.dry_run }}
+        if: ${{ always() && steps.slack_baton_taken.conclusion == 'success' }}
         env:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
 
@@ -57,10 +57,12 @@ permissions:
   contents: read
   id-token: write
 
-# This workflow overwrites a single shared Drive file - never let two runs
-# race to upload against each other.
+# Every workflow that rewrites the shared documentation.db on Drive shares this group, not just
+# the two runs of this one. Each does download -> modify -> upload against the same file, so an
+# Android run overlapping a Kotlin run means both start from the same revision and whichever
+# uploads second silently discards the other's work. A per-workflow group never saw that.
 concurrency:
-  group: build-android-docs
+  group: documentation-db
   cancel-in-progress: false
 
 on:
@@ -175,6 +177,10 @@ jobs:
       - name: Install Python dependencies
         run: |
           pip install -r requirements.txt
+          # pytest: the "Run the unit tests" step below needs it, and nothing else installs it.
+          # setup-python gives a clean interpreter, so the runner image's own packages are not
+          # on this path - without this line that step dies on `No module named pytest`.
+          pip install pytest
           # google-api-python-client & friends: Drive download/upload, same
           # libraries check-tools/download_database.py already depends on.
           pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
@@ -198,7 +204,11 @@ jobs:
         with:
           workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}
           service_account: ${{ secrets.GCP_WIF_SERVICE_ACCOUNT }}
+          # drive.readonly as well as drive.file: drive.file covers only files this app
+          # created or opened itself, and the step below downloads a database it did not.
+          # The same pair docdb-regression-test.yaml uses against the same file.
           access_token_scopes: |
+            https://www.googleapis.com/auth/drive.readonly
             https://www.googleapis.com/auth/drive.file
 
       - name: Download current documentation.db from Google Drive
@@ -214,7 +224,13 @@ jobs:
           rm -f documentation.zip
           echo "DB_SIZE=$(stat -c%s documentation.db 2>/dev/null || stat -f%z documentation.db)" >> "$GITHUB_ENV"
 
+      # dry_run-gated, and paired with the release below. The baton stands for the lock on the
+      # shared file this workflow rewrites, so a dry run - which rewrites nothing - should never
+      # take it. Before this was gated, the default dispatch (dry_run is true) grabbed a baton
+      # that the release, gated on dry_run being false, then never dropped.
       - name: 'Notify Slack: build started'
+        id: slack_baton_taken
+        if: ${{ !inputs.dry_run }}
         env:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
@@ -318,7 +334,14 @@ jobs:
 
       - name: Zip updated database for upload
         if: ${{ !inputs.dry_run }}
-        run: zip -j documentation.zip "$STAGED_DB"
+        run: |
+          # The member inside the zip has to be called documentation.db, not whatever this
+          # workflow happened to name its staging file: every reader of the Drive artifact looks
+          # for that exact name and fails outright without it - this workflow's own download step
+          # above, docdb-regression-test.yaml's daily run, and build-kotlin-docs.yaml. `zip -j`
+          # drops the directory but keeps the basename, so the rename has to happen first.
+          cp "$STAGED_DB" documentation.db
+          zip -j documentation.zip documentation.db
 
       - name: Upload updated database to Google Drive
         if: ${{ !inputs.dry_run }}
@@ -339,8 +362,14 @@ jobs:
           print(f"Uploaded new revision of {file_id}: {updated}")
           PYEOF
 
+      # always(), keyed off whether the acquire actually ran rather than off dry_run again.
+      # Everything from the checkout to the Drive download can fail before "build started" is
+      # reached, and a release gated only on dry_run announces a drop for a baton nobody took;
+      # without always(), a failure after it leaves the baton held. The acquire's own conclusion
+      # answers both - 'skipped' on a dry run and on an early failure, 'success' exactly when
+      # Slack was told the baton had been taken.
       - name: 'Notify Slack: build complete'
-        if: ${{ !inputs.dry_run }}
+        if: ${{ always() && steps.slack_baton_taken.conclusion == 'success' }}
         env:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
 
@@ -47,8 +47,10 @@ permissions:
 
 # This workflow overwrites a single shared Drive file - never let two runs
 # race to upload against each other.
+# Shared with build-android-docs.yaml: both rewrite the same documentation.db on Drive, so they
+# have to serialise against each other, not merely against a second run of themselves.
 concurrency:
-  group: build-kotlin-docs
+  group: documentation-db
   cancel-in-progress: false
 
 on:
 
@@ -124,8 +124,12 @@ def rewrite_link(url: str, page_dir: str, known: dict) -> str:
 
 
 def rewrite_document(node, page_dir: str, known: dict):
-    """Every link in a page document, rewritten. Mirrors HtmlLinks.java, which does this for the
-    standalone renderer; the two exist separately only because one is Java and one is Python."""
+    """Every link in a page document, rewritten.
+
+    HtmlLinks.java walks the document the same way for the standalone renderer, but the two are
+    not interchangeable: `rewrite_link` below also canonicalises each path's case against what
+    this database holds, which the renderer has no need of. See that class's own header.
+    """
     if isinstance(node, dict):
         result = {}
         for key, value in node.items():
@@ -218,7 +222,7 @@ def prepare(job: tuple, known: dict, compressor: DictionaryCompressor) -> tuple:
 
 
 def load(json_dir: Path, conn, workers: int, limit: int | None) -> dict:
-    stats = {"updated": 0, "inserted": 0, "skipped": 0, "raw": 0, "stored": 0}
+    stats = {"updated": 0, "inserted": 0, "skipped": 0, "stored": 0}
     language_id = get_id(conn, "Languages", "en-US")
     content_type_id, compress = get_content_type(conn, CONTENT_TYPE)
     if not compress:
@@ -267,6 +271,21 @@ def load(json_dir: Path, conn, workers: int, limit: int | None) -> dict:
     return stats
 
 
+# Every table this script reads or writes. Checked up front (see check_schema) because two of
+# them are only touched by record_version, at the very end: a database missing them would
+# otherwise take the whole load - 90 seconds locally, a quarter of an hour in CI - before saying
+# so. The same fail-fast the media optimizer does for its own content types.
+REQUIRED_TABLES = ("Content", "Languages", "ContentTypes", "Templates", "CompressionDictionary",
+                   "DocumentationDatabaseVersion", "LastChange")
+
+
+def check_schema(conn) -> list[str]:
+    """The tables in REQUIRED_TABLES this database does not have, in the order listed."""
+    present = {name for (name,) in conn.execute(
+        "SELECT name FROM sqlite_master WHERE type = 'table'")}
+    return [name for name in REQUIRED_TABLES if name not in present]
+
+
 def record_version(conn, stats: dict) -> None:
     """A row saying what changed, as the schema's own comment asks for. Minor, not major: nothing
     about the schema or the server's contract changes, a documentation set is re-expressed."""
@@ -306,6 +325,15 @@ def main(argv: list[str] | None = None) -> int:
     if args.out.resolve() == args.source.resolve():
         parser.error("--out must not be --source: the source database is never written to")
 
+    source_conn = sqlite3.connect(f"file:{args.source}?mode=ro", uri=True)
+    try:
+        missing = check_schema(source_conn)
+    finally:
+        source_conn.close()
+    if missing:
+        parser.error(f"{args.source} is missing table(s) this loader writes: "
+                     + ", ".join(missing))
+
     print(f"==> copying {args.source} -> {args.out}")
     shutil.copy2(args.source, args.out)
 
 
@@ -17,8 +17,14 @@
  *
  * It happens here rather than in a Pebble filter so that the templates need no filter of their
  * own: the database stores one self-contained template per row and evaluates it against the
- * page's JSON, with no opportunity to register anything. The same swap is implemented in
- * `load_android_json_db.py` for the same reason.
+ * page's JSON, with no opportunity to register anything.
+ *
+ * `load_android_json_db.py`'s `rewrite_link` does the corresponding job for the database, and is
+ * deliberately NOT identical: it also folds each path to the case the database spells it with,
+ * because the database holds pages the scrape spelled two ways (`StrictMode/` and `strictmode/`)
+ * and a link has to name the row that exists. There is no such second spelling here - this
+ * renderer writes the HTML tree itself, mirroring the JSON tree's own paths - so the swap below
+ * is the whole job. Change one and the other does not automatically need the same change.
  */
 final class HtmlLinks {
 
 
@@ -201,3 +201,20 @@
 {% endif %}
 </div>
 {% endmacro %}
+
+{#
+  The page footer, including the legend for the red links.
+
+  A macro rather than three copies because the colouring is applied by `reference` above, which
+  every page kind uses: a class page, a package summary and an index all render red links, so all
+  three need the sentence that says what red means. It lived on class.peb alone, and a reader
+  landing on a package summary saw the colour with nothing to explain it.
+#}
+{% macro pageFooter() %}
+<footer>
+<p>Generated from the developer.android.com reference scrape. A link shown in red is not part of
+this documentation: nearly all of them leave for the web and need a network connection -- most
+back to developer.android.com, the rest to other sites the reference cites -- and a handful name
+nothing at all, because the <code>href</code> in the source is malformed.</p>
+</footer>
+{% endmacro %}
@@ -103,11 +103,6 @@
 {% endfor %}
 
 </main>
-<footer>
-<p>Generated from the developer.android.com reference scrape. A link shown in red is not part of
-this documentation: nearly all of them leave for the web and need a network connection -- most
-back to developer.android.com, the rest to other sites the reference cites -- and a handful name
-nothing at all, because the <code>href</code> in the source is malformed.</p>
-</footer>
+{{ pageFooter() }}
 </body>
 </html>
@@ -50,8 +50,6 @@
 {% endfor %}
 
 </main>
-<footer>
-<p>Generated from the developer.android.com reference scrape.</p>
-</footer>
+{{ pageFooter() }}
 </body>
 </html>
@@ -46,8 +46,6 @@
 {% endfor %}
 
 </main>
-<footer>
-<p>Generated from the developer.android.com reference scrape.</p>
-</footer>
+{{ pageFooter() }}
 </body>
 </html>
@@ -1102,3 +1102,34 @@ def test_a_class_the_source_already_set_is_kept(self, linker, tmp_path):
         """
         page = parse(markup, "android/demo/Widget.html", linker, tmp_path)
         assert 'class="api-reference external-link"' in page["description"]
+
+
+class TestKindTablesAgree:
+    """Three tables have to name the same kinds, and none of them says so.
+
+    A kind is counted by `_MEMBER_KINDS`, described only if it is in `_MEMBER_ORDER`, and
+    labelled only if it is in `_PLURALS`. `describe_tally` iterates the order and skips anything
+    not in it, so a kind missing there is dropped from every package's prose while still riding
+    on the row as data; `count_label` subscripts `_PLURALS`, so a kind missing there raises
+    KeyError after the whole corpus has been converted.
+    """
+
+    def test_every_counted_member_kind_is_described(self):
+        counted = set(extractor._MEMBER_KINDS.values()) | {"nested type"}
+        assert counted == set(extractor._MEMBER_ORDER)
+
+    def test_every_described_kind_has_a_plural(self):
+        assert set(extractor._MEMBER_ORDER) <= set(extractor._PLURALS)
+        assert set(extractor._TYPE_ORDER) <= set(extractor._PLURALS)
+
+    def test_every_kind_class_kind_returns_is_described(self):
+        # package_tally falls back to "class" for a page whose kind could not be read, so that
+        # one has to be in the order too.
+        produced = {"annotation", "enum", "object", "record", "interface", "class"}
+        assert produced == set(extractor._TYPE_ORDER)
+
+    def test_count_label_covers_every_kind(self):
+        # The subscript in count_label is the crash; this is the cheapest proof it cannot fire.
+        for kind in (*extractor._TYPE_ORDER, *extractor._MEMBER_ORDER):
+            assert extractor.count_label(2, kind).startswith("2 ")
+