feat(#15): session audit log domain, store, and instrumentation

2026-05-07 12:16:54 +00:00
parent 6394b1fe8c
commit 35894bf89e
6 changed files with 508 additions and 0 deletions
@@ -0,0 +1,343 @@
+# Issue #15: Session Audit Log Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** Add transparent audit history for every session change, visible to GM in Web Dashboard.
+
+**Architecture:** PostgreSQL audit table + Dapper queries. Automatic logging inside mutating SessionService methods. New Razor page for GM history view.
+
+**Tech Stack:** C# 12, Blazor SSR, Dapper, PostgreSQL, xUnit.
+
+**Branch:** `issue-15-session-audit-log` (includes mobile UI bugfix cherry-pick)
+
+**Version Bump:** `1.10.1` → `1.10.2`
+
+---
+
+## Task 1: Database Migration (V013)
+
+**Objective:** Create `session_audit_log` table.
+
+**File:** Create `src/GmRelay.Bot/Migrations/V013__add_session_audit_log.sql`
+
+```sql
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+CREATE TABLE session_audit_log (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id          UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    actor_telegram_id   BIGINT NOT NULL,
+    actor_name          VARCHAR(255) NOT NULL,
+    change_type          VARCHAR(50) NOT NULL,
+                        CHECK (change_type IN ('Title','Time','Link','MaxPlayers','Status','WaitlistPromote','PlayerRemoved','BatchRescheduled','Cancelled')),
+    old_value           TEXT,
+    new_value           TEXT,
+    changed_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX ix_session_audit_log_session_id ON session_audit_log(session_id);
+CREATE INDEX ix_session_audit_log_changed_at ON session_audit_log(changed_at);
+```
+
+**Step 2:** Verify migration compiles: `psql $DATABASE_URL -f src/GmRelay.Bot/Migrations/V013__add_session_audit_log.sql` (optional, CI will test)
+
+**Step 3:** Commit: `git add src/GmRelay.Bot/Migrations/V013__add_session_audit_log.sql && git commit -m "chore(#15): add session_audit_log migration"`
+
+---
+
+## Task 2: Domain Model & Interface Methods
+
+**Objective:** Add `SessionAuditLogEntry` record and two new methods to `ISessionStore`.
+
+**Files:**
+- Modify: `src/GmRelay.Web/Services/ISessionStore.cs`
+- Modify: `src/GmRelay.Web/Services/SessionService.cs`
+
+**Step 1: Add record to ISessionStore.cs** (after PlayerAttendanceStats)
+
+```csharp
+public sealed record SessionAuditLogEntry(
+    Guid Id,
+    Guid SessionId,
+    long ActorTelegramId,
+    string ActorName,
+    string ChangeType,
+    string? OldValue,
+    string? NewValue,
+    DateTime ChangedAt
+);
+```
+
+**Step 2: Add methods to ISessionStore interface**
+
+```csharp
+Task LogSessionChangeAsync(Guid sessionId, long actorTelegramId, string actorName, string changeType, string? oldValue, string? newValue);
+Task<List<SessionAuditLogEntry>> GetSessionHistoryAsync(Guid sessionId);
+```
+
+**Step 3: Implement in SessionService.cs**
+
+```csharp
+public async Task LogSessionChangeAsync(Guid sessionId, long actorTelegramId, string actorName, string changeType, string? oldValue, string? newValue)
+{
+    using var connection = new NpgsqlConnection(connectionString);
+    await connection.ExecuteAsync(
+        "INSERT INTO session_audit_log (session_id, actor_telegram_id, actor_name, change_type, old_value, new_value) VALUES (@sessionId, @actorTelegramId, @actorName, @changeType, @oldValue, @newValue)",
+        new { sessionId, actorTelegramId, actorName, changeType, oldValue, newValue });
+}
+
+public async Task<List<SessionAuditLogEntry>> GetSessionHistoryAsync(Guid sessionId)
+{
+    using var connection = new NpgsqlConnection(connectionString);
+    var entries = await connection.QueryAsync<SessionAuditLogEntry>(
+        "SELECT id, session_id as SessionId, actor_telegram_id as ActorTelegramId, actor_name as ActorName, change_type as ChangeType, old_value as OldValue, new_value as NewValue, changed_at as ChangedAt FROM session_audit_log WHERE session_id = @sessionId ORDER BY changed_at DESC",
+        new { sessionId });
+    return entries.ToList();
+}
+```
+
+**Step 4:** Commit: `git add -A && git commit -m "feat(#15): add SessionAuditLogEntry and audit store methods"`
+
+---
+
+## Task 3: Instrument Mutating Methods
+
+**Objective:** Auto-log changes in key methods. Only log when value actually changes.
+
+**File:** Modify `src/GmRelay.Web/Services/SessionService.cs`
+
+**Step 1: Instrument UpdateSessionAsync**
+
+Before executing UPDATE, read current session. After UPDATE, compare and log each changed field:
+
+```csharp
+// After var currentSession = await GetSessionAsync(sessionId);
+// Before the UPDATE SQL:
+
+if (currentSession is not null)
+{
+    if (currentSession.Title != title)
+        await LogSessionChangeAsync(sessionId, /* actor will be passed from caller */ ...);
+}
+```
+
+**Problem:** SessionService doesn't know the actor (GM) telegram ID. Solution: add `long actorTelegramId` parameter to mutating methods, or use a decorator pattern.
+
+**Better approach:** Instrument in `AuthorizedSessionService` which already has `gmId`. That is the authorized wrapper.
+
+**Revised approach:** Add `IAuditLogger` interface and inject it. Or simpler: change `ISessionStore` mutating methods to accept `long actorTelegramId` and `string actorName` as last parameters.
+
+**Simpler approach for this plan:** Since all mutating methods in `ISessionStore` are called through `AuthorizedSessionService`, instrument in `AuthorizedSessionService` methods AFTER the underlying `SessionService` call. BUT we need old values. 
+
+**Final approach:** Change `ISessionStore` methods to include `actorTelegramId` parameter, and inside `SessionService` fetch old values and log.
+
+Let's add `long actorTelegramId` parameter to:
+- `UpdateSessionAsync`
+- `PromoteWaitlistedPlayerAsync`
+- `RemovePlayerFromSessionAsync`
+- `RescheduleBatchAsync`
+
+Wait, this is a bigger change. Let's be more pragmatic: add a new `IAuditService` that can be called from `AuthorizedSessionService` after mutations. `IAuditService` just wraps `ISessionStore.LogSessionChangeAsync`.
+
+Actually, simplest: add `actorTelegramId` and `actorName` parameters to `LogSessionChangeAsync` and call it from `AuthorizedSessionService` after each mutation. For old/new values, read the session before mutation in AuthorizedSessionService.
+
+**Plan:**
+- `AuthorizedSessionService.UpdateSessionForGmAsync`: read session before update, call update, then log differences.
+- Same pattern for other mutating methods.
+
+**Step 1: Read current session in AuthorizedSessionService.UpdateSessionForGmAsync**
+
+```csharp
+public async Task UpdateSessionForGmAsync(Guid sessionId, long gmId, string title, DateTime scheduledAt, string joinLink, int? maxPlayers)
+{
+    var groupId = await EnforceSessionOwnershipAsync(sessionId, gmId);
+    var before = await store.GetSessionAsync(sessionId);  // add this
+    await store.UpdateSessionAsync(sessionId, groupId, title, scheduledAt, joinLink, maxPlayers);
+    if (before is not null)
+    {
+        if (before.Title != title)
+            await store.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Title", before.Title, title);
+        if (before.ScheduledAt != scheduledAt)
+            await store.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Time", before.ScheduledAt.ToString("O"), scheduledAt.ToString("O"));
+        if (before.JoinLink != joinLink)
+            await store.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Link", before.JoinLink, joinLink);
+        if (before.MaxPlayers != maxPlayers)
+            await store.LogSessionChangeAsync(sessionId, gmId, "ГМ", "MaxPlayers", before.MaxPlayers?.ToString(), maxPlayers?.ToString());
+    }
+}
+```
+
+Wait, `EnforceSessionOwnershipAsync` returns `groupId` but we need it. Let me check the current AuthorizedSessionService code... We saw earlier it does `await EnforceSessionOwnershipAsync(sessionId, gmId)` then calls `store.UpdateSessionAsync`.
+
+Actually, looking at the compact output from earlier, `AuthorizedSessionService` has `EnforceSessionOwnershipAsync` as a private helper. Let me verify.
+
+From the compact output of AuthorizedSessionService earlier:
+```
+public async Task UpdateSessionForGmAsync(Guid sessionId, long gmId, string title, DateTime scheduledAt, string joinLink, int? maxPlayers)
+{
+    var groupId = await EnforceSessionOwnershipAsync(sessionId, gmId);
+    await store.UpdateSessionAsync(sessionId, groupId, title, scheduledAt, joinLink, maxPlayers);
+}
+```
+
+So it DOES return groupId. Perfect.
+
+But we need actor name. We can use the GM's display name from `GetGroupManagementForGmAsync` or just hardcode "ГМ" for now. Or we can query the player name. For simplicity, use "ГМ" + telegram ID, or query the player display name.
+
+Actually, let's query the GM name from the group or just use telegram ID as identifier. Since this is audit log, having human-readable name is better. We can pass `actorName` to the log method.
+
+Simpler: In `AuthorizedSessionService`, after `EnforceSessionOwnershipAsync`, we already know the group. We can get the GM name from group or just use a generic "ГМ" label. Actually, the telegram ID is sufficient for audit, and the display name can be resolved later in the UI.
+
+Let's just log `actor_telegram_id` and use "ГМ" as actor_name. Or better, query the player display name if needed.
+
+For this plan, let's keep it simple: log with `gmId` as actor_telegram_id and `"ГМ"` as actor_name. The UI can resolve the name.
+
+**Step 2: Instrument all mutating AuthorizedSessionService methods**
+
+Do this for:
+- `UpdateSessionForGmAsync` (Title, Time, Link, MaxPlayers)
+- `RescheduleBatchForGmAsync` (BatchRescheduled)
+- `PromoteWaitlistedPlayerForGmAsync` (WaitlistPromote)
+- `RemovePlayerFromSessionForGmAsync` (PlayerRemoved)
+- `UpdateBatchDetailsForGmAsync` (Title, Link)
+- `UpdateBatchNotificationModeForGmAsync` (maybe skip, internal)
+- `DeleteSessionHandler` in Bot features (Cancelled) — this is in Bot layer, not Web
+
+For Cancelled status, we need to instrument `CancelSessionHandler` in Bot. But the Bot handlers don't use `ISessionStore` directly... they use `SessionService` or direct SQL. Let me check.
+
+Actually, for this plan, focus on Web layer mutations first. Bot layer can be a follow-up.
+
+**Step 3: Commit:** `git add -A && git commit -m "feat(#15): instrument audit logging in AuthorizedSessionService"`
+
+---
+
+## Task 4: Web Page - SessionHistory.razor
+
+**Objective:** GM-visible timeline of session changes.
+
+**Files:**
+- Create: `src/GmRelay.Web/Components/Pages/SessionHistory.razor`
+- Modify: `src/GmRelay.Web/Components/Pages/GroupDetails.razor` (add "История" link)
+- Modify: `src/GmRelay.Web/Components/Pages/EditSession.razor` (add "История" link)
+
+**Step 1: Create SessionHistory.razor**
+
+Route: `@page "/session/{SessionId:guid}/history"`
+
+Layout: table with columns: Время, Актор, Тип изменения, Было, Стало.
+
+Colors: use existing CSS variables.
+
+**Step 2: Add navigation links**
+
+In GroupDetails.razor sessions table: add 📜 История column/link.
+In EditSession.razor: add button "📜 История изменений" linking to `/session/{SessionId}/history`.
+
+**Step 3: Commit:** `git add -A && git commit -m "feat(#15): add SessionHistory.razor page with audit timeline"`
+
+---
+
+## Task 5: FakeSessionStore + TDD Tests
+
+**Objective:** Test audit logging. RED-GREEN-REFACTOR.
+
+**Files:**
+- Modify: `tests/GmRelay.Bot.Tests/Web/AuthorizedSessionServiceTests.cs`
+
+**Step 1: RED — Write failing test**
+
+```csharp
+[Fact]
+public async Task UpdateSessionForGmAsync_LogsAudit_WhenTitleChanges()
+{
+    var gmId = 1001L;
+    var groupId = Guid.NewGuid();
+    var sessionId = Guid.NewGuid();
+    var store = new FakeSessionStore(
+        groups: [new(groupId, 42, "Alpha", gmId)],
+        sessions: [new(sessionId, groupId, "Session A", DateTime.UtcNow, "Planned", "https://example.test/a", Guid.NewGuid(), 10, 42, 4, 1, 0)]);
+    var service = new AuthorizedSessionService(store);
+
+    await service.UpdateSessionForGmAsync(sessionId, gmId, "Updated Title", DateTime.UtcNow.AddDays(1), "https://example.test/b", 5);
+
+    Assert.Single(store.LogEntries);
+    Assert.Equal("Title", store.LogEntries[0].ChangeType);
+    Assert.Equal("Session A", store.LogEntries[0].OldValue);
+    Assert.Equal("Updated Title", store.LogEntries[0].NewValue);
+}
+```
+
+Run: `dotnet test tests/GmRelay.Bot.Tests/Web/AuthorizedSessionServiceTests.cs --filter "FullyQualifiedName~LogsAudit" -v n`
+Expected: FAIL (FakeSessionStore doesn't have LogSessionChangeAsync / LogEntries)
+
+**Step 2: GREEN — Add to FakeSessionStore**
+
+Add `List<SessionAuditLogEntry> LogEntries` and implement `LogSessionChangeAsync` / `GetSessionHistoryAsync`.
+
+**Step 3: Refactor — Add more tests**
+
+- No audit when values unchanged
+- Audit for time change
+- Audit for link change
+- Audit for max players change
+- GetSessionHistoryAsync returns entries ordered by time desc
+
+**Step 4: Full suite**
+Run: `dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj`
+Expected: all pass
+
+**Step 5: Commit:** `git add -A && git commit -m "test(#15): add audit logging TDD tests"`
+
+---
+
+## Task 6: Bump Version & Docs
+
+**Objective:** Update version and documentation.
+
+**Files:**
+- Modify: `Directory.Build.props`
+- Modify: `compose.yaml`
+- Modify: `README.md`
+- Modify: Wiki «Руководство ГМа»
+
+**Step 1: Bump version to 1.10.2**
+
+**Step 2: Update README** — add "📜 История изменений сессии" bullet in Web Dashboard section.
+
+**Step 3: Update wiki** — add subsection «Журнал действий» with description of how to access `/session/{id}/history`, what change types are tracked, and how to read the timeline.
+
+**Step 4: Commit:** `git add -A && git commit -m "docs(#15): bump version to 1.10.2 and add audit log docs"`
+
+---
+
+## Task 7: Push & PR
+
+**Step 1:** `git push origin issue-15-session-audit-log`
+
+**Step 2:** Create PR via `mcp_gitea_pull_request_write`
+
+**Step 3:** Wait CI (`mcp_gitea_actions_run_read`)
+
+**Step 4:** Merge PR
+
+**Step 5:** Create tag `v1.10.2` and release
+
+---
+
+## Verification Checklist
+
+- [ ] Migration V013 applied successfully
+- [ ] `SessionAuditLogEntry` record defined in `ISessionStore.cs`
+- [ ] `LogSessionChangeAsync` and `GetSessionHistoryAsync` implemented in `SessionService.cs`
+- [ ] `AuthorizedSessionService` logs on value changes only
+- [ ] `SessionHistory.razor` renders timeline for GM
+- [ ] Links from GroupDetails and EditSession pages
+- [ ] `FakeSessionStore` implements audit methods
+- [ ] TDD tests: RED → GREEN → all pass
+- [ ] Full `dotnet test` suite: all pass
+- [ ] Version bumped to 1.10.2
+- [ ] README and wiki updated
+- [ ] CI run success
+- [ ] PR merged to main
+- [ ] Tag `v1.10.2` created
+- [ ] Release published
@@ -0,0 +1,16 @@
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+CREATE TABLE session_audit_log (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id          UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    actor_telegram_id   BIGINT NOT NULL,
+    actor_name          VARCHAR(255) NOT NULL,
+    change_type         VARCHAR(50) NOT NULL
+                        CHECK (change_type IN ('Title','Time','Link','MaxPlayers','Status','WaitlistPromote','PlayerRemoved','BatchRescheduled','Cancelled')),
+    old_value           TEXT,
+    new_value           TEXT,
+    changed_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX ix_session_audit_log_session_id ON session_audit_log(session_id);
+CREATE INDEX ix_session_audit_log_changed_at ON session_audit_log(changed_at);
@@ -66,6 +66,15 @@ public sealed class AuthorizedSessionService(ISessionStore sessionStore)
        }

        await sessionStore.UpdateSessionAsync(sessionId, session.GroupId, title, scheduledAt, joinLink, maxPlayers);
+
+        if (session.Title != title)
+            await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Title", session.Title, title);
+        if (session.ScheduledAt != scheduledAt)
+            await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Time", session.ScheduledAt.ToString("O"), scheduledAt.ToString("O"));
+        if (session.JoinLink != joinLink)
+            await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "Link", session.JoinLink, joinLink);
+        if (session.MaxPlayers != maxPlayers)
+            await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "MaxPlayers", session.MaxPlayers?.ToString(), maxPlayers?.ToString());
    }

    public async Task PromoteWaitlistedPlayerForGmAsync(Guid sessionId, long gmId)
