feat(tutorial): add /tutorial/update — echo step + persist to viewer

POST /tutorial/update echoes tutorial_step back and saves it to
Viewer.MissionData.TutorialState. is_skip=1 is handled server-side
by honoring whatever tutorial_step value the client sends (client
already sends 100 when skipping). Adds TutorialUpdateRequest DTO,
TutorialUpdateResponse DTO, injects SVSimDbContext into
TutorialController, and adds GetViewerTutorialStateAsync helper to
SVSimTestFactory.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SVSim.EmulatedEntrypoint/Controllers/TutorialController.cs

@@ -1,5 +1,8 @@
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+using SVSim.Database;
 using SVSim.EmulatedEntrypoint.Models.Dtos.Requests.Tutorial;
+using SVSim.EmulatedEntrypoint.Models.Dtos.Responses.Tutorial;
 
 namespace SVSim.EmulatedEntrypoint.Controllers;
 
@@ -9,6 +12,13 @@ namespace SVSim.EmulatedEntrypoint.Controllers;
 /// </summary>
 public class TutorialController : SVSimController
 {
+    private readonly SVSimDbContext _db;
+
+    public TutorialController(SVSimDbContext db)
+    {
+        _db = db;
+    }
+
     [HttpPost("update_action")]
     public IActionResult UpdateAction([FromBody] TutorialUpdateActionRequest request)
     {
@@ -16,4 +26,19 @@ public class TutorialController : SVSimController
         // We still emit an empty object so the translation middleware has a `data` payload to wrap.
         return new JsonResult(new { });
     }
+
+    [HttpPost("update")]
+    public async Task<ActionResult<TutorialUpdateResponse>> Update([FromBody] TutorialUpdateRequest request)
+    {
+        if (!TryGetViewerId(out long viewerId)) return Unauthorized();
+
+        var viewer = await _db.Viewers
+            .Include(v => v.MissionData)
+            .FirstAsync(v => v.Id == viewerId);
+
+        viewer.MissionData.TutorialState = request.TutorialStep;
+        await _db.SaveChangesAsync();
+
+        return new TutorialUpdateResponse { TutorialStep = request.TutorialStep };
+    }
 }

SVSim.EmulatedEntrypoint/Models/Dtos/Requests/Tutorial/TutorialUpdateRequest.cs

@@ -0,0 +1,23 @@
+using System.Text.Json.Serialization;
+using MessagePack;
+using SVSim.EmulatedEntrypoint.Models.Dtos.Requests;
+
+namespace SVSim.EmulatedEntrypoint.Models.Dtos.Requests.Tutorial;
+
+/// <summary>
+/// <c>POST /tutorial/update</c> — client reports the step it is moving TO.
+/// Client task: <c>Wizard/TutorialUpdateTask.cs</c>.
+/// </summary>
+[MessagePackObject]
+public class TutorialUpdateRequest : BaseRequest
+{
+    /// <summary>The tutorial step the client is moving TO (0, 1, 11, 21, 31, 41, 100).</summary>
+    [JsonPropertyName("tutorial_step")]
+    [Key("tutorial_step")]
+    public int TutorialStep { get; set; }
+
+    /// <summary>0 = normal, 1 = user chose Skip Tutorial.</summary>
+    [JsonPropertyName("is_skip")]
+    [Key("is_skip")]
+    public int IsSkip { get; set; }
+}

SVSim.EmulatedEntrypoint/Models/Dtos/Responses/Tutorial/TutorialUpdateResponse.cs

@@ -0,0 +1,17 @@
+using System.Text.Json.Serialization;
+using MessagePack;
+
+namespace SVSim.EmulatedEntrypoint.Models.Dtos.Responses.Tutorial;
+
+/// <summary>
+/// Server echoes the new step. Capture confirms exact value mirror — no validation,
+/// no munging. <c>tutorial_replay_step</c> is in the spec as optional but the live capture
+/// never includes it; omit unless we observe a need.
+/// </summary>
+[MessagePackObject]
+public class TutorialUpdateResponse
+{
+    [JsonPropertyName("tutorial_step")]
+    [Key("tutorial_step")]
+    public int TutorialStep { get; set; }
+}

SVSim.UnitTests/Controllers/TutorialControllerTests.cs

@@ -33,4 +33,48 @@ public class TutorialControllerTests
         Assert.That(doc.RootElement.EnumerateObject().Count(), Is.EqualTo(0),
             "update_action returns empty data — client uses SkipAllNetworkChecks and reads nothing.");
     }
+
+    [TestCase(11)]
+    [TestCase(21)]
+    [TestCase(31)]
+    public async Task Update_echoes_requested_step_and_persists(int step)
+    {
+        using var factory = new SVSimTestFactory();
+        long viewerId = await factory.SeedViewerAsync(tutorialState: 0);
+        using var client = factory.CreateAuthenticatedClient(viewerId);
+
+        var requestJson = $$"""
+        {"tutorial_step":{{step}},"is_skip":0,"viewer_id":"0","steam_id":0,"steam_session_ticket":""}
+        """;
+
+        var response = await client.PostAsync("/tutorial/update",
+            new StringContent(requestJson, Encoding.UTF8, "application/json"));
+
+        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        Assert.That(doc.RootElement.GetProperty("tutorial_step").GetInt32(), Is.EqualTo(step));
+
+        // Side effect: viewer state advanced.
+        Assert.That(await factory.GetViewerTutorialStateAsync(viewerId), Is.EqualTo(step));
+    }
+
+    [Test]
+    public async Task Update_with_is_skip_1_jumps_to_100()
+    {
+        using var factory = new SVSimTestFactory();
+        long viewerId = await factory.SeedViewerAsync(tutorialState: 0);
+        using var client = factory.CreateAuthenticatedClient(viewerId);
+
+        // The client sends the step it's MOVING TO. is_skip=1 means "skip the rest" — typically
+        // sent with tutorial_step=100 already (matches what `TutorialUpdateTask` does with the
+        // is_skip flag), so the server's job is just to honor whatever value is provided.
+        var requestJson = """{"tutorial_step":100,"is_skip":1,"viewer_id":"0","steam_id":0,"steam_session_ticket":""}""";
+
+        var response = await client.PostAsync("/tutorial/update",
+            new StringContent(requestJson, Encoding.UTF8, "application/json"));
+
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        Assert.That(doc.RootElement.GetProperty("tutorial_step").GetInt32(), Is.EqualTo(100));
+        Assert.That(await factory.GetViewerTutorialStateAsync(viewerId), Is.EqualTo(100));
+    }
 }

SVSim.UnitTests/Infrastructure/SVSimTestFactory.cs

@@ -372,6 +372,18 @@ internal sealed class SVSimTestFactory : WebApplicationFactory<Program>
         await db.SaveChangesAsync();
     }
 
+    /// <summary>
+    /// Reads the viewer's current <c>TutorialState</c> from the DB.
+    /// Tests use this to verify that <c>/tutorial/update</c> persisted the step.
+    /// </summary>
+    public async Task<int> GetViewerTutorialStateAsync(long viewerId)
+    {
+        using var scope = Services.CreateScope();
+        var db = scope.ServiceProvider.GetRequiredService<SVSimDbContext>();
+        var viewer = await db.Viewers.Include(v => v.MissionData).FirstAsync(v => v.Id == viewerId);
+        return viewer.MissionData.TutorialState;
+    }
+
     protected override void Dispose(bool disposing)
     {
         base.Dispose(disposing);