Server comments describe the code to a stranger (#6221)

Rule 32 "Comments describe the product to a stranger" sweep over
src/, alembic/ and tests/. Comments and docstrings now say what the code
does and the reason as a present-tense constraint, briefly.

Removed:
- issue, task, note, rule, milestone and family-idea references
- "used to" / before-and-after narration
- quotes of decisions and incident stories from the deploying instance
- paragraph-length arguments, where a line or two carries the fact

Kept every hazard as a present-tense fact, e.g. timing oracles, the
proxy hop direction, and migrations that must stay frozen.

Also:
- Three test names lose "still"/"used to"/"pre_m304" phrasing.
- pyproject's description drops "FabledSword family".

The history these comments carried stays in Scribe and in git log.
A comment-stripping diff (Scribe snippet #6226 "codeonly.py — prove a
diff changed only comments") shows no code changed apart from the
renamed tests and the description string.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/test_client_dist.py

@@ -14,28 +14,17 @@ from inkwell.client_dist import (
 )
 from inkwell.config import Config
 
-# DB-free, like the rest of this suite — the test lane runs no Postgres. That is
-# why the advertisement is asserted through `advertisement()` rather than through
-# `/api/config`: the route is a one-line merge of this dict into a payload whose
-# other half needs a database, and testing it here tests the part that can be wrong.
-#
-# The routes below ARE exercised, because none opens a session: the metadata route
-# only stats files, and the download's 401 is returned before any token lookup.
+# DB-free, so the advertisement is asserted through `advertisement()` rather than
+# `/api/config`, whose other half needs a database. The routes below are exercised:
+# none opens a session.
 
 PAYLOAD = b"not really a client, but the server only ever stats it"
 
-# Every test that is about the MECHANISM rather than about one platform runs
-# against all of them. The bugs this module can have — a sidecar describing a
-# different build, a half-finished copy shadowing a good one — are not
-# platform-specific, and a suite that only ever exercised Android is how the other
-# four would ship untested.
+# Tests about the mechanism rather than one platform run against every platform.
 ALL_IDS = [p.id for p in PLATFORMS]
 
-# `version_code` is "whatever this platform's comparator reads", and that is not one
-# type. Android's install gate compares an integer; the desktop's updater compares
-# Tauri's semver key. The tests carry both shapes for the same reason the module
-# does — a suite that only ever wrote integers would pass while every desktop
-# sidecar CI writes was being rejected.
+# `version_code` is an integer for Android and Tauri's semver key for the desktop,
+# so the tests write both shapes.
 ANDROID_CODE = 3503708
 DESKTOP_CODE = "1.0.3503707"
 
@@ -58,10 +47,8 @@ def coded(platform_id: str, value: int):
 def _empty_baked_client(tmp_path, monkeypatch):
     """Point the baked-in copy at an empty directory.
 
-    In a source checkout `src/inkwell/client/` does not exist, so these tests
-    would pass anyway — but only by accident of where they are run. A built image
-    has real clients there, and a test that silently depends on which tree it is in
-    is one that will eventually lie.
+    A built image has real clients in `src/inkwell/client/`, so the tests must not
+    depend on which tree they run in.
     """
     monkeypatch.setattr(client_dist, "BAKED_ROOT", tmp_path / "baked")
     yield
@@ -121,8 +108,7 @@ def test_the_android_names_are_the_ones_the_image_build_writes():
     with nothing checking them against each other, so a rename on one side reads as
     "no Android client" on the other rather than as an error.
 
-    Phones never ask for these names; they poll `/api/client/android`. The names
-    changed once, with the rename to Inkwell (Scribe note 5071).
+    Phones never ask for these names; they poll `/api/client/android`.
     """
     assert BY_ID["android"].artifact == "inkwell.apk"
     assert BY_ID["android"].sidecar == "inkwell-android.json"
@@ -139,8 +125,7 @@ def test_an_absent_client_is_no_client(platform_id):
 def test_a_server_holding_nothing_advertises_no_keys_at_all():
     """The KEYS are missing, not null.
 
-    A client testing for one then gets an unambiguous answer rather than having to
-    tell "this server has no client" apart from "this server predates the feature".
+    A client testing for one gets an unambiguous answer.
     """
     assert releases() == {}
     assert advertisement() == {}
@@ -234,7 +219,7 @@ def test_a_present_client_reports_what_a_comparator_reads(platform_id):
     assert not found["url"].startswith("http")
 
 
-def test_the_android_payload_still_carries_every_field_it_used_to():
+def test_the_android_payload_carries_every_field_phones_read():
     """Phones in the field parse this. Fields may be ADDED — `ClientRelease` in
     core/src/sync/client.rs is a plain serde struct and ignores what it does not
     know — but none of these may move or change meaning."""
@@ -303,15 +288,13 @@ def test_a_dropped_in_build_beats_the_one_the_image_shipped():
     """Someone who deliberately put a build on the volume wants that build."""
     place("android", root=client_dist.BAKED_ROOT, version_code=300)
     place("android", version_code=99)
-    # Lower version and all — precedence is about intent, not about newness. An
-    # operator pinning an older client is doing it on purpose.
+    # Even at a lower version: dropping in an older client is deliberate.
     assert release("android")["version_code"] == 99
 
 
 def test_precedence_is_decided_per_platform_not_for_the_whole_set():
-    """THE trap this table introduces. Dropping in one client must not retract the
-    other four — "first directory holding anything wins" would mean overriding the
-    APK silently takes the desktop downloads offline."""
+    """Dropping in one client must not retract the other four, as "first directory
+    holding anything wins" would."""
     for platform_id in ALL_IDS:
         place(platform_id, root=client_dist.BAKED_ROOT, version_code=300)
     place("android", version_code=99)
@@ -326,8 +309,7 @@ def test_precedence_is_decided_per_platform_not_for_the_whole_set():
 def test_a_broken_drop_in_does_not_shadow_the_baked_copy():
     """A half-finished copy onto the volume must not take the app offline.
 
-    This is the failure the copy-order advice in docs/android-distribution.md is
-    about, and the server should ride it out rather than go dark.
+    The failure the copy-order advice in docs/android-distribution.md is about.
     """
     place("android", root=client_dist.BAKED_ROOT, version_code=300)
     place("android", size=999_999)  # sidecar describing a different build
@@ -424,7 +406,7 @@ async def test_a_server_without_the_appimage_404s_its_updater_manifest(app):
     assert resp.status_code == 404
 
 
-# --- serving the bytes (#5118, family idea #5103 practice 6) -----------------
+# --- serving the bytes ------------------------------------------------------
 #
 # `send_artifact` is called directly in a request context: the route in front of it
 # needs a signed-in account, and this suite has no database to sign one in with.