@@ -77,6 +86,7 @@ public sealed class AuthorizedSessionService(ISessionStore sessionStore)
        }

        await sessionStore.PromoteWaitlistedPlayerAsync(sessionId, session.GroupId);
+        await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "WaitlistPromote", null, null);
    }

    public async Task UpdateBatchDetailsForGmAsync(Guid batchId, long gmId, string title, string joinLink)
@@ -115,6 +125,7 @@ public sealed class AuthorizedSessionService(ISessionStore sessionStore)
        }

        await sessionStore.RescheduleBatchAsync(batchId, batch.GroupId, firstScheduledAt, intervalDays);
+        await sessionStore.LogSessionChangeAsync(batchId, gmId, "ГМ", "BatchRescheduled", batch.FirstScheduledAt.ToString("O"), firstScheduledAt.ToString("O"));
    }

    public async Task<WebSessionBatch> CloneBatchForGmAsync(Guid batchId, long gmId, BatchCloneInterval interval)
@@ -239,6 +250,7 @@ public sealed class AuthorizedSessionService(ISessionStore sessionStore)
        }

        await sessionStore.RemovePlayerFromSessionAsync(sessionId, session.GroupId, participantId);
+        await sessionStore.LogSessionChangeAsync(sessionId, gmId, "ГМ", "PlayerRemoved", participantId.ToString(), null);
    }

    private async Task<bool> GroupBelongsToGmAsync(Guid groupId, long gmId)
