Handoff: SVC-002-owner-source-gateway-proof bff-service owner source and gateway proof

Scope

• Service/area: bff-service
• Task ID: SVC-002-owner-source-gateway-proof
• Dispatch ID: SVC-002
• Task pack: docs/agents/service-tasks/bff-service.md
• Accepted first-slice handoff: docs/agents/handoffs/SVC-002-next-owner-read-adapter.md
• Goal: name owner-service source evidence and prove gateway route behavior before any BFF route promotion.
• Non-goals: default gateway route promotion, broad admin migration, frontend changes, BFF database creation, owner-service database reads, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• docs/architecture/service-responsibility-matrix.md
• docs/architecture/api-contract-strategy.md
• docs/agents/service-agent-manifest.json
• docs/agents/service-agent-proof-ledger.json
• docs/agents/service-agent-closeout-ledger.json
• docs/agents/service-agent-execution-queue.json
• docs/agents/service-agent-next-slice-queue.json
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-agent-next-slice-spawn-packets.md
• docs/agents/service-agent-accepted-handoffs.md
• docs/agents/agent-handoff-format.md
• docs/agents/service-tasks/bff-service.md
• docs/agents/handoffs/SVC-002-next-owner-read-adapter.md
• docs/api/bff-service.md
• docs/api/admin-service.md
• docs/qa/profile-admin-bff-route-rehearsals.md
• docs/qa/bff-admin-overview-owner-source-proof.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/app/**
• /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 file under /Users/velikho/Desktop/WORKING/HOCTAPAZ/ was changed.

Files Changed

• services/bff-service/internal/http/owner_source_integration_test.go
• docs/agents/handoffs/SVC-002-owner-source-gateway-proof.md
• docs/qa/bff-admin-overview-owner-source-proof.md
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-agent-next-slice-closeout-ledger.md
• docs/agents/service-agent-accepted-handoffs.md
• docs/agents/service-tasks/bff-service.md
• docs/api/bff-service.md
• docs/index.md
• docs/.vitepress/config.ts
• docs/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md

No default gateway route table or shared deploy manifest was changed.

Behavior Implemented

• Added an integration-style BFF HTTP test with a real httptest owner endpoint for admin-service source-map and source-snapshot APIs.
• Proved actor, role, and organization headers are forwarded to the owner service and owner metadata is returned through the BFF admin overview.
• Kept owner failures as degraded optional metadata; BFF does not synthesize domain metrics or read owner databases.
• Confirmed the exact non-default gateway route maps GET /api/admin/overview to /v1/bff/admin/overview, while broad admin and fallback routes remain legacy-backed.

Required evidence covered:

• owner-service source evidence
• gateway route proof
• BFF aggregation test

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/bff-service/...

• Result: passed, including the new owner-source integration test and existing upstream/degraded metadata tests.

• Command: make test-bff-routes

• Result: passed. The default table remains legacy; Compose and localhost non-default tables contain only the exact admin overview BFF route with ADMIN gateway authorization.

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/internal/gateway -run BFF -count=1

• Result: passed. Native BFF rewrite and legacy fallback behavior are covered.

• Command: ruby -e 'require "yaml"; ARGV.each { |path| YAML.load_file(path) }' services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml

• Result: passed; both OpenAPI files parsed.

• Command: diff -u services/bff-service/api/openapi.yaml contracts/openapi/services/bff-service.yaml

• Result: passed; service contract and mirror match.

• Command: docker compose -f deploy/docker-compose.yml config --quiet

• Result: passed; BFF/admin runtime wiring remains valid.

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/admin-service/internal/usecase -run TestOperationsSourceMapRequiresExplicitOwnerApis -count=1

• Result: passed; owner source map has explicit, unique owner API entries and remains legacy-status until route proof.

Route State

• Route/default state: implementation remains blocked until the owner API is named; gateway route proof required before public dashboard route promotion
• Owner API is now explicitly named as admin-service source-map/source-snapshots endpoints for this bounded adapter.
• Gateway route proof is non-default only. deploy/gateway/routes.json remains untouched and broad /api/admin remains legacy_proxy.
• Rollback: use GATEWAY_ROUTE_TABLE=deploy/gateway/routes.json, rerun make test-bff-routes, and keep the BFF exact route inactive until runtime, browser, candidate, and rollback review are complete.

Data Notes

• Tables touched: none.
• Migrations: none.
• Validation report: not applicable because no business data changed.

Risks / Blockers

• Static/native route proof is complete, but browser/runtime proof for the promoted public dashboard route is still missing.
• Native BFF overview is not full legacy dashboard parity; broad admin metrics and remaining health-only source snapshots need additional owner adapters.
• The BFF service remains not-complete and must not become a domain source of truth.

Next Step

• Continue with SVC-003-default-auth-cutover-proof-bundle only through its production-like data gate, or proceed to the next non-gated service slice; do not promote the BFF route from this handoff alone.