User-Service Retirement Readiness

Status: quarantine confirmed, retirement blocked.

user-service is a deprecated compatibility scaffold. It is not a canonical identity or profile owner and must receive no new product work. Identity, credentials, sessions, roles, permissions, and organization membership belong to iam-service; educational profile and KYC data belong to profile-service.

Route Inventory

Deprecated user-service route	Replacement / reason	Current retirement state
GET /v1	Compatibility marker only; no product replacement needed.	Keep until runtime removal is approved.
PUT /v1/users/{userId}/profile-snapshot	profile-service exposes the same compatibility snapshot path for IAM/backfill hydration.	Replacement exists; backfill proof still required.
GET /v1/users/{userId}/profile	profile-service compatibility read path and native profile APIs.	Replacement exists; default cutover remains gated.
PATCH /v1/users/{userId}/profile	profile-service owns base profile writes.	Replacement exists; candidate/default rollback proof remains open.
PATCH /v1/users/{userId}/teacher-profile	profile-service owns teacher profile and KYC-adjacent profile data.	Replacement exists; production-like proof remains open.
PATCH /v1/users/{userId}/student-profile	profile-service owns student profile data.	Replacement exists; live/browser parity remains open.
PATCH /v1/users/{userId}/parent-profile	profile-service owns parent profile data.	Replacement exists; live/browser parity remains open.

The user-service routes are not present in the default gateway route table. The default /api/auth* compatibility family remains legacy_proxy; non-default auth/profile examples target IAM/Profile only. No user-service entry was found in Compose, K8s service manifests, Helm service values, BFF upstream targets, or migration jobs.

IAM/Profile Parity Evidence

• GOTOOLCHAIN=go1.25.11 go test ./services/user-service/... -count=1 passed; compatibility responses retain deprecation and canonical-owner headers.
• GOTOOLCHAIN=go1.25.11 go test ./services/profile-service/... ./services/iam-service/... -count=1 passed.
• make test-profile-routes test-auth-routes passed static route coverage and self-test live/browser/rollback hooks.
• The latest linked bundle is output/qa/iam-profile-default-cutover-proof-bundle-20260709-121632/. Its summary is mode=self-test, selfTestOnly=true, targetProvenance=fixture_only, with null live minimums and route hashes.
• make test-iam-profile-default-cutover-review-artifact rejects that bundle, as required, because it lacks production-like populated-target evidence, required migrator run-report reconciliation, per-step summaries, and matching candidate/gateway route hashes.

These results prove quarantine and replacement direction, not removal approval.

Runtime Manifest Removal Plan

After an accepted production-like IAM/Profile bundle:

1. Re-run the route inventory and verify no gateway, BFF, Compose, K8s, Helm, Prometheus, migration, or service-readiness reference still requires user-service.
2. Remove the deprecated service image/deployment and its migration job only in an explicit orchestrator-owned change.
3. Keep profile backfill/reconciliation reports and compatibility route mapping attached to the removal change.
4. Run the full service/readiness/docs guards and verify the default route table hash was not changed unintentionally.

Default-Route And Rollback Proof

The default route table remains deploy/gateway/routes.json. No default auth, profile, KYC, or compatibility route was promoted in this readiness slice.

Rollback plan:

• Restore deploy/gateway/routes.json as the active table and disable native IAM/Profile callers if any candidate route regresses.
• Re-enable the retained user-service compatibility deployment and image during the rollback window; do not drop its tables or migrations until parity is reconciled.
• Preserve Deprecation: true, X-Hoctapaz-Service-Status, and canonical-owner headers on compatibility responses.
• Re-run auth/profile route live/browser checks, migration reconciliation, and the offline review artifact before attempting removal again.

Retirement Criteria

Retirement remains blocked until all of these are attached to one reviewed change:

• IAM/Profile production-like populated-target parity with required migrator run-report status passed, zero issues, zero rejected rows, and owner-local reconciliation.
• Candidate/default route diff, live gateway proof, browser proof, and rollback-after-candidate proof with matching route-table hashes.
• Route inventory showing every user-service route replaced or explicitly compatibility-only, with no runtime manifest or migration dependency left.
• A reviewed removal plan covering gateway, Compose, K8s, Helm, migrations, compatibility headers, observability, and rollback.

Verification

GOTOOLCHAIN=go1.25.11 go test ./services/user-service/...
GOTOOLCHAIN=go1.25.11 go test ./services/profile-service/... ./services/iam-service/...
make test-profile-routes test-auth-routes
IAM_PROFILE_DEFAULT_CUTOVER_PROOF_BUNDLE_ARTIFACT_DIR=output/qa/iam-profile-default-cutover-proof-bundle-20260709-121632 make test-iam-profile-default-cutover-review-artifact
make test-service-agent-goal-completion-audit

The first three commands passed. The review-artifact command rejected the fixture/self-test bundle as expected; the goal-completion audit passed while keeping retirement and the broad rollout not-complete.