feat(ai): capstone AI-off via the credential-gate constant (#867)

The capstone credential attests that the learner shipped the program
themselves, so it certifies nothing if a tutor could have written it. Until
now the AI path had only structural absence (the capstone happens to carry no
code block) plus quiz-level aiSuppressed — no code read a capstone constant,
so a content edit could silently re-enable AI on the very lesson the
credential rests on.

Enforcement now keys off the SAME constant as the credential gate:

- lib/credentials/capstone-identity.ts — the one definition site, deliberately
  not server-only so the client can read it. capstone-gate re-exports it, so
  every existing importer is unchanged.
- /api/ai/partner refuses the capstone with 403 + `capstone_ai_off`, before any
  spend (no assist turn, no ledger write, no Gemini call) and before the
  codeBlock 404 so the refusal is typed rather than incidental.
- /api/lessons/reflect suppresses the AI reply on the capstone; the seal is
  still returned unconditionally (receipt-first untouched).
- The pane renders the AI-free explanation in place of its actions, threaded
  from the same constant; copy in en / pt-BR / es.

Author: thomgabriel

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/blocks/__tests__/open-ended-block.test.tsx

@@ -36,6 +36,7 @@ function makeCtx(overrides: Partial<BlockContext> = {}): BlockContext {
     setProof: vi.fn(),
     setQuizAnswered: vi.fn(),
     aiSuppressed: true,
+    capstoneAiOff: false,
     buildUuid: null,
     programKeypairSecret: null,
     resetBuild: vi.fn(),

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/blocks/__tests__/parsons-block.test.tsx

@@ -43,6 +43,7 @@ function makeCtx(overrides: Partial<BlockContext> = {}): BlockContext {
     setProof: vi.fn(),
     setQuizAnswered: vi.fn(),
     aiSuppressed: true,
+    capstoneAiOff: false,
     buildUuid: null,
     programKeypairSecret: null,
     resetBuild: vi.fn(),

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/blocks/__tests__/quiz-block.test.tsx

@@ -72,6 +72,7 @@ function makeCtx(overrides: Partial<BlockContext> = {}): BlockContext {
     setProof: vi.fn(),
     setQuizAnswered: vi.fn(),
     aiSuppressed: true,
+    capstoneAiOff: false,
     buildUuid: null,
     programKeypairSecret: null,
     resetBuild: vi.fn(),

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/blocks/code-block.tsx

@@ -56,6 +56,7 @@ export function CodeBlock({ block, ctx }: BlockRenderProps) {
           isEnrolled={ctx.isEnrolled}
           onEnroll={ctx.onEnroll}
           aiSuppressed={ctx.aiSuppressed}
+          capstoneAiOff={ctx.capstoneAiOff}
           className="h-full"
         />
       </div>

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/blocks/types.ts

@@ -30,6 +30,15 @@ export interface BlockContext {
    * block threads it to ChallengeInterface, which keeps the AI Partner hidden.
    */
   aiSuppressed: boolean;
+  /**
+   * True on THE graded capstone lesson (#867) — derived from
+   * `lib/credentials/capstone-identity`, the same constant the credential gate
+   * uses. Unlike `aiSuppressed` this is permanent and explained: the code block
+   * threads it to ChallengeInterface, which renders the AI-free rationale where
+   * the AI Partner would sit. The server refuses independently
+   * (`/api/ai/partner`) — this is presentation, not the enforcement.
+   */
+  capstoneAiOff: boolean;
   /** Latest successful build (for deployable code + the deployed-program card). */
   buildUuid: string | null;
   programKeypairSecret: number[] | null;

apps/web/src/app/[locale]/(platform)/courses/[slug]/lessons/[id]/lesson-client.tsx

@@ -18,6 +18,7 @@ import { AuthModal } from "@/components/auth/auth-modal";
 import { trackEvent } from "@/lib/analytics";
 import { completionErrorKey } from "@/lib/lessons/completion-error";
 import { createClient } from "@/lib/supabase/client";
+import { isCapstoneLesson } from "@/lib/credentials/capstone-identity";
 import { useAuth } from "@/lib/auth/auth-provider";
 import { useOnChainEnroll } from "@/hooks/use-on-chain-enroll";
 import { bankCompletion, removeBanked } from "@/lib/lessons/progress-bank";
@@ -223,6 +224,16 @@ export function LessonPageClient({
       prev[blockKey] === answered ? prev : { ...prev, [blockKey]: answered }
     );
   }, []);
+  // AI hard-off on the capstone (#867) — the CLIENT leg of the server refusal
+  // in /api/ai/partner, derived from the same `capstone-identity` constant as
+  // the credential gate (never a second hardcoded id). Distinct from
+  // `aiSuppressed`: quiz suppression is temporary (answer the quiz and the
+  // tutor returns) and simply HIDES the pane, whereas this is permanent and
+  // must be EXPLAINED — the pane renders the AI-free rationale in place of its
+  // actions, so a learner who expected a tutor learns why there isn't one
+  // rather than finding a blank column.
+  const capstoneAiOff = isCapstoneLesson(lesson._id);
+
   const aiSuppressed =
     hasQuizBlock &&
     !isCompleted &&
@@ -401,6 +412,7 @@ export function LessonPageClient({
       setProof,
       setQuizAnswered,
       aiSuppressed,
+      capstoneAiOff,
       buildUuid,
       programKeypairSecret,
       resetBuild,
@@ -418,6 +430,7 @@ export function LessonPageClient({
       setProof,
       setQuizAnswered,
       aiSuppressed,
+      capstoneAiOff,
       buildUuid,
       programKeypairSecret,
       resetBuild,

apps/web/src/app/api/ai/__tests__/partner-capstone-off.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { NextRequest } from "next/server";
+
+// AI hard-off on the capstone (#867, unified spec item 33) — the SERVER leg.
+//
+// RED-PROOF (measured): with this file's route change reverted, 3 of these 4
+// tests fail — `expected 200 to be 403` and `spendAssistTurn … called 1 times`.
+// No capstone check exists at main, so the request falls straight through and
+// is SERVED, spending a turn and hitting Gemini.
+//
+// That 200 is the point. Today's capstone happens to carry no `code` block, so
+// the route 404s there by accident — the "structural absence" this issue
+// exists to replace. The fixtures below deliberately give the capstone a code
+// block, which is precisely the content edit that would silently re-enable AI
+// on the lesson the credential rests on.
+
+vi.mock("server-only", () => ({}));
+
+const getUser = vi.fn();
+vi.mock("@/lib/supabase/server", () => ({
+  createClient: async () => ({ auth: { getUser } }),
+}));
+
+const spendAssistTurn = vi.fn();
+const refundAssistTurn = vi.fn();
+const recordBilledAssist = vi.fn();
+const appendAssistLog = vi.fn();
+vi.mock("@/lib/ai/assist-budget", () => ({
+  spendAssistTurn,
+  refundAssistTurn,
+  recordBilledAssist,
+  appendAssistLog,
+  MAX_PAID_ASSISTS: 4,
+}));
+
+const isRateLimited = vi.fn();
+const getClientIp = vi.fn(() => "203.0.113.9");
+vi.mock("@/lib/rate-limit", () => ({ isRateLimited, getClientIp }));
+
+const checkAiSpend = vi.fn();
+const recordAiSpend = vi.fn();
+vi.mock("@/lib/ai/spend-ledger", () => ({
+  checkAiSpend,
+  recordAiSpend,
+  degradedMaxTokens: (base: number) => Math.max(256, Math.floor(base / 2)),
+}));
+
+const getLessonBySlug = vi.fn();
+vi.mock("@/lib/content/queries", () => ({ getLessonBySlug }));
+
+// The REAL identity module — deliberately not mocked. These tests must break if
+// the constant moves or changes, which is half the point of the shared-constant
+// clause.
+import {
+  CAPSTONE_CREDENTIAL,
+  CAPSTONE_AI_OFF_CODE,
+} from "@/lib/credentials/capstone-identity";
+
+const CODE_BLOCK = {
+  _type: "code",
+  key: "c1",
+  language: "rust",
+  buildType: "standard",
+  starter: "fn solve() {}",
+  solution: "fn solve() { /* the answer */ }",
+  tests: [
+    { id: "v1", description: "visible test", input: "1", expectedOutput: "2" },
+  ],
+  hints: [],
+};
+
+// The capstone WITH a code block: the worst case this change defends against —
+// a future content edit that gives the capstone a challenge surface. Structural
+// absence would silently serve AI here; the constant-driven check must not.
+const CAPSTONE_LESSON = {
+  _id: CAPSTONE_CREDENTIAL.deployLessonId,
+  title: "Capstone",
+  slug: "capstone",
+  blocks: [{ _type: "prose", key: "p1", src: "Ship it." }, CODE_BLOCK],
+};
+
+const ORDINARY_LESSON = {
+  _id: "lesson-1",
+  title: "Solve it",
+  slug: "l-slug",
+  blocks: [{ _type: "prose", key: "p1", src: "Double it." }, CODE_BLOCK],
+};
+
+function makeRequest(body: unknown): NextRequest {
+  return new NextRequest("http://localhost/api/ai/partner", {
+    method: "POST",
+    body: JSON.stringify(body),
+    headers: { "content-type": "application/json" },
+  });
+}
+
+const BODY = {
+  lessonSlug: "capstone",
+  courseSlug: "c-slug",
+  action: "hint",
+  code: "let x = 1;",
+  testSummary: "1/2 passing",
+};
+
+const GEMINI_TEXT = JSON.stringify({
+  type: "hint",
+  text: "Try a smaller step.",
+});
+
+function stubGeminiFetch() {
+  const fetchMock = vi.fn(async () => {
+    return {
+      ok: true,
+      text: async () => "",
+      json: async () => ({
+        candidates: [{ content: { parts: [{ text: GEMINI_TEXT }] } }],
+        usageMetadata: {},
+      }),
+    } as unknown as Response;
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+beforeEach(() => {
+  vi.resetModules();
+  process.env.GEMINI_API_KEY = "test-gemini-key";
+  process.env.AI_PARTNER_SEAL_SECRET = "test-seal-secret";
+  getUser.mockReset();
+  spendAssistTurn.mockReset();
+  refundAssistTurn.mockReset();
+  recordBilledAssist.mockReset();
+  appendAssistLog.mockReset();
+  isRateLimited.mockReset();
+  getLessonBySlug.mockReset();
+  checkAiSpend.mockReset();
+  recordAiSpend.mockReset();
+
+  getUser.mockResolvedValue({ data: { user: { id: "user-1" } }, error: null });
+  isRateLimited.mockResolvedValue(false);
+  spendAssistTurn.mockResolvedValue({
+    allowed: true,
+    tier: "free",
+    counts: { free: 1, metered: 0, socratic: 0 },
+  });
+  refundAssistTurn.mockResolvedValue(undefined);
+  recordBilledAssist.mockResolvedValue(undefined);
+  appendAssistLog.mockResolvedValue(undefined);
+  checkAiSpend.mockResolvedValue({ decision: "full" });
+  recordAiSpend.mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  delete process.env.GEMINI_API_KEY;
+  delete process.env.AI_PARTNER_SEAL_SECRET;
+});
+
+describe("POST /api/ai/partner — capstone AI hard-off (#867)", () => {
+  it("refuses the capstone lesson with the typed capstone_ai_off code", async () => {
+    getLessonBySlug.mockResolvedValue(CAPSTONE_LESSON);
+    stubGeminiFetch();
+
+    const { POST } = await import("../partner/route");
+    const res = await POST(makeRequest(BODY));
+    const json = await res.json();
+
+    expect(res.status).toBe(403);
+    expect(json).toMatchObject({
+      code: CAPSTONE_AI_OFF_CODE,
+      capstoneAiOff: true,
+    });
+  });
+
+  it("spends nothing: no assist turn, no ledger write, no Gemini call", async () => {
+    getLessonBySlug.mockResolvedValue(CAPSTONE_LESSON);
+    const fetchMock = stubGeminiFetch();
+
+    const { POST } = await import("../partner/route");
+    await POST(makeRequest(BODY));
+
+    // The refusal is the design, not a failure — it must cost the learner
+    // nothing and must never reach the platform-funded key.
+    expect(spendAssistTurn).not.toHaveBeenCalled();
+    expect(recordBilledAssist).not.toHaveBeenCalled();
+    expect(recordAiSpend).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+    // Nothing was spent, so nothing may be refunded either (a refund would
+    // credit a turn that was never taken).
+    expect(refundAssistTurn).not.toHaveBeenCalled();
+  });
+
+  it("refuses every action, not just hint", async () => {
+    getLessonBySlug.mockResolvedValue(CAPSTONE_LESSON);
+    stubGeminiFetch();
+    const { POST } = await import("../partner/route");
+
+    for (const action of ["hint", "ask", "propose", "review"]) {
+      const res = await POST(makeRequest({ ...BODY, action }));
+      expect(res.status, `action=${action}`).toBe(403);
+    }
+  });
+
+  it("leaves a non-capstone lesson untouched", async () => {
+    getLessonBySlug.mockResolvedValue(ORDINARY_LESSON);
+    const fetchMock = stubGeminiFetch();
+
+    const { POST } = await import("../partner/route");
+    const res = await POST(
+      makeRequest({ ...BODY, lessonSlug: "l-slug", action: "hint" })
+    );
+    const json = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(json).toMatchObject({ type: "hint" });
+    expect(spendAssistTurn).toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalled();
+  });
+});

apps/web/src/app/api/ai/partner/route.ts

@@ -35,6 +35,10 @@ import type {
   ReviewResponse,
   CodeEdit,
 } from "@/lib/ai/partner-types";
+import {
+  isCapstoneLesson,
+  CAPSTONE_AI_OFF_CODE,
+} from "@/lib/credentials/capstone-identity";
 import { serverEnv } from "@/lib/env.server";
 
 const GEMINI_API_KEY = serverEnv.GEMINI_API_KEY;
@@ -340,6 +344,34 @@ export async function POST(request: NextRequest) {
   // §10.2). getLessonBySlug applies the normal catalog gate — a lesson not yet
   // live has no partner surface either.
   const lesson = await getLessonBySlug(courseSlug, lessonSlug);
+
+  // AI HARD-OFF ON THE CAPSTONE (#867, unified spec item 33). The capstone
+  // credential attests that the learner shipped the program themselves (the
+  // deploy gate, item 14) — so it certifies nothing if a tutor could have
+  // written it. This is the SERVER leg, keyed off the SAME constant as that
+  // gate (`lib/credentials/capstone-identity`), so the two can never drift:
+  // re-shaping the capstone lesson cannot silently re-open the AI path.
+  //
+  // Placement is load-bearing on two counts:
+  //   • BEFORE any spend — no assist turn, no ledger entry, no Gemini call. A
+  //     refusal here costs the learner nothing (it is not a failure, it is the
+  //     design), so it must not consume a turn.
+  //   • BEFORE the `codeBlock` 404 — the capstone hosts no `code` block today,
+  //     so a structural 404 is what happens by accident. This returns the
+  //     TYPED reason instead, which is the whole point of the issue: the
+  //     refusal must be intentional and observable, not incidental.
+  // The copy is neutral, not an error: this is a permanent, explained state.
+  if (lesson && isCapstoneLesson(lesson._id)) {
+    return NextResponse.json(
+      {
+        error: "AI Partner is off for the capstone",
+        code: CAPSTONE_AI_OFF_CODE,
+        capstoneAiOff: true,
+      },
+      { status: 403 }
+    );
+  }
+
   const codeBlock = lesson?.blocks.find(
     (b): b is CodeBlockData => b._type === "code"
   );