Handoff: SVC-004-profile-backfill-cutover-hardening profile-service backfill and cutover hardening

Scope

• Service/area: profile-service
• Task pack: docs/agents/service-tasks/profile-service.md
• Goal: accept the bounded profile ownership and cutover-hardening evidence while keeping default profile route promotion gated.
• Non-goals: default /api/auth/me* or admin KYC route promotion, populated production target backfill approval, IAM session/role ownership, credential/token handling, broad user-service work, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.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/profile-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/api/profile-service.md
• go-platform/docs/qa/profile-route-live-smoke.md
• go-platform/docs/qa/profile-route-browser-smoke.md
• go-platform/services/profile-service/README.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/components/account/profile-settings-client.tsx
• Legacy source was read-only evidence only; no legacy files were changed.

Files Changed

• go-platform/docs/agents/handoffs/SVC-004-profile-backfill-cutover-hardening.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• none in this handoff.
• Existing audited profile-service implementation owns base profile, public profile, contacts, student/teacher/parent/staff profile rows, teacher KYC self-service/admin review, parent-child read models, parent recipient resolution, profile owner summary, profile mutation events, audit projection, and UUID shadow/backfill migration foundations.
• Existing tests cover safe public redaction, projection/access-control field rejection, KYC CCCD hashing/redaction, admin KYC review behavior, parent-recipient internal token guards, profile owner summary, audit event context/redaction/projection, OpenAPI mirror checks, and repository migrations.
• Existing docs and route guards keep credentials, sessions, JWT, roles, permissions, and authorization decisions in iam-service; profile role/status/staff scope fields are projection/display metadata only.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/profile-service/... -count=1
• Result: passed.
• Evidence: profile-service command, audit sink, HTTP, repository, and usecase packages passed.
• Command: make test-profile-routes test-profile-kyc-routes test-profile-admin-kyc-routes
• Result: passed.
• Evidence: default profile routes stayed legacy; non-default profile, teacher KYC, and admin KYC route examples passed route coverage; profile live/browser smoke scripts passed self-test mode.
• Command: ruby -e 'require "yaml"; ARGV.each { |path| YAML.load_file(path); puts "ok #{path}" }' services/profile-service/api/openapi.yaml contracts/openapi/services/profile-service.yaml && diff -u services/profile-service/api/openapi.yaml contracts/openapi/services/profile-service.yaml
• Result: passed.
• Evidence: Profile service OpenAPI and mirrored contract parsed and matched exactly.

Route State

• Legacy route: deploy/gateway/routes.json remains the default rollback table and keeps broad /api/auth and /api/admin profile/KYC compatibility routes on legacy paths.
• Native route: deploy/gateway/routes.profile-native-example.json, routes.profile-kyc-native-example.json, and routes.profile-admin-kyc-native-example.json remain non-default rehearsals only.
• Gateway state: this handoff accepts profile service-side and non-default route guard evidence only; it does not promote default public profile or KYC routes.
• Rollback: keep deploy/gateway/routes.json active. If a non-default profile route table is used for rehearsal, switch GATEWAY_ROUTE_TABLE back to deploy/gateway/routes.json to roll back to legacy.

Data Notes

• Tables touched: none in this handoff run.
• Migration run: none against a live database in this handoff.
• Validation report: not applicable because no live data was migrated or backfilled.
• Existing service migrations include Profile UUID shadow, FK validation, and primary-key promotion scaffolding; populated-target validation remains gated by the IAM/Profile cutover task packs.

Risks / Blockers

• This is closeout-accepted-cutover-gated-not-complete, not completion of the full IAM/Profile cutover.
• Optional Postgres integration commands requiring PROFILE_SERVICE_POSTGRES_TEST_DATABASE_URL were not run in this handoff because no DSN was configured for this turn.
• Fresh real gateway/browser runs were not rerun in this handoff; current docs retain latest local artifacts from 2026-07-09.
• Default route promotion still requires populated target proof, candidate diff/review, browser proof, rollback proof, and coordination with iam-service.

Next Step

• Audit RET-USER so the deprecated user-service scaffold stays quarantined and no new identity/profile work is routed there.