Handoff: SVC-014-projection-worker-runtime-fixtures search-service projection worker runtime fixtures

Scope

• Service/area: search-service
• Task pack: docs/agents/service-tasks/search-service.md
• Goal: accept the bounded SVC-014 slice for search projection worker and rebuild fixture evidence across question-bank, course, exam, and document owner projections, while keeping search-service as a copied-index/read-model owner rather than a source of truth.
• Non-goals: public /api/search compatibility routes, default gateway promotion, owner-service canonical writes, browser route parity, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/architecture/legacy-api-map.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-tasks/search-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/qa/search-route-rehearsals.md
• go-platform/docs/qa/service-agent-goal-completion-audit.md
• go-platform/docs/qa/service-agent-readiness-smoke.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/questions/questions.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exams/exams.controller.ts
• /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/storage/storage.controller.ts
• Legacy source was read-only evidence only; no public search route parity is claimed because no exact legacy search route has been assigned to search-service.

Files Changed

• go-platform/docs/agents/handoffs/SVC-014-projection-worker-runtime-fixtures.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• No new runtime code was implemented in this handoff.
• Existing audited search-service projection rebuild APIs pull copied QUESTION, COURSE, EXAM, and DOCUMENT projections from owner-service HTTP routes, validate owner sourceService and entityType, write service-owned index rows, and update sync-state cursors.
• Existing audited projection freshness worker is opt-in via SEARCH_REBUILD_WORKER_ENABLED=1, resumes from sync-state cursors, caps each tick with SEARCH_REBUILD_WORKER_MAX_PAGES, and records owner-source failures as sync-state ERROR without making search-service unavailable.
• Existing audited organization-scope handling requires a scoped organization unless allOrganizations=true is requested by an ADMIN; explicit organizationId wins over global bypass.
• Existing audited route guard blocks synthetic /api/search or search-service public gateway targets until an exact legacy route mapping is assigned.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/search-service/... -count=1
• Result: passed.
• Evidence: search-service HTTP, repository, and usecase packages passed.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/search-service/internal/http -run 'TestQuestionBankProjectionFixtureRebuild|TestDocumentServiceProjectionFixtureRebuild' -count=1 -v
• Result: passed.
• Evidence: question-bank and document fixture rebuilds covered copied index rows, idempotent rebuild, filters, and sync-state behavior.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/search-service/internal/usecase -run 'TestProjectionFreshnessWorker|TestRebuildFromProjection|TestHTTPProjectionSource' -count=1 -v
• Result: passed.
• Evidence: freshness worker cursor resume/page cap, source error recording, projection rebuild validation, admin-only global bypass, and HTTP projection source fetches passed.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/search-service/internal/http -run 'TestSearchRebuildQuestionBankQuestionsRoute|TestSearchRebuildCourseServiceCoursesRoute|TestSearchRebuildExamServiceExamsRoute|TestSearchRebuildDocumentServiceDocumentsRoute' -count=1 -v
• Result: passed.
• Evidence: all owner-source rebuild routes passed.
• Command: make test-search-rebuild
• Result: passed.
• Evidence: external rebuild helper self-test indexed paginated course, document, exam, and question-bank projection pages.
• Command: make test-search-routes
• Result: passed.
• Evidence: search route rehearsal guard confirmed no route table targets search-service and no synthetic /api/search compatibility route exists.
• Command: SEARCH_REBUILD_SELF_TEST=1 python3 scripts/migration/rebuild-question-search-index.py
• Result: passed.
• Evidence: self-test completed paginated rebuild loops for course, document, exam, and question-bank.

Route State

• Legacy route: default gateway routes remain unchanged; search-service has no public /api/* default route.
• Native route: none accepted in this handoff because no exact legacy route is mapped to search-service.
• Gateway state: make test-search-routes keeps all search-service public route rehearsal work pending and blocks synthetic /api/search.
• Rollback: keep the current default route table. A future search route rehearsal must first name the exact legacy route, native target, route guard, browser/runtime proof, and rollback evidence.

Data Notes

• Tables touched: none in this handoff run; tests used in-memory stores unless package tests exercised local repository code without a live Postgres URL.
• Migration run: no live rebuild/backfill was executed.
• Validation report: not applicable because no live data was migrated.

Risks / Blockers

• Optional Postgres integration was not run because SEARCH_SERVICE_POSTGRES_TEST_DATABASE_URL was not provided.
• Public search/catalog promotion remains blocked until a real legacy controller route is selected and mapped to search-service.
• Browser/runtime parity and rollback evidence remain required before any future default route cutover.
• Search-service copied indexes must not bypass owner-service visibility or authorization decisions.

Next Step

• Either provide a live disposable Postgres URL for search-service integration proof, or assign a real legacy route mapping before starting any public search route rehearsal.