feat(education): complete P02d-4 public reads and contract checks

.github/CONTRIBUTING.md

@@ -54,29 +54,21 @@ Configure these in **GitHub → Settings → Branches → Branch protection rule
       no test — `dotnet test --filter` exits 0 when nothing matches, and a renamed
       `Requires=Docker` trait would otherwise leave the whole Docker suite unrun
       behind a green check.
-  - Deferred checks. Each is gated on a repository variable (`vars.ENABLE_*`,
-    unset by default — a constant `if: false` is rejected by actionlint).
-    Activating one is **four edits, in the same pull request wherever possible**:
-    set the variable in **Settings → Secrets and variables → Actions → Variables**,
-    replace the placeholder step with the real one, **rename the job** to drop the
-    `(deferred …)` suffix, and add the new name both to this list and to the live
-    branch-protection setting. Setting the variable alone leaves a job that runs
-    but gates nothing.
-    - `openapi diff (deferred to Phase 02d)` — **Phase 02d**, with the first real
-      `/api/v1/*` read endpoints.
-    - `lighthouse budget (deferred to Phase 02d)` — **Phase 02d**, with the first
-      content-bearing public pages.
-
-    GitHub matches required checks **by name**, so the rename is the dangerous
-    half: a renamed check that nobody re-required is a check that no longer blocks
-    anything, and the PR still shows green.
-
-    > **Open in Phase 02d.** Whether the Lighthouse job activates in Phase 02d, and on
-    > what harness, is G44; whether an activated job keeps its `vars.ENABLE_*`
-    > condition — GitHub treats a skipped required job as passing — is G31.
-    > [Phase 02d's decision register](../docs/roadmap/phase-02d-walking-skeleton.md#the-decision-register)
-    > holds both. The pass that closes each gate edits the activation steps and the
-    > Lighthouse entry above with its answer.
+    - `openapi diff` — **required since P02d-4, 2026-10-04.** The always-running
+      job uses pinned policy fixtures, verified base/head snapshots and actual
+      first-baseline proof. Its real PR run passed before activation. API read-back
+      verifies all six GitHub Actions contexts, strict up-to-date checking and
+      every other protection setting unchanged. The
+      [packet delivery record](../docs/roadmap/phase-02d-walking-skeleton.md#p02d-4-step-4-contract-sdk-and-ci)
+      records the successful job and activation proof.
+  - `lighthouse budget (deferred to Phase 02d)` remains behind its unset
+    `vars.ENABLE_LIGHTHOUSE_BUDGET` condition. P02d-6/G44 owns activation,
+    pages, harness and assertions; its rename also needs live registration.
+
+    GitHub matches required checks **by name**. The
+    [packet record](../docs/roadmap/phase-02d-walking-skeleton.md#p02d-4-step-4-contract-sdk-and-ci)
+    owns execution and dated API read-back; a workflow edit alone is not a
+    protection-setting change.
 - **Require conversation resolution before merging**: on.
 - **Require signed commits**: optional (off until the team rolls out signing keys).
 - **Require linear history**: on (we use squash-merge or rebase-merge, never bubble).

.github/workflows/ci.yml

@@ -24,24 +24,9 @@
 #     REQUIRED check is a repository setting — see .github/CONTRIBUTING.md
 #     § Branch protection.
 #
-# Still deferred to later phases. Each is scaffolded behind a repository variable
-# (`vars.ENABLE_*`), unset by default. A constant `if: false` would be simpler but
-# actionlint rejects it ([if-cond] constant expression). Activation is never *only*
-# the variable — .github/CONTRIBUTING.md § Branch protection lists every edit it
-# takes, including the rename and the live required-check registration:
-#   - 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.
-#   - lighthouse-budget   : LHCI against the built Next.js app. Activates
-#     in Phase 02d, which ships the first content-bearing public pages (the
-#     two tenant catalog / lesson pages a visitor actually loads).
-#
-# Open in Phase 02d: whether lighthouse-budget activates there, on what harness,
-# over which pages and with which assertions is G44, and whether an activated job
-# keeps its `if: vars.ENABLE_*` condition is G31, both in
-# docs/roadmap/phase-02d-walking-skeleton.md § The decision register. The pass that
-# closes each gate edits this block, the deferred jobs and
-# .github/CONTRIBUTING.md § Branch protection with its answer.
+# P02d-4 activates the always-running `openapi diff` check: pinned oasdiff,
+# ADR-0024 policy controls and verified base/head snapshots. Lighthouse remains
+# deferred under P02d-6's G44; a public-page harness has not shipped yet.
 
 name: ci
 
@@ -51,6 +36,11 @@ on:
   pull_request:
     branches: [main]
   workflow_dispatch:
+    inputs:
+      openapi_base_ref:
+        description: "Explicit verified base commit/ref for the OpenAPI comparison"
+        required: true
+        type: string
 
 # Cancel in-progress runs on the same ref so PR force-pushes don't queue.
 concurrency:
@@ -271,6 +261,14 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Regenerate SDK from the committed contract and refuse drift
+        env:
+          LEARNSTACK_OPENAPI: ../../../backend/openapi/v1.json
+        run: |
+          git ls-files --error-unmatch packages/sdk/src/generated/schema.d.ts
+          pnpm --filter @learnstack/sdk generate
+          git diff --exit-code -- packages/sdk/src/generated/schema.d.ts
+
       - name: Typecheck
         run: pnpm -r typecheck
 
@@ -283,13 +281,68 @@ jobs:
       - name: Test (Vitest)
         run: pnpm -r test
 
-  # ─── OpenAPI breaking-change check (deferred — Phase 02d) ─────────────
+  # ─── OpenAPI breaking-change check (active — P02d-4) ─────────────────
   openapi-diff:
-    name: openapi diff (deferred to Phase 02d)
+    name: openapi diff
     runs-on: ubuntu-latest
-    if: vars.ENABLE_OPENAPI_DIFF == 'true'
+    timeout-minutes: 15
     steps:
-      - run: echo "Placeholder — Phase 02d wires oasdiff against the prior main spec."
+      - name: Checkout verified history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up .NET SDK for the first-baseline proof
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: backend/global.json
+
+      - name: Install pinned, checksum-verified oasdiff
+        run: python3 scripts/install-oasdiff.py artifacts/openapi/tool
+
+      - name: Prove snapshot admission and fail-closed controls
+        run: python3 scripts/test-openapi-ci.py
+
+      - name: Prove breaking-policy controls
+        run: |
+          python3 scripts/openapi-policy.py \
+            --tool artifacts/openapi/tool/oasdiff \
+            --fixtures --output artifacts/openapi/fixtures
+
+      - name: Compare the event's verified base and head
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+          MANUAL_BASE_REF: ${{ inputs.openapi_base_ref }}
+        run: |
+          set -euo pipefail
+          case "$EVENT_NAME" in
+            pull_request) openapi_base="$PR_BASE_SHA"; openapi_head="$PR_HEAD_SHA" ;;
+            push)
+              if [[ "$PUSH_BEFORE_SHA" == "0000000000000000000000000000000000000000" ]]; then
+                openapi_base="${HEAD_SHA}^"
+              else
+                openapi_base="$PUSH_BEFORE_SHA"
+              fi
+              openapi_head="$HEAD_SHA"
+              ;;
+            workflow_dispatch) openapi_base="$MANUAL_BASE_REF"; openapi_head="$HEAD_SHA" ;;
+            *) echo "Unsupported OpenAPI event" >&2; exit 1 ;;
+          esac
+          python3 scripts/openapi-ci.py --base "$openapi_base" --head "$openapi_head" \
+            --tool artifacts/openapi/tool/oasdiff --output artifacts/openapi/diff
+
+      - name: Upload specs, SHAs, policy, tool version and comparison reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-comparison
+          path: artifacts/openapi
+          if-no-files-found: error
 
   # ─── Lighthouse budget (deferred — Phase 02d) ─────────────────────────
   lighthouse-budget:

