Teacher AI Preview Question Bank Draft Runtime Proof

Date: 2026-07-12

Scope

This proof covers the narrow reviewed-generation path only:

teacher-web -> Gateway exact route -> question-bank-service -> canonical DRAFT

ai-classifier-service remains the preview owner. Question Bank is the only service that creates the canonical question. The default Gateway route table is unchanged.

Static And Hermetic Gates

GOTOOLCHAIN=go1.25.11 go test ./services/question-bank-service/... -count=1
GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/internal/gateway \
  -run TestGatewayTeacherAIPreviewRoutesForwardOnlyAuthenticatedTeacherScope -count=1
pnpm --filter @hoctapaz/ui typecheck
pnpm --filter @hoctapaz/ui test -- --run packages/ui/src/modules/teacher/teacher-workspace.test.tsx
make test-teacher-ai-preview-routes

All gates passed on 2026-07-12.

Local Runtime Evidence

1. Rebuilt and started question-bank-service with docker compose -f deploy/docker-compose.yml up -d --build question-bank-service.
2. Confirmed GET http://127.0.0.1:8089/readyz returned 200.
3. Posted a reviewed candidate to POST /v1/questions/ai-preview-drafts under isolated organization org_ai_preview_runtime_20260712.
4. The first response returned 201 with a canonical question ID, status=DRAFT, sourceType=AI_GENERATED, source=AI preview, two ordered options, and provenance for previewId, provider, model, generation mode, and the teacher-edit marker.
5. An identical retry returned 200 with that same canonical ID. Reusing the same previewId with changed reviewed content returned 400 and did not create another question.
6. A scoped GET /v1/questions/{id} returned the stored explanation and the correct option marker. The fixture was deleted through the owner API; a final scoped read returned 404. Reposting the original payload returned 201 and a new question ID, proving hard-delete cleanup of the service-owned idempotency record.

Boundary

• The teacher UI sends only a reviewed Gateway preview to the exact opt-in route. Local browser drafts cannot invoke a Question Bank write.
• Question Bank forces DRAFT; teachers must review/edit before publication.
• The Gateway forwards authenticated organization, user, and role headers and removes forged actor headers. The route regression test verifies this.
• The default broad /api/questions route remains legacy_proxy.

Not Proven

This is not proof of usage/quota/credit settlement, a billed live provider call, or applying an AI solution to an existing canonical question. Those need separate owner-service contracts.