@@ -15,6 +15,17 @@ public sealed record PlayerAttendanceStats(
    decimal AttendanceRate
 );

+public sealed record SessionAuditLogEntry(
+    Guid Id,
+    Guid SessionId,
+    long ActorTelegramId,
+    string ActorName,
+    string ChangeType,
+    string? OldValue,
+    string? NewValue,
+    DateTime ChangedAt
+);
+
 public interface ISessionStore
 {
    Task<List<WebGameGroup>> GetGroupsForGmAsync(long gmId);
@@ -41,4 +52,6 @@ public interface ISessionStore
    Task<List<WebParticipant>> GetSessionParticipantsAsync(Guid sessionId);
    Task RemovePlayerFromSessionAsync(Guid sessionId, Guid groupId, Guid participantId);
    Task<List<PlayerAttendanceStats>> GetGroupAttendanceStatsAsync(Guid groupId);
+    Task LogSessionChangeAsync(Guid sessionId, long actorTelegramId, string actorName, string changeType, string? oldValue, string? newValue);
+    Task<List<SessionAuditLogEntry>> GetSessionHistoryAsync(Guid sessionId);
 }
@@ -202,6 +202,32 @@ public sealed class SessionService(
            new { GroupId = groupId })).ToList();
    }

+    public async Task LogSessionChangeAsync(Guid sessionId, long actorTelegramId, string actorName, string changeType, string? oldValue, string? newValue)
+    {
+        await using var conn = await dataSource.OpenConnectionAsync();
+        await conn.ExecuteAsync(
+            """
+            INSERT INTO session_audit_log (session_id, actor_telegram_id, actor_name, change_type, old_value, new_value)
+            VALUES (@SessionId, @ActorTelegramId, @ActorName, @ChangeType, @OldValue, @NewValue)
+            """,
+            new { SessionId = sessionId, ActorTelegramId = actorTelegramId, ActorName = actorName, ChangeType = changeType, OldValue = oldValue, NewValue = newValue });
+    }
+
+    public async Task<List<SessionAuditLogEntry>> GetSessionHistoryAsync(Guid sessionId)
+    {
+        await using var conn = await dataSource.OpenConnectionAsync();
+        var entries = await conn.QueryAsync<SessionAuditLogEntry>(
+            """
+            SELECT id, session_id AS SessionId, actor_telegram_id AS ActorTelegramId, actor_name AS ActorName,
+                   change_type AS ChangeType, old_value AS OldValue, new_value AS NewValue, changed_at AS ChangedAt
+            FROM session_audit_log
+            WHERE session_id = @SessionId
+            ORDER BY changed_at DESC
+            """,
+            new { SessionId = sessionId });
+        return entries.ToList();
+    }
+
    public async Task AddGroupCoGmAsync(
        Guid groupId,
        long ownerTelegramId,
@@ -167,6 +167,81 @@ public sealed class AuthorizedSessionServiceTests
        Assert.Equal(5, store.LastUpdatedMaxPlayers);
    }