CLAUDE.md

@@ -88,9 +88,24 @@ is Accepted — 2026-10-02. Step 1 implements typed settings and locale resoluti
 both review rounds passed. Step 2 implements batched definition reads; both review
 rounds passed. Step 3
 adds generation caching and scope-safe bypass; both review rounds passed.
-P02d-3 is complete and ready for PR review; it remains unmerged.
-Public reads
-stay with P02d-4.
+**P02d-3 is complete and merged** through
+[PR #24](https://github.com/HodeTech/LearnStack/pull/24) on 2026-10-03; its
+[merge closeout](docs/roadmap/phase-02d-walking-skeleton.md#p02d-3-merge-and-closeout-2026-10-03)
+records final verification. Public reads stay with P02d-4.
+Its [decision package](docs/roadmap/phase-02d-walking-skeleton.md#p02d-4-decision-package-2026-10-03)
+and ADR-0052 are Accepted — 2026-10-03. The approved four-step implementation and
+two-round review loop run on development; delivery evidence is recorded per step.
+Step 1 implements immutable host provenance and physical read-only transactions;
+both review rounds and the focused fix review pass. Step 2 implements live site
+configuration and GET/HEAD with no-store; both review rounds and focused fix
+verification pass. Step 3 implements Education GET/HEAD reads, exact-locale
+marketing/content projections and scoped seek cursors; both independent review
+rounds pass. Step 4 implements served/snapshot contract controls, the injected typed
+SDK and always-running OpenAPI compatibility CI. Both independent review rounds
+and fresh fix verification pass. All six real CI jobs pass; the approved sixth
+required check is active with all other live settings preserved. P02d-4 is
+implementation-complete in [PR #25](https://github.com/HodeTech/LearnStack/pull/25),
+awaiting maintainer review and merge. P02d-5 is next; its decision pass is not started.
 
 **Phase 01** shipped the .NET 10 solution scaffold under `backend/`
 (core + 7 modules × 4 projects + 4 test projects including the

Makefile

@@ -223,10 +223,9 @@ migrate: ## Apply every EF migration chain (platform + each module) as `learnsta
 	exit "$$failed"
 
 .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>.
+sdk: ## Regenerate @learnstack/sdk types from the committed v1 snapshot.
+	@# No running API is needed. Contract tests verify this snapshot against Program.
+	@# LEARNSTACK_OPENAPI=<url-or-path> is a diagnostic override; CI uses the snapshot.
 	(cd frontend && pnpm --filter @learnstack/sdk generate)
 
 # ─── Tests ────────────────────────────────────────────────────────────────

README.md

@@ -81,18 +81,30 @@ records verification. P02d-3 read internals are implemented; the
 is Accepted — 2026-10-02, with Step 1 implemented and both review rounds passed.
 Step 2 implements batched definition reads; both review rounds passed. Step 3 adds
 generation caching and scope-safe bypass; both review rounds passed.
-P02d-3 is complete and ready for PR review; it remains unmerged.
-**P02d-4** owns anonymous public API reads. Browser rendering follows
-in P02d-5–7; none of these later packets has started.
+**P02d-3 is complete and merged** through
+[PR #24](https://github.com/HodeTech/LearnStack/pull/24) on 2026-10-03; its
+[merge closeout](docs/roadmap/phase-02d-walking-skeleton.md#p02d-3-merge-and-closeout-2026-10-03)
+records final verification.
+**P02d-4 is implementation-complete** in
+[PR #25](https://github.com/HodeTech/LearnStack/pull/25), awaiting review and merge.
+Its four steps deliver the read-only host boundary, anonymous site/Education
+GET/HEAD reads and OpenAPI/SDK/CI controls. Every step completed both review
+rounds; final fix verification and all six real required CI jobs pass. The sixth
+required OpenAPI check is active, with all other live protection settings preserved.
+Browser rendering follows
+in P02d-5–7. The
+[P02d-4 decision package](docs/roadmap/phase-02d-walking-skeleton.md#p02d-4-decision-package-2026-10-03)
+is Accepted — 2026-10-03. All four implementation steps and their review loops
+are complete; server rendering and browser delivery remain P02d-5/6.
 
 | Area | Delivered now | Next milestone |
 |---|---|---|
 | **Tenancy** | Tenant provisioning, organizations, locales, typed settings/branding reads, host resolution and database isolation | User membership and permissions in [Phase 03](docs/roadmap/phase-03-identity-admin.md) |
 | **Customization** | Content types, level taxonomies, exact-definition and generation-cached batched display readers, text-card metadata validation and tenant-authored seeds | Remaining authoring capabilities across [Phases 04–08a](docs/roadmap/README.md) |
 | **Audit** | Classified write path and transactional durability for business changes | Operational hardening in [Phase 11](docs/roadmap/phase-11-production-hardening.md) |
-| **Education** | Course and Lesson aggregates, translations, protected-content policy, scoped authoring commands, complete demo seeds and isolation tests | Public reading in [P02d-4](docs/roadmap/phase-02d-walking-skeleton.md) |
+| **Education** | Course and Lesson aggregates, translations, protected-content policy, scoped authoring commands, complete demo seeds and isolated public GET/HEAD reads | Trusted server consumer in [P02d-5](docs/roadmap/phase-02d-walking-skeleton.md) |
 | **API foundation** | Error contracts, validation, tenancy, concurrency and observability infrastructure | Authentication and durable event processing in [Phase 02b](docs/roadmap/phase-02b-events-auth.md) |
-| **Frontend** | Next.js app and public / studio / portal route scaffolds | First two-tenant browser demo in [P02d-5–7](docs/roadmap/phase-02d-walking-skeleton.md) |
+| **Frontend** | Next.js route scaffolds and generated typed SDK with injected transport | First two-tenant browser demo in [P02d-5–7](docs/roadmap/phase-02d-walking-skeleton.md) |
 
 **Four modules contain domain implementations:** Tenancy, Customization, Audit and
 Education. Identity, Content and Media remain scaffolded.
@@ -190,7 +202,7 @@ three product surfaces. See the
 |---|---|---|
 | Backend | .NET 10 · ASP.NET Core · EF Core · MediatR | Foundation and four domain modules implemented |
 | Database | PostgreSQL 18 | Migrations, tenant / organization RLS and integration proofs |
-| Frontend | Next.js 15 · React 19 · TypeScript | App and shared packages scaffolded |
+| Frontend | Next.js 15 · React 19 · TypeScript | App/UI scaffolds; generated SDK and injected transport implemented |
 | Observability | OpenTelemetry · Serilog → OTLP | Cross-cutting backend instrumentation implemented |
 | Identity | Keycloak | Local realms configured; application authentication belongs to Phase 02b |
 | Storage and search | SeaweedFS · PostgreSQL full-text search | Selected architecture; feature delivery belongs to Phases 04–05 |

backend/openapi/policy/README.md

@@ -0,0 +1,52 @@
+# OpenAPI compatibility controls
+
+[ADR-0024](../../../docs/decisions/0024-api-versioning-policy.md) owns the policy.
+[P02d-4 G31](../../../docs/roadmap/phase-02d-walking-skeleton.md#openapi-sdk-and-required-check-plan)
+owns pins, severity overrides, artifact contents and required-check rollout.
+
+`fixtures/base.json` and `fixtures/cases.json` cover each representable policy row
+with breaking mutations and nonbreaking controls. The runner checks a literal
+non-empty census against the real pinned executable. It retains raw tool reports,
+normalized reports and companion findings; no external references are allowed.
+
+The pinned tool misses some root enum additions, open-to-closed enum changes and
+numeric field type changes. It also rejects additions to an explicitly open
+response enum. The companion walks reachable request/response schemas, including
+local schema and Response/RequestBody/Parameter references. It refuses type changes,
+closed enum additions and open enum closure/removal, and removes only matching
+open enum lists for the tool. Fields, validators and other constraints remain.
+Analysis finishes against immutable occurrences before normalizing separate copies;
+an open reference never erases a closed consumer of the same component. Effective
+parameters honor path inheritance and operation overrides; the CLI also flattens
+parameters. Parameter/header schema and content forms are mirrored into temporary
+request/response bodies the tool checks, preserving original metadata and recording
+source locations. These policy-only paths exist in comparison artifacts, never in
+the published snapshot or runtime routes. Controls cover field/validator changes,
+equivalent relocation and both shared-reference key orders. Strengthening an output
+guarantee is not an input-validator tightening and remains compatible.
+Recursive edges stay in private schema copies identified by stable declaration
+locations, so open enum additions and documentation edits remain compatible without
+erasing closed consumers. Cycle and mixed open/closed controls cover this boundary,
+including inline schemas and schemas declared inside Response components.
+A combined open addition and field removal proves that normalization cannot hide
+another breaking change. Current public enums are closed. A future open-set enum
+still requires compatible generation and consumer proof before shipping.
+
+Schema limits cannot describe every runtime rule or what a status means.
+`PublicReadProtocolTests` and `PublicEducationHttpTests` prove locale, slug and
+cursor grammar/multiplicity, unsupported locales and hidden-resource outcomes;
+`PublicSiteHttpTests` proves site configuration/lifecycle status mapping. These
+runtime cases complement documented validator/status mutations in the fixtures.
+
+From the repository root, with the verified pinned executable:
+
+```sh
+python3 scripts/test-openapi-ci.py
+python3 scripts/openapi-policy.py --tool /path/to/oasdiff --fixtures --output /tmp/openapi-controls
+python3 scripts/openapi-ci.py --base BASE_REF --head HEAD_REF --tool /path/to/oasdiff --output /tmp/openapi-diff
+```
+
+The installer is Linux AMD64 only and verifies the approved archive before
+extracting/executing it. A workstation can pass a separately checksum-verified
+executable of the same pinned version. The first baseline is proved by building
+and serving the verified base Program; a missing file alone is insufficient.