Handoff: SVC-001-default-route-proof-bundle api-gateway default route proof bundle

Scope

• Service/area: api-gateway
• Task ID: SVC-001-default-route-proof-bundle
• Dispatch ID: SVC-001
• Task pack: docs/agents/service-tasks/api-gateway.md
• Accepted first-slice handoff: docs/agents/handoffs/SVC-001-protected-route-jwks-rehearsal.md
• Goal: produce the gateway route diff, live/browser route proof, and rollback notes required before any default public route promotion.
• Non-goals: modifying deploy/gateway/routes.json, approving default promotion, changing IAM/Profile ownership, editing frontend callers, or changing 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/api-gateway.md
• docs/agents/handoffs/SVC-001-protected-route-jwks-rehearsal.md
• docs/qa/iam-profile-route-rollback-rehearsal.md
• docs/qa/auth-route-live-smoke.md
• docs/qa/auth-route-browser-smoke.md
• docs/qa/profile-route-live-smoke.md
• docs/qa/profile-route-browser-smoke.md
• docs/qa/api-gateway-default-route-proof-bundle.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/main.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/lib/api-config.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/lib/api.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/lib/client-api.ts

Legacy source was read-only evidence only. No file under /Users/velikho/Desktop/WORKING/HOCTAPAZ/ was changed.

Files Changed

• docs/agents/handoffs/SVC-001-default-route-proof-bundle.md
• docs/qa/api-gateway-default-route-proof-bundle.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/api/api-gateway.md
• docs/index.md
• docs/.vitepress/config.ts
• docs/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md

No gateway route table or runtime source was changed in this proof-only slice.

Behavior Implemented

• The gateway route diff is documented and backed by the route coverage guards for auth, profile, organization, attempt, and BFF native candidates.
• Live/browser route proof is indexed from confirmed gateway artifacts, including browser-observed route headers and legacy sibling behavior.
• Rollback notes are captured by a fresh 2026-07-10 artifact proving deploy/gateway/routes.json remains the rollback table with broad routes on legacy_proxy and exact native carve-outs absent.
• No default route was promoted. This is an audit/proof slice with no new business behavior; the existing gateway route behavior remains unchanged.

Required evidence covered:

• gateway route diff
• live/browser route proof
• rollback notes

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/...

• Result: passed with ok .../services/api-gateway/internal/gateway.

• Command: make test-auth-routes test-auth-routes-live test-auth-routes-browser test-auth-routes-session-browser test-profile-routes test-organization-routes test-attempt-routes test-bff-routes

• Result: static route coverage and all self-tests passed. The aggregate command then stopped at the intentional live confirmation guard because AUTH_ROUTE_LIVE_CONFIRM=auth-native was not supplied. This guard prevents an unreviewed live call; confirmed live/browser results are recorded in docs/qa/api-gateway-default-route-proof-bundle.md.

• Command: make test-auth-routes

• Result: passed. Default auth table remained legacy and native auth examples passed static coverage plus live/browser/session self-tests.

• Command: make test-profile-routes test-organization-routes test-attempt-routes test-bff-routes

• Result: passed. Profile, organization, attempt, and BFF route tables passed static coverage and the BFF gateway test.

• Command: make test-frontend-boundary

• Result: passed. Frontend callers remain gateway/BFF-only.

• Command: IAM_PROFILE_ROUTE_ROLLBACK_ARTIFACT_DIR=output/qa/iam-profile-route-rollback-20260710-svc001 make test-iam-profile-route-rollback

• Result: passed. The artifact records defaultRouteTableModified=false, broad auth, admin, and fallback as legacy_proxy, and native exact routes as absent from the rollback table.

• Existing runtime evidence reviewed: output/qa/auth-route-live-20260709-115133/, output/playwright/auth-route-browser-smoke-20260709-115940/, output/playwright/auth-route-session-browser-smoke-20260709-100744/, output/qa/profile-route-live-20260709-121055/, output/playwright/profile-route-browser-smoke-20260709-121825/, and output/qa/iam-profile-default-candidate-rollback-20260709-095948/.

Route State

• Route/default state: non-default rehearsal; default route promotion still requires live/browser proof and rollback notes
• deploy/gateway/routes.json remains the default table and was not modified.
• Auth, profile, organization, attempt, and BFF native candidates remain in separate route tables with exact route matching and legacy fallbacks.
• Rollback: restore/use GATEWAY_ROUTE_TABLE=deploy/gateway/routes.json, then run make test-iam-profile-route-rollback and the affected route coverage target. Do not leave native carve-outs active in the default table.
• IAM/Profile populated-target validation, UUID primary-key promotion, and candidate approval remain outside this handoff.

Data Notes

• Tables touched: none.
• Migrations: none.
• Data validation report: not applicable because this slice changed no data.

Risks / Blockers

• The live smoke command is explicitly confirmation-gated; the aggregate workflow without AUTH_ROUTE_LIVE_CONFIRM=auth-native is expected to stop rather than contact a gateway.
• Existing live/browser evidence is non-default rehearsal evidence, not default promotion approval.
• Production-like IAM/Profile populated data, required migrator run report, candidate route review, and rollback-after-candidate approval remain open.
• The broad service-agent goal remains active-not-complete.

Next Step

• Continue with SVC-002-owner-source-gateway-proof for BFF owner-service source evidence and gateway aggregation proof, while keeping default gateway routes orchestrator-owned.