Handoff: SVC-007-quiz-question-integration-contract course-service quiz/question integration contract

Scope

Service/area: course-service
Task pack: docs/agents/service-tasks/course-service.md
Goal: complete the bounded SVC-007 quiz/question integration contract slice by adding a service-local contract endpoint and tests that name question-bank-service and exam-service as canonical owners while keeping course-service limited to course/progress state and future copied reference rows.
Non-goals: course lesson-question persistence, course quiz persistence, public /api/courses* route promotion, wallet/payment paid-access changes, canonical question/exam ownership, live browser proof, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

/Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/courses/courses.controller.ts
/Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/courses/courses.service.ts
/Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/courses/courses.spec.ts
/Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/courses/**
/Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
Legacy source was read-only evidence only; no course quiz/question route parity is claimed.

go-platform/services/course-service/internal/domain/course.go
go-platform/services/course-service/internal/http/server.go
go-platform/services/course-service/internal/http/server_test.go
go-platform/services/course-service/internal/usecase/course_integration_contract.go
go-platform/services/course-service/internal/usecase/course_integration_contract_test.go
go-platform/contracts/openapi/services/course-service.yaml
go-platform/services/course-service/api/openapi.yaml
go-platform/services/course-service/README.md
go-platform/docs/api/course-service.md
go-platform/docs/agents/service-tasks/course-service.md
go-platform/docs/agents/handoffs/SVC-007-quiz-question-integration-contract.md
go-platform/docs/agents/service-agent-closeout-ledger.json
go-platform/docs/agents/service-agent-closeout-ledger.md

Added GET /v1/courses/integration-contracts/question-exam as a service-local contract endpoint.
The contract names question-bank-service as canonical owner for question content, answers, solutions, taxonomy, and usage counters through GET /v1/questions/{id} and PUT /v1/questions/usage-counts.
The contract names exam-service as canonical owner for exam/quiz definition, question snapshots, publish lifecycle, assignment, and runtime access through GET /v1/exams/{id} and PUT|GET /v1/exams/{examId}/question-snapshots.
The contract states future course-owned rows may store only copied references such as courseId, lessonId, questionId, examId, order, and optional copied display/title snapshots.
The contract explicitly forbids course-service from owning wallet ledger, payment order, canonical question content, canonical exam/attempt state, or analytics mastery rollups.

Command: GOTOOLCHAIN=go1.25.11 go test ./services/course-service/internal/usecase -run TestQuestionExamIntegrationContractPreservesOwnerBoundaries -count=1 -v
Result: passed.
Evidence: usecase contract test verified schema/status, question-bank owner API, exam owner API, course-stored refs, and forbidden ownership boundaries.
Command: GOTOOLCHAIN=go1.25.11 go test ./services/course-service/internal/http -run TestQuestionExamIntegrationContractRoute -count=1 -v
Result: passed.
Evidence: HTTP route returned the contract envelope and forbidden ownership list.
Command: GOTOOLCHAIN=go1.25.11 go test ./services/course-service/... -count=1
Result: passed.
Evidence: all course-service packages passed after the contract endpoint and docs/API mirror updates.
Command: make test-student-course-routes test-student-course-progress-routes
Result: passed.
Evidence: default routes stayed legacy while non-default student course read/progress rehearsals remained exact and guarded.
Command: STUDENT_COURSE_BROWSER_SELF_TEST=1 make test-student-course-browser
Result: passed.
Evidence: browser smoke harness self-test passed; live browser proof remains separate and not claimed.
Command: ruby -e 'require "yaml"; YAML.load_file("contracts/openapi/services/course-service.yaml"); YAML.load_file("services/course-service/api/openapi.yaml"); puts "course openapi yaml ok"'
Result: passed.
Evidence: canonical and service-local OpenAPI YAML parsed successfully.

Legacy route: default /api/courses*, /api/student/courses*, /api/public/catalog*, wallet, question, exam, and fallback routes remain legacy-proxied.
Native route: only service-local /v1/courses/integration-contracts/question-exam was added; no public gateway route table was changed.
Gateway state: student course read/progress non-default route guards passed; they do not promote quiz/question or default course routes.
Rollback: keep deploy/gateway/routes.json as the active route table; remove callers to the service-local contract endpoint if needed. Do not promote quiz/question course routes until owner API proof, legacy response parity, browser/runtime proof, and rollback evidence are attached.

Tables touched: none; no CourseLessonQuestion or CourseQuiz table was added.
Migration run: none.
Validation report: not applicable because no live data was migrated or backfilled.

Course lesson-question and course quiz persistence remain deferred.
Public course route promotion still requires live/browser proof, rollback proof, and response parity.
Wallet/payment paid access stays legacy or future billing/wallet integration; no paid-access contract was added here.
SVC-006 has accepted bounded evidence only and remains not complete.

Implement future course lesson-question and quiz reference persistence only after question-bank/exam owner APIs are proven against a non-default route rehearsal with response parity and rollback evidence.