Handoff: SVC-002-next-owner-read-adapter bff-service owner read-adapter contract

Scope

• Service/area: bff-service
• Task pack: docs/agents/service-tasks/bff-service.md
• Goal: accept the bounded SVC-002 slice for the first BFF owner-service read adapter, keeping BFF screen aggregation traceable to admin-service owner APIs without canonical domain writes or a primary business database.
• Non-goals: default /api/admin/overview promotion, broad admin route migration, teacher dashboard public route promotion, frontend changes, service database ownership, or replacing owner-service metrics with BFF-owned fallback data.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/architecture/api-contract-strategy.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/bff-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/qa/service-agent-goal-completion-audit.md
• go-platform/docs/qa/service-agent-readiness-smoke.md
• go-platform/services/bff-service/README.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/admin/admin-dashboard.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/analytics/analytics.controller.ts
• Legacy source was read-only evidence only; no legacy route was promoted or edited.

Files Changed

• go-platform/docs/agents/handoffs/SVC-002-next-owner-read-adapter.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 BFF implementation exposes admin overview and operations summary screen aggregation without a primary business DB.
• Existing audited owner adapter calls admin-service GET /v1/admin/operations/source-map and GET /v1/admin/operations/source-snapshots, forwards actor and organization headers, and stamps returned metadata as sourceService=admin-service.
• Existing audited BFF usecase exposes owner-source failures as degraded optional metadata instead of synthesizing canonical domain data in BFF.
• Existing audited gateway rehearsal routes only GET /api/admin/overview to /v1/bff/admin/overview in non-default route tables, with broad /api/admin staying legacy-backed.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/bff-service/...
• Result: passed.
• Evidence: bff-service HTTP and upstream tests passed.
• Command: make test-bff-routes
• Result: passed.
• Evidence: default BFF route table stayed legacy, Compose and localhost non-default examples route GET /api/admin/overview to bff-service, require gateway auth, and require ADMIN.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/internal/gateway -run BFF -count=1
• Result: passed.
• Evidence: focused gateway BFF route behavior passed.
• Command: ruby -e 'require "yaml"; ARGV.each { |path| YAML.load_file(path); puts "ok #{path}" }' services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml && diff -u services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml
• Result: passed.
• Evidence: service OpenAPI and contract mirror both parsed and matched exactly.

Current Working-Tree Re-verification

On 2026-07-14, the BFF admin screen dependency fan-out was reduced without changing the owner contract. Health checks, the admin source-map, and source-snapshot reads now run in parallel; each optional metadata result stays independently degraded when its owner read fails. The gated TestAdminOverviewReadsOwnerMetadataConcurrently requires both owner endpoint requests to begin before either response is released, and passed 100 times under -race.

• GOTOOLCHAIN=go1.25.11 go test ./services/bff-service/... -count=1, GOTOOLCHAIN=go1.25.11 go test -race ./services/bff-service/... -count=1, and GOTOOLCHAIN=go1.25.11 go vet ./services/bff-service/... passed.
• make test-bff-routes test-frontend-boundary passed.
• This is owner-read and latency behavior evidence only. It does not approve public-route promotion.

Route State

• Legacy route: deploy/gateway/routes.json remains default and keeps broad /api/admin on legacy_proxy.
• Native route: deploy/gateway/routes.bff-admin-overview-native-example.json and deploy/gateway/routes.bff-admin-overview-native-localhost-example.json route only exact GET /api/admin/overview to /v1/bff/admin/overview.
• Gateway state: make test-bff-routes confirms the BFF admin overview route appears before broad /api/admin, requires ADMIN, and does not require organization at the gateway.
• Rollback: keep using deploy/gateway/routes.json; do not promote the BFF admin overview route until route-specific runtime/browser proof, candidate review, and rollback evidence are attached.

Data Notes

• Tables touched: none.
• Migration run: none.
• Validation report: not applicable because no data was migrated.

Risks / Blockers

• Public dashboard route promotion still needs runtime/browser proof and rollback review.
• Remaining BFF source snapshots are not complete owner-service adapters unless the owner API has parity evidence.
• BFF does not own IAM/profile/wallet/payment/question/exam/import state; future adapters must keep owner-service boundaries explicit.
• Student exam-start adapter work is explicitly out of scope unless delegated with exam-service runtime-access proof.

Next Step

• Continue with the next bounded service row, or harden BFF only by replacing one additional health-only source snapshot with a named owner-service read adapter backed by owner API parity evidence.