feat(api): Phase 02a Packet 4 — API conventions

.githooks/pre-commit

@@ -116,6 +116,15 @@ restage() { git add -- "$@"; }
 # once and degrade to a message rather than blocking; CI is the real gate.
 leakwatch_takes_files() {
     local probe
+
+    # An empty staged set — `git commit --amend` with nothing new, for one —
+    # expands to an unbound variable under `set -u`, and the resulting error
+    # made the caller take the "this build only scans directories" branch and
+    # skip the secret scan over a capability problem that does not exist.
+    # Nothing staged means nothing to scan, so the answer is moot: say yes and
+    # let the (equally empty) scan loop below no-op.
+    (( ${#all_staged[@]} == 0 )) && return 0
+
     for probe in "${all_staged[@]}"; do
         [[ -f "$probe" ]] || continue
         if leakwatch scan fs "$probe" --config .leakwatch.yaml \

.github/CONTRIBUTING.md

@@ -103,9 +103,10 @@ The pre-commit hook (activated by `make install`) runs, on staged files only:
 `frontend/`**; `next lint --fix` on JS / TS under `frontend/apps/web` — the one
 workspace with a `lint` script, so this is exactly what `pnpm -r lint` covers in
 CI; and, when the binary is on PATH, `leakwatch scan fs <staged-file>`. So the
-lint / typecheck / test / secret-scan pass above is mostly a sanity check. CI
-re-runs every check as a hard gate, so a bypassed local commit will fail the PR
-build.
+three commands above are mostly a sanity check. There is deliberately no
+`make secret-scan` to pair with them — the hook and CI are the scanner's only
+runners, and CI re-runs every check as a hard gate, so a bypassed local commit
+will fail the PR build.
 
 Prettier stops at the `frontend/` boundary, and the root `.prettierignore`
 is what enforces it in your editor — `.vscode/settings.json` maps `[markdown]`

.github/workflows/ci.yml

@@ -6,7 +6,9 @@
 # the GitHub Settings → Branches page matches the corpus.
 #
 # What lights up in Phase 01:
-#   - backend  : `dotnet build` + unit + architecture + contract tests
+#   - backend  : `dotnet build` + unit + architecture + contract tests, and
+#                from Phase 02a Packet 4 the WebApplicationFactory HTTP tests
+#                in LearnStack.Tests.Integration, which need no Docker
 #   - frontend : pnpm install + typecheck + lint + build + Vitest
 #   - meta     : `make lint`-style format verification
 #
@@ -16,8 +18,11 @@
 # ([if-cond] constant expression). Activation is never *only* the variable —
 # see .github/CONTRIBUTING.md § Branch protection for the three edits:
 #   - backend-integration : Testcontainers needs a real Docker socket inside
-#     the runner — works on `ubuntu-latest` natively. Activates when the
-#     first integration test lands (Phase 02a) so we have something to run.
+#     the runner — works on `ubuntu-latest` natively. Activates in Phase 02a
+#     Packet 7, with the first cross-tenant isolation test. The HTTP tests
+#     already in LearnStack.Tests.Integration do NOT wait for it: they use
+#     WebApplicationFactory, need no Docker, and run in the `backend` job
+#     today. Packet 7 splits the Docker-bound tests out into this job.
 #   - openapi-diff        : oasdiff against the prior `main` spec. Activates
 #     in Phase 02d, which ships the first real `/api/v1/*` read endpoints and
 #     retires `/healthz` as the only documented surface.
@@ -91,12 +96,18 @@ jobs:
           CI: "true"
         run: dotnet build LearnStack.slnx --no-restore --configuration Release
 
-      - name: Test (unit + architecture + contract; integration excluded)
+      # No --filter. LearnStack.Tests.Integration holds WebApplicationFactory
+      # tests that need no Docker, and they carry rules the structural tests
+      # cannot: no-op'ing VersionedRouteConvention leaves every architecture
+      # test green and turns most of this assembly red. Excluding it meant a
+      # broken route convention shipped green. Testcontainers
+      # tests arrive in Packet 7 and move to the backend-integration job then;
+      # this job's NAME is a required check and does not change.
+      - name: Test (unit + architecture + contract + HTTP integration)
         working-directory: backend
         run: |
           dotnet test LearnStack.slnx \
             --no-restore --no-build --configuration Release \
-            --filter "FullyQualifiedName!~LearnStack.Tests.Integration" \
             --logger "trx;LogFileName=test-results.trx" \
             --results-directory ../artifacts/backend-tests
 

.prettierignore

@@ -18,3 +18,19 @@
 
 /*
 !/frontend/
+
+# Generated from the backend's OpenAPI document. Reformatting the generator's
+# output makes every `pnpm generate` dirty the tree, which is what would stop
+# `generate && git diff --exit-code` being a usable freshness gate.
+#
+# Listed here AND in frontend/.prettierignore on purpose, because prettier reads
+# the ignore file relative to its working directory and the three callers do not
+# share one: the editor extension runs from the repository root, and the
+# pre-commit hook and `make format` both run from `frontend/`.
+/frontend/packages/sdk/src/generated/
+
+# Same argument, and the asymmetry is worth closing: a lockfile is generated and
+# prettier is not its author. `frontend/.prettierignore` covers the two callers
+# that run from `frontend/`; this file covers the editor, which runs from here.
+# Measured — without it, an explicit Format Document rewrites 3761 lines of it.
+/frontend/pnpm-lock.yaml

CLAUDE.md

@@ -36,7 +36,7 @@ repository holds only LearnStack's side of the boundary, in
 
 **Phase 01 complete.
 [Phase 02a](docs/roadmap/phase-02a-kernel-tenancy.md) in progress —
-packets 0–3 and 3b shipped; packets 4–10 were re-scoped on 2026-08-08 after
+packets 0–3, 3b and 4 shipped; packets 4–10 were re-scoped on 2026-08-08 after
 a four-report audit of the corpus.**
 
 **Phase 01** shipped the .NET 10 solution scaffold under `backend/`
@@ -69,6 +69,25 @@ overlay boots, and compose ports bind loopback. Its record is
 [Delivery Record (Packet 3b)](docs/roadmap/phase-02a-kernel-tenancy.md#delivery-record-packet-3b),
 kept separate from the frozen packets 0–3 record.
 
+**Packet 4** shipped the API conventions: `/api/v{N}` routing with startup
+guards for the escapes a route rule cannot see, one RFC 7807 shape on every
+error including the three the framework used to produce without one, cursor
+pagination and the sort grammar, the
+[ADR-0036](docs/decisions/0036-tenant-resolution-trusted-inputs.md) tenancy
+edge (host normalization, the trusted hop, headers as assertions, the anonymous
+rate limiter, a required `Deployment:Mode`), idempotency keys and ETag
+concurrency under
+[ADR-0037](docs/decisions/0037-idempotency-key-contract.md), a request-body
+limit that a test can actually assert, the first working SDK generation, and
+the OpenAPI mapping for strongly-typed identifiers that ADR-0023 had assigned
+to it. Its record —
+[Delivery Record (Packet 4)](docs/roadmap/phase-02a-kernel-tenancy.md#delivery-record-packet-4)
+— lists the six defects the packet introduced and caught in its own review
+rounds alongside what it built, because most of them answered a **success** the
+client had no way to question — and the two that did not were worse: one handed
+back a truncated body under a `200`, the other a `500` per request that an
+anonymous caller could trigger at will.
+
 **The 2026-08-08 restructure** re-scoped packets 3b–10 along three lines,
 all recorded in the Phase 02a Status block:
 

Makefile

@@ -95,18 +95,27 @@ build-backend: ## `dotnet build` the solution.
 build-frontend: ## `pnpm -r build` the frontend monorepo.
 	(cd frontend && pnpm -r build)
 
+.PHONY: sdk
+sdk: ## Regenerate @learnstack/sdk types from a running API's OpenAPI document.
+	@# Needs the API up. `make dev` starts the compose stack, NOT the API — run
+	@# `dotnet run --project backend/src/LearnStack.Api` in another shell first.
+	@# Override the source with LEARNSTACK_OPENAPI=<url-or-path>.
+	(cd frontend && pnpm --filter @learnstack/sdk generate)
+
 # ─── Tests ────────────────────────────────────────────────────────────────
 .PHONY: test
 test: test-backend test-frontend ## Run all test suites (backend + frontend).
 
 .PHONY: test-backend
-test-backend: ## `dotnet test` (unit + architecture + contract; integration skipped — see test-integration).
-	(cd backend && dotnet test LearnStack.slnx \
-	  --filter "FullyQualifiedName!~LearnStack.Tests.Integration" \
-	  --nologo)
+test-backend: ## `dotnet test` (unit + architecture + contract + HTTP integration — same set as CI).
+	(cd backend && dotnet test LearnStack.slnx --nologo)
 
 .PHONY: test-integration
-test-integration: ## Testcontainers-backed integration tests (requires Docker).
+test-integration: ## Just the LearnStack.Tests.Integration assembly (a subset of test-backend).
+	@# Today this assembly holds only WebApplicationFactory HTTP tests and needs
+	@# no Docker, so `make test-backend` already covers it. The target stays as
+	@# the fast inner loop while working on that assembly, and becomes the
+	@# Docker-bound entry point in Packet 7 when Testcontainers tests land.
 	(cd backend && dotnet test tests/LearnStack.Tests.Integration/LearnStack.Tests.Integration.csproj --nologo)
 
 .PHONY: test-frontend
@@ -128,7 +137,11 @@ lint-frontend: ## `pnpm -r lint` (Next/ESLint).
 .PHONY: format
 format: ## Apply formatters in place (backend dotnet-format + frontend prettier).
 	(cd backend && dotnet format LearnStack.slnx --no-restore)
-	(cd frontend && pnpm -r exec prettier --write .)
+	@# One invocation from `frontend/`, not `pnpm -r exec`: that runs prettier once
+	@# per package with the PACKAGE as its working directory, where
+	@# frontend/.prettierignore is not found — measured, it reformatted the
+	@# generated SDK schema every run.
+	(cd frontend && pnpm exec prettier --write .)
 
 # ─── Typecheck (frontend) ─────────────────────────────────────────────────
 .PHONY: typecheck
@@ -149,7 +162,7 @@ install: .env hooks ## Restore backend NuGet + frontend pnpm deps + activate git
 .PHONY: hooks
 hooks: ## Activate the repo's pre-commit hook (.githooks/pre-commit).
 	@git config core.hooksPath .githooks
-	@printf "$(CYAN)git hooks → .githooks/ (pre-commit: dotnet format on *.cs, prettier + next lint under frontend/, leakwatch if available)$(RESET)\n"
+	@printf "$(CYAN)git hooks → .githooks/ (pre-commit: dotnet format *.cs | prettier frontend/ | next lint frontend/apps/web | leakwatch if present)$(RESET)\n"
 
 # ─── Env scaffolding ──────────────────────────────────────────────────────
 # `.env` is gitignored; this rule copies `.env.example` on first run so the

backend/Directory.Packages.props

@@ -102,6 +102,17 @@
   <!--
     Reserved for later Phase 02a packets (EF migrations + design-time).
   -->
+  <!--
+    Phase 02a Packet 4 — API conventions (ADR-0024, ADR-0036).
+    Scalar renders the OpenAPI document Microsoft.AspNetCore.OpenApi emits.
+    Swashbuckle is NOT used: it does not ship a .NET 10 document generator,
+    and ADR-0024 § Implementation Notes fixes Microsoft.AspNetCore.OpenApi as
+    the generator. Standards 04 § OpenAPI was corrected to match.
+  -->
+  <ItemGroup Label="Phase 02a Packet 4 (in use)">
+    <PackageVersion Include="Scalar.AspNetCore" Version="2.16.20" />
+  </ItemGroup>
+
   <ItemGroup Label="Reserved for later Phase 02a packets">
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.0" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.0" />

backend/src/LearnStack.Api/Common/ApiControllerBase.cs

@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace LearnStack.Api.Common;
+
+/// <summary>
+/// Base type for every tenant-facing controller. Carries the two attributes
+/// that would otherwise be repeated — and occasionally forgotten — on each
+/// one: <see cref="ApiControllerAttribute"/> and the
+/// <c>[controller]</c> route token that
+/// <see cref="Versioning.VersionedRouteConvention"/> prefixes with
+/// <c>api/v{N}</c>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The sanctioned action shape is the one
+/// <see href="../../../../docs/decisions/0032-exception-handling-logging-and-observability.md">ADR-0032
+/// § Sub-decision 6</see> fixes — explicit at every endpoint, no action filter
+/// and no MediatR unwrap behavior:
+/// </para>
+/// <code>
+/// [HttpPost]
+/// public async Task&lt;IActionResult&gt; Create(CreateCourseCommand cmd, CancellationToken ct)
+///     =&gt; (await _mediator.Send(cmd, ct)).ToActionResult();
+/// </code>
+/// <para>
+/// <b>Derive from this type.</b> An earlier version of this comment said the
+/// base class was "a convenience, not the enforcement point" and that a
+/// controller deriving from <see cref="ControllerBase"/> directly was still
+/// routed correctly. Both halves were wrong, and the second was actively
+/// harmful: such a controller has no controller-level route template, so MVC
+/// routes every action on it at the bare <c>api/v{N}</c> with the resource
+/// segment dropped, and two of them collide as a 500
+/// <c>AmbiguousMatchException</c> at request time. It also lacks
+/// <see cref="ApiControllerAttribute"/>, so a malformed body bypasses the
+/// automatic 400 and surfaces as a 500 rather than the single Problem Details
+/// shape Standards 09 § API Surface fixes.
+/// </para>
+/// <para>
+/// <see cref="Versioning.VersionedRouteConvention"/> now refuses to start
+/// against a controller missing either, so the requirement is a startup
+/// failure rather than a convention nobody is obliged to follow. Declaring
+/// <c>[ApiController]</c> and a <c>[Route]</c> by hand satisfies it too; this
+/// type is simply the one place that already does.
+/// </para>
+/// </remarks>
+[ApiController]
+[Route("[controller]")]
+public abstract class ApiControllerBase : ControllerBase;

backend/src/LearnStack.Api/Common/ClientErrorProblemDetails.cs

@@ -0,0 +1,121 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Infrastructure;
+
+namespace LearnStack.Api.Common;
+
+/// <summary>
+/// Gives a LearnStack Problem Details body to the client errors nothing else
+/// covers — the ones the framework produces with no body at all.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Standards 04 § Error Responses admits exactly one error shape and
+/// Standards 09 § API Surface fixes its fields. Three statuses arrived outside
+/// it, from two different places:
+/// </para>
+/// <list type="bullet">
+/// <item>
+/// <b>404 and 405</b> come from <b>routing</b>, before MVC. No action runs, so
+/// no MVC hook fires — <see cref="MapLearnStackClientErrors"/>, built on
+/// <c>UseStatusCodePages</c>, is what sees them.
+/// </item>
+/// <item>
+/// <b>415</b> and any bodyless <see cref="StatusCodeResult"/> come from
+/// <b>MVC</b>. <see cref="ApiControllerAttribute"/> already converts those into
+/// ASP.NET's own <see cref="ProblemDetails"/> — the right idea, the wrong
+/// shape, with no <c>code</c>, no <c>messageKey</c> and no
+/// <c>correlationId</c>. <see cref="LearnStackClientErrorFactory"/> replaces
+/// that conversion rather than layering over it.
+/// </item>
+/// </list>
+/// <para>
+/// Both funnel through <see cref="ProblemDetailsFactory.ForStatus"/>, so a
+/// 404 from routing and a 404 from a controller are indistinguishable on the
+/// wire — which is the point of having one shape.
+/// </para>
+/// </remarks>
+public static class ClientErrorProblemDetails
+{
+    /// <summary>
+    /// Writes a Problem Details body for any 4xx/5xx response that reached the
+    /// client with none.
+    /// </summary>
+    /// <remarks>
+    /// Registered right after <c>UseExceptionHandler</c>. "Before routing" is
+    /// not something a caller can arrange in minimal hosting — the implicit
+    /// <c>UseRouting</c> is inserted ahead of user middleware — so what
+    /// actually matters is the order relative to the exception handler, and
+    /// that a routing 404 unwinds back through this middleware on the way out.
+    /// </remarks>
+    public static WebApplication MapLearnStackClientErrors(this WebApplication app)
+    {
+        ArgumentNullException.ThrowIfNull(app);
+
+        app.UseStatusCodePages(async context =>
+        {
+            var http = context.HttpContext;
+
+            // UseStatusCodePages only invokes this for an empty body, but the
+            // guard is cheap and the alternative — a second body appended to a
+            // partial response — is a malformed payload rather than an error.
+            if (http.Response.HasStarted)
+            {
+                return;
+            }
+
+            // An exception that reached the L1 handler has already produced a
+            // body and a status; re-writing it here would replace a specific
+            // error with a generic one derived from the status alone.
+            if (http.Features.Get<IExceptionHandlerFeature>() is not null)
+            {
+                return;
+            }
+
+            var problem = ProblemDetailsFactory.ForStatus(http.Response.StatusCode, http);
+
+            // The content type goes through WriteAsJsonAsync, not through a
+            // prior assignment to Response.ContentType: the method sets its own
+            // ("application/json") and silently overwrites anything already
+            // there, which is how these two answered with the right body under
+            // the wrong media type.
+            await http.Response.WriteAsJsonAsync(
+                problem,
+                options: null,
+                contentType: ProblemDetailsMediaType.Value,
+                cancellationToken: http.RequestAborted);
+        });
+
+        return app;
+    }
+}
+
+/// <summary>
+/// Replaces MVC's client-error conversion so a bodyless
+/// <see cref="StatusCodeResult"/> from an <see cref="ApiControllerAttribute"/>
+/// action carries the LearnStack shape rather than ASP.NET's.
+/// </summary>
+internal sealed class LearnStackClientErrorFactory : IClientErrorFactory
+{
+    public IActionResult GetClientError(ActionContext actionContext, IClientErrorActionResult clientError)
+    {
+        ArgumentNullException.ThrowIfNull(actionContext);
+        ArgumentNullException.ThrowIfNull(clientError);
+
+        var status = clientError.StatusCode ?? StatusCodes.Status500InternalServerError;
+
+        // actionContext.HttpContext, not an injected IHttpContextAccessor: MVC
+        // hands the context in, and registering the accessor app-wide to reach
+        // something already in the parameter list costs an AsyncLocal write on
+        // every request for nothing.
+        var problem = ProblemDetailsFactory.ForStatus(status, actionContext.HttpContext);
+
+        return new ObjectResult(problem)
+        {
+            StatusCode = status,
+            ContentTypes = { ProblemDetailsMediaType.Value },
+        };
+    }
+}