+    [Fact]
+    public async Task UpdateSessionForGmAsync_LogsAudit_WhenTitleChanges()
+    {
+        var gmId = 1001L;
+        var groupId = Guid.NewGuid();
+        var sessionId = Guid.NewGuid();
+        var store = new FakeSessionStore(
+            groups:
+            [
+                new(groupId, 42, "Alpha", gmId)
+            ],
+            sessions:
+            [
+                new(sessionId, groupId, "Session A", DateTime.UtcNow, "Planned", "https://example.test/a", Guid.NewGuid(), 10, 42, 4, 1, 0)
+            ]);
+        var service = new AuthorizedSessionService(store);
+
+        await service.UpdateSessionForGmAsync(sessionId, gmId, "Updated Title", DateTime.UtcNow.AddDays(1), "https://example.test/b", 5);
+
+        Assert.Single(store.LogEntries);
+        Assert.Equal("Title", store.LogEntries[0].ChangeType);
+        Assert.Equal("Session A", store.LogEntries[0].OldValue);
+        Assert.Equal("Updated Title", store.LogEntries[0].NewValue);
+    }
+
+    [Fact]
+    public async Task UpdateSessionForGmAsync_LogsMultipleAudits_WhenMultipleFieldsChange()
+    {
+        var gmId = 1001L;
+        var groupId = Guid.NewGuid();
+        var sessionId = Guid.NewGuid();
+        var originalTime = DateTime.UtcNow;
+        var store = new FakeSessionStore(
+            groups:
+            [
+                new(groupId, 42, "Alpha", gmId)
+            ],
+            sessions:
+            [
+                new(sessionId, groupId, "Session A", originalTime, "Planned", "https://example.test/a", Guid.NewGuid(), 10, 42, 4, 1, 0)
+            ]);
+        var service = new AuthorizedSessionService(store);
+
+        var newTime = originalTime.AddDays(1);
+        await service.UpdateSessionForGmAsync(sessionId, gmId, "Updated Title", newTime, "https://example.test/b", 5);
+
+        Assert.Equal(3, store.LogEntries.Count);
+        Assert.Contains(store.LogEntries, e => e.ChangeType == "Title");
+        Assert.Contains(store.LogEntries, e => e.ChangeType == "Time");
+        Assert.Contains(store.LogEntries, e => e.ChangeType == "Link");
+    }
+
+    [Fact]
+    public async Task UpdateSessionForGmAsync_DoesNotLogAudit_WhenNothingChanges()
+    {
+        var gmId = 1001L;
+        var groupId = Guid.NewGuid();
+        var sessionId = Guid.NewGuid();
+        var originalTime = DateTime.UtcNow;
+        var store = new FakeSessionStore(
+            groups:
+            [
+                new(groupId, 42, "Alpha", gmId)
+            ],
+            sessions:
+            [
+                new(sessionId, groupId, "Session A", originalTime, "Planned", "https://example.test/a", Guid.NewGuid(), 10, 42, 4, 1, 0)
+            ]);
+        var service = new AuthorizedSessionService(store);
+
+        await service.UpdateSessionForGmAsync(sessionId, gmId, "Session A", originalTime, "https://example.test/a", 10);
+
+        Assert.Empty(store.LogEntries);
+    }
+
    [Fact]
    public async Task PromoteWaitlistedPlayerForGmAsync_PromotesOwnedSession()
    {
@@ -659,6 +734,13 @@ public sealed class AuthorizedSessionServiceTests
        public Guid? LastRemovedPlayerSessionId { get; private set; }
        public Guid? LastRemovedPlayerGroupId { get; private set; }
        public Guid? LastRemovedPlayerParticipantId { get; private set; }
+        public List<SessionAuditLogEntry> LogEntries { get; private set; } = new();
+        public Guid? LastLogSessionId { get; private set; }
+        public long? LastLogActorTelegramId { get; private set; }
+        public string? LastLogActorName { get; private set; }
+        public string? LastLogChangeType { get; private set; }
+        public string? LastLogOldValue { get; private set; }
+        public string? LastLogNewValue { get; private set; }

        public Task<List<WebGameGroup>> GetGroupsForGmAsync(long gmId) =>
            Task.FromResult(groupsById.Values.Where(group => IsManager(group.Id, gmId)).ToList());
@@ -889,6 +971,22 @@ public sealed class AuthorizedSessionServiceTests
        public Task<List<PlayerAttendanceStats>> GetGroupAttendanceStatsAsync(Guid groupId) =>
            Task.FromResult(new List<PlayerAttendanceStats>());

+        public Task LogSessionChangeAsync(Guid sessionId, long actorTelegramId, string actorName, string changeType, string? oldValue, string? newValue)
+        {
+            var entry = new SessionAuditLogEntry(Guid.NewGuid(), sessionId, actorTelegramId, actorName, changeType, oldValue, newValue, DateTime.UtcNow);
+            LogEntries.Add(entry);
+            LastLogSessionId = sessionId;
+            LastLogActorTelegramId = actorTelegramId;
+            LastLogActorName = actorName;
+            LastLogChangeType = changeType;
+            LastLogOldValue = oldValue;
+            LastLogNewValue = newValue;
+            return Task.CompletedTask;
+        }
+
+        public Task<List<SessionAuditLogEntry>> GetSessionHistoryAsync(Guid sessionId) =>
+            Task.FromResult(LogEntries.Where(e => e.SessionId == sessionId).OrderByDescending(e => e.ChangedAt).ToList());
+
        private bool IsManager(Guid groupId, long telegramId) =>
            IsOwner(groupId, telegramId) ||
            managers.Any(manager => manager.GroupId == groupId && manager.TelegramId == telegramId);