docs: merge the upsert ADRs, drop replaced and non-ADR records, renumber (#62)

ADRs that a later decision replaces are now deleted once their reasoning moves
into the new record.

Author: lesnik512

AGENTS.md

@@ -187,6 +187,12 @@ env vars (see `docker-compose.yml`). `api_bootstrapper_config` builds the
   `ForeignKey`, a `return` from inside a transaction block, discarded work that
   is not dead code (`AuthenticateUserUseCase`'s hash-anyway). Alembic's own
   `# ###` autogenerate markers stay — they are regenerated on every migration.
+- **Coverage.** The suite runs at `--cov-fail-under=100` and no `# pragma: no cover`
+  appears anywhere. The only exemptions are structural: `[tool.coverage.run] omit`
+  for files the default run never imports, and `exclude_also` for
+  `if typing.TYPE_CHECKING:`. A branch that looks untestable gets a test that
+  produces its condition for real, such as the concurrent create tests'
+  second connection holding an uncommitted insert.
 - `ruff` is configured with `select = ["ALL"]` and a line length of 120 —
   expect strict lint. Type-check with `ty`.
 

docs/adr/0005-idempotency-scoped-per-chat.md

@@ -0,0 +1,8 @@
+# Idempotency is scoped per chat
+
+`messages` carries `UniqueConstraint("chat_id", "idempotency_key")`, and the
+send's `ON CONFLICT` names that constraint. Idempotency belongs to the operation
+"send this message to this chat", so a key reused in another chat is a different
+operation, not a retry. A global constraint on `idempotency_key` shipped first.
+A client that reused a key across chats got the other chat's message back, and
+the message it meant to send was never written.

docs/adr/0005-upsert-via-duplicate-key-recovery.md

@@ -0,0 +1,9 @@
+# Read-marker integrity
+
+`MarkReadUseCase` rejects a `last_read_message_id` that does not name a message
+in that chat with a `400`, and moving the marker to a lower id is a silent
+no-op. Accepting any id would let a client set its marker arbitrarily high and
+permanently zero its own unread counts, and storing self-inflicted corruption is
+worse than refusing the request. A lower id usually comes from a replayed or
+reordered request, which is not a client mistake worth reporting, so it gets the
+current marker back instead of an error.

docs/adr/0006-idempotency-scoped-per-chat.md

@@ -8,7 +8,7 @@ that user, and short-lived tokens with refresh because they replace the whole
 auth model. The cost is one primary-key lookup per authenticated request, on a
 session the middleware closes before the handler opens its own, so a request
 still holds one pooled connection at a time. That lookup is the read
-[ADR-0010](0010-auth-carries-an-actor-id.md) kept out of authentication; the
+[ADR-0008](0008-auth-carries-an-actor-id.md) kept out of authentication; the
 user row is still never loaded. A token without a `jti`, which includes every
 token issued before this change, gets a 401. Each logout prunes expired rows,
 so the table holds at most a token lifetime of logouts.