From 450952cd6480c774034ca99178b9bd968227cecd Mon Sep 17 00:00:00 2001
From: Leo Vasanko <leo@git>
Date: Thu, 6 Aug 2026 23:07:05 +0000
Subject: [PATCH] Document transaction log headers: extra, logheader, toggles

---
 docs/database.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/database.md b/docs/database.md
index 6c5765b..f7f09eb 100644
--- a/docs/database.md
+++ b/docs/database.md
@@ -197,6 +197,40 @@ def resolve_user_key(value: str) -> str | None:
     return names_by_id.get(value)
 ```
 
+#### Transaction Log Headers
+
+- By default a transaction is logged with an `action by user` header followed
+  by the diff lines.  Added paths are colored green, deleted paths red.
+- `kanta.transaction(..., extra=...)` accepts display-only metadata that is
+  used for logging and is never persisted in the `ChangeRecord`:
+  - a string is appended literally after the action in the default header,
+  - a dict is passed to a registered `@kanta.logheader` callback; if it has
+    no `"target"` key, the database filename is inserted as the target.
+- Register a `@kanta.logheader` callback to replace the entire header line.
+  It may declare `action: str`, `user: str | None` and `extra: dict | None`
+  parameters, and can also have `DictPre`/`DictPost` state dicts and the
+  `Kanta` instance injected.  It must be synchronous and return `str | None`.
+- Multiple logheader callbacks are stacked in registration order; the first
+  callback to return a non-`None` result wins.  If all return `None`, Kanta
+  falls back to the default header.  The `user` value passed to the callback
+  has already been through the `logfmt` formatters.
+- The header and diff parts can be toggled independently per transaction:
+  `kanta.transaction(..., log={"header": True, "diff": False})`.
+
+```python
+@kanta.logheader
+def format_header(action: str, user: str | None, extra: dict | None) -> str:
+    session = extra.get("session_id", "-")
+    return f"{user:<20} {session:>2}  {action}  {extra['target']}"
+
+with kanta.transaction(
+    action="update",
+    user="alice",
+    extra={"session_id": 3, "target": "Project Name (abcd1234)"},
+) as data:
+    ...
+```
+
 ## Migrations
 
 - Migration source is configured on `Kanta(...)` via `migrations=`.