Address review: restore remaining invariant comments, convert root to def, add dev stress-test runbook

- Restore the five invariant comment blocks dropped by the
  _sync_update_assignments extraction (no-op updated_at rationale,
  full-replacement-set semantics, valid_community_ids bootstrap path,
  comments None-vs-[] semantics, assignments_updated_at staleness contract)
- Convert root() to def, matching the convention comment above it
- stress_test/README.md: "Dev stack run" section — env overrides, capacity
  sizing, seed-slug precheck

Author: fangge518

backend/app/main.py

@@ -278,7 +278,7 @@ def duplicate_document_comments(
 
 
 @app.get("/")
-async def root():
+def root():
     return {"message": "Hello World"}
 
 
@@ -790,6 +790,9 @@ def _sync_update_assignments(
             status_code=status.HTTP_409_CONFLICT,
             detail="Document has been updated since the last update",
         )
+    # Track whether anything actually changed so we can skip the updated_at bump on
+    # true no-op requests (which would otherwise break optimistic concurrency for
+    # other clients).
     mutated = False
 
     # Snapshot pre-existing district-mode assignments to compute which zones
@@ -814,6 +817,10 @@ def _sync_update_assignments(
             {"document_id": document_id},
         )
 
+    # The assignments field is always a full replacement set:
+    #   [] means "delete all assignments" (user cleared everything)
+    #   [...] means "replace with these assignments"
+    # Always DELETE existing rows, then INSERT new ones if any.
     delete_result = session.connection().execute(
         text(f"DELETE FROM {assignment_table} WHERE document_id = :document_id"),
         {"document_id": document_id},
@@ -823,6 +830,12 @@ def _sync_update_assignments(
     inserted_count = 0
     has_assignments = len(assignments) > 0
     if has_assignments:
+        # For community maps, build the set of valid community_ids so we can reject
+        # orphan-producing writes before they hit the table. 0 is the "unassigned"
+        # sentinel; positive ids must exist in the effective metadata list. Skip the
+        # check entirely when no metadata has been established yet (either in this
+        # request or previously persisted) — that's the bootstrap path where the UI
+        # writes assignments before the metadata save lands.
         valid_community_ids: set[int] | None = None
         if is_community_map:
             if validated_community_metadata is not None:
@@ -978,6 +991,7 @@ def _sync_update_assignments(
     ):
         mutated = True
 
+    # Sync scoped comments via comments schema (None = no change, [] = delete all)
     if data.comments is not None:
         comment_inputs: list[DistrictCommentInput] = []
         for c in data.comments:
@@ -1050,10 +1064,16 @@ def _sync_update_assignments(
     if mutated:
         updated_at = update_timestamp(session, document_id)
     else:
+        # No-op request (e.g. assignments=[] on an already-empty doc with no metadata
+        # or comment changes). Keep updated_at pinned to its current value so other
+        # clients' optimistic-concurrency windows aren't invalidated.
         updated_at = session.exec(
             select(Document.updated_at).where(Document.document_id == document_id)
         ).one()
     if dirty_zones:
+        # Bump assignments_updated_at so /stats can tell that the CDN object
+        # is stale and republish, even on the path that doesn't otherwise
+        # change document.updated_at.
         session.connection().execute(
             text(
                 "UPDATE document.document SET assignments_updated_at = NOW() "

backend/stress_test/README.md

@@ -179,6 +179,35 @@ var. `stress-test-seed` uses no CDN override, so it reads the real
 `stress-test/config.json`; it aborts before creating anything if any config
 slug is missing from the prod `districtrmap` table.)
 
+## Dev stack run
+
+The prod defaults above are all env overrides — no script changes needed. Dev
+resources use the same `Name`-tag scheme with the `districtr-dev` prefix, so
+provisioning/discovery works identically:
+
+```sh
+# provision.sh / teardown.sh
+export STACK_PREFIX=districtr-dev
+# run.sh + ECS Exec one-liners
+export BASE_URL=https://api.dev.districtr.org
+export CLUSTER=$(cd ../../infra && pulumi stack select dev >/dev/null && pulumi stack output clusterName)
+export RESULTS_BUCKET=$(cd ../../infra && pulumi stack output s3BucketName 2>/dev/null || true)  # dev backend bucket
+```
+
+Caveats specific to dev:
+
+- **Capacity**: dev runs 1–2 backend tasks at half prod CPU and a
+  `db.t4g.small` (vs `large`) — roughly ⅛–¼ of prod capacity. Size runs with
+  `SCALE` accordingly (e.g. `SCALE=0.25` ≈ 3,200 users); a full-scale run
+  saturates the stack and the failure noise drowns whatever you were
+  measuring.
+- **Seed slugs**: `stress-test-seed` validates the config JSON's slugs against
+  the target DB's `districtrmap` table and aborts if any is missing. Dev
+  shares the prod CDN config by default — verify the 10 slugs exist in the
+  dev DB first (or point `STRESS_CONFIG_URL` at a dev-specific config).
+- **Comparisons**: only compare runs against the *same* stack at the same
+  `SCALE`. Dev numbers are not comparable to prod numbers.
+
 ## Runner (ephemeral prod EC2)
 
 Scripts in `runner/`. `provision.sh`/`teardown.sh` run on the operator's