Plan: Typed Path<*Id> rollout — workspace-wide (#627)

Issue: #627
Branches: one per step — feature/627-typed-ids-{slug}
Reference commit: 5bb503f7 — the verification slice (MR !785), already merged, is the proven template.

The define_id! typed-ID migration (crates/canopy-common/src/id.rs) replaced raw Uuid path parameters with per-entity newtypes across most services in April 2026 but left holdouts. The verification slice was since completed (5bb503f7) as the template. A workspace audit finds 61 raw Path<Uuid> extractors remain = the 46 in the five services the issue names (tanf 17, medicaid 12, caps 8, snap 5, wic 4) plus canopy-applications (10), canopy-persons (4), canopy-security (1). Per the owner decision this plan migrates all 61 so the finalization lint can ban the pattern with a near-empty allowlist — the sole entries are the 2 canopy-applications worker Path sites, which a worker is an issuer-scoped OIDC subject (a string), not a domain UUID: typing that awaits the worker-identity redesign (Step 8 decision; #559/#493 + multi-IdP). (Per-step site counts, which regroup the shared FTI 2 + overpayments 12 into Steps 1–2: 2+12+4+1+8+7+12+10+4+1 = 61.)

Typed path IDs turn an ID-transposition bug into a compile error. This is a behaviour-preserving refactor (the newtypes are wire/OpenAPI/DB-transparent) with two deliberate deviations the owner approved: the shared overpayments DTO crate is fully typed (below), and the incoherent wic appointment route is re-scoped (a pre-1.0 wire change, below).

In scope: every raw Path<Uuid> / Path<uuid::Uuid> / tuple Path<(… Uuid …)> under services/*/src/api/; the newtypes each needs; threading each id through its store fn(s) + the entity’s contract .id; the shared canopy-overpayments crate + its cross-service consumers; the wic appointment route re-scope; a workspace lint banning Path<Uuid>.

Out of scope: any behaviour change other than the two approved deviations (overpayments full-thread, wic re-scope); #628 (DeterminationStatus).

Each step = one MR via Per-slice recipe (every step), independently mergeable; shared surfaces (1–2) first. Every new .rs file starts with // SPDX-License-Identifier: AGPL-3.0-or-later.

Step 0 — Commit the plan. Write this plan (body only) to docs/modules/ROOT/pages/plans/typed-path-id-rollout.adoc, add its nav.adoc xref under "Code Quality & Infrastructure", commit on feature/627-typed-ids-plan → docs-MR → merge. (Plans are in-repo .adoc + nav-linked before implementation.)

Step 1 — Shared FTI id (2 sites). Mint FtiAuditEntryId; type FtiAuditEntry.id, FtiAuditLogger::get_entry, and the PostgresFtiAuditLogger impl (all crates/canopy-common/src/fti_audit.rs); type Path<FtiAuditEntryId> at services/canopy-{tanf,medicaid}/src/api/fti_audit_handlers.rs:92; fix the 3 construction sites (medicaid/tanf determine.rs, tanf fti_audit_hash_chain_test.rs).

Step 2 — Shared overpayments, full thread-through (12 path sites + consumers). Mint RepaymentPlanId, RecoupmentLedgerEntryId (reuse OverpaymentClaimId); add canopy-common to canopy-overpayments. Type ALL id + FK fields in canopy-overpayments/src/lib.rs (OverpaymentClaim/RepaymentPlan/ RecoupmentLedgerEntry/CreateClaimRequest: id, overpayment_claim_id, repayment_plan_id, person_id, household_id, determination_id). Type the 4 path sites + store fns in each of snap/tanf/medicaid (api/overpayments_handler.rs:{109,137,165,191} + store/overpayments.rs). Update consumers (same MR): canopy-reporting clients/mod.rs — list_overpayment_claims (:342, returns Vec<OverpaymentClaim>) and get_overpayment_ledger (:363, param claim_id: Uuid, returns LedgerView); reporting/overpayments.rs loops those and reads claim.id/claim.person_id/… (:38-48) + passes claim.id into get_overpayment_ledger (:39, needs .into_inner()); the snap/tanf/medicaid main.rs RabbitMQ CreateClaimRequest construction sites + snap recompute_persist.rs/ipv_claim.rs. AlreadyClosed { id: claim_id.into() }.

Step 3 — canopy-wic (4 sites; + appointment route re-scope). Add canopy-common to contracts-wic. Mint WicParticipantId, WicAssessmentId.

Appointment re-scope (owner-approved, pre-1.0): the value is a fiction — no wic_certifications table, the server aliases it to household_id (let household_id = certification_id), and the BFF (canopy-web/src/api/actions_wic.rs::schedule_certification_appointment_wic) already holds form.household_id. Change the route to POST /v1/wic/households/{household_id}/appointments, Path<HouseholdId>; the BFF passes form.household_id; stop writing the bogus wic_appointments.certification_id column (leave NULL). Drop certification_id from the ScheduleCertificationAppointmentWicForm (BFF form) and from the response DTO WicAppointment (crates/canopy-contracts-wic/src/appointments.rs:43). Note: ScheduleAppointmentRequest has NO certification_id field (nothing to drop there; the BFF request body already omits it). Relate to #571 (this supersedes its participant-indirection; note #571 for close/reduce). Verify the upcoming_appointments panel doesn’t read certification_id. OpenAPI exception: this route-path + body change is a deliberate pre-1.0 wire change, so cargo xtask api-docs --update IS expected on this slice (regenerate + CHANGELOG the route change) — the "zero drift" rule in Per-slice recipe (every step) holds for every OTHER slice.

Step 4 — canopy-snap (1 site). contracts-snap has canopy-common. Mint TsnapCertificationId; type get_tsnap (tsnap_handler.rs:28) + TsnapCertification.id + store/tsnap.rs:94. (overpayments → Step 2.)

Step 5 — canopy-caps (8 sites; + PK fix). Add canopy-common to contracts-caps. Mint CapsAuthorizationId, CapsProviderId.

Also type SwitchProviderRequest.new_provider_id + AuthorizationCreatedEvent.authorization_id. Fix in-slice: providers.rs:52 Uuid::new_v4() → CapsProviderId::new() (v7) — the PK must be v7 (owner: fix, don’t defer).

Step 6 — canopy-medicaid (7 sites). Mint MedicaidApplicationId. (overpayments → Step 2; FTI → Step 1.)

Step 7 — canopy-tanf (12 sites). Add canopy-common to contracts-tanf. Mint TanfPersonalResponsibilityId, TanfApplicationId, TanfDiscrepancyId. (overpayments → Step 2; FTI → Step 1.)

Step 8 — canopy-applications (+ the enrollment gate). Mint HouseholdAssignmentId, RecoveryId. Worker identity stays raw Uuid (see the newtype note): the 2 worker Path sites are left Path<Uuid> and Step-11-allowlisted; transposition safety comes from typing the household side.

Contract typing: HouseholdAssignment.{id→HouseholdAssignmentId, household_id→HouseholdId} — keep their #[schema(value_type=String)] overrides → snapshot-neutral; worker_id stays Uuid (Tier-3: the enrollment gate deserialises it cross-service as Uuid). ApplicationDocument.{id→DocumentId, application_id→ApplicationId, person_id→PersonId} have no overrides → the applications OpenAPI snapshot regenerates (a new DocumentId component + $ref`s; wire-identical → `api-docs --update); accepted_by stays Uuid. Recovery DTOs/events stay Uuid (a Uuid-native event pipeline read back by canopy-notices via GET /recover/{recovery_id}). Row mirrors
store fns threaded to match; recovery is minimal (recover_get Path + store::get_by_id). Enrollment gate (Decision — included): is_worker_assigned_to_household (canopy-enrollment/src/clients/mod.rs:65) gets household_id → HouseholdId (worker stays Uuid) so the Pub-1075 §9.3.1 (worker, household) authz transposition is a compile error — the caller already holds HouseholdId. Test hardening: added the missing store/assignments.rs unit-test module (covers is_assigned) and an infrastructure_available() guard to document_test/recovery_test (they skipped silently under CANOPY_CI). Correct worker typing is deferred to the worker-identity redesign (follow-up #1008; relates #559/#493 + multi-IdP). The document accepted_by trust-boundary hardening (derive from verified claims, not the body) is follow-up #1009.

Step 9 — canopy-persons (4 tuple sites). persons already has canopy-common. Mint FactId. Each tuple’s first element (household_id/person_id) is already typed; only the fact_id (last) element is retyped.

The 3 close_*_version store fns type the public param and convert once at entry (let fact_id = fact_id.into_inner();) — the shared bitemporal engine (lock_fact/snapshot_and_supersede/ reinsert_remnants, also driven by the claim path) stays Uuid. persons has no worker Path sites, so its residual-Path<Uuid> grep is empty (nothing to allowlist here).

Step 10 — canopy-security (1 site). fact_change_history (mod.rs:193) Path<(uuid::Uuid, String)> → (PersonId, String); store list_fact_change_history takes Uuid → .into_inner() (the audit_events store is a generic cross-service ledger, Tier-3); resource stays String. The FactChangeEntry response DTO keeps its Uuid fields (person_id/fact_id/version_id — a generic cross-service audit record read from persons' events, Tier-3), so — with the utoipa path-param doc-type left = Uuid — the security OpenAPI snapshot is unchanged.

Step 11 — Finalization lint (final MR carries the closing keyword for #627). New xtask/src/cmd/typed_ids.rs::run_audit_path_uuid() (SPDX header; registered in cmd/mod.rs AND wired as a Command variant in xtask/src/main.rs with dispatch, so cargo xtask typed-ids audit-path-uuid runs standalone). Regex catches Path<Uuid>, Path<uuid::Uuid>, and tuple Path<(… Uuid …)> across services/ + crates/; bails with a file:line list. Allowlist file compliance/typed-id-path-allowlist.toml — the 2 worker Path sites only (canopy-applications/src/api/assignments.rs create_assignment + list_assignments_by_worker), each with a reason pointing at the worker-identity redesign (issuer-scoped OIDC subject, not a domain UUID — #1008, which relates #559/#493 + the multi-IdP epic). Every other raw Path<Uuid> in the tree is typed; the allowlist entries are removed by that follow-up, not by Step 11. Wire as a numbered step in cargo xtask validate after the ADR-011 audits + mirror as a CI job. The MR for this step carries the closing keyword for #627 (see recipe — do not write that literal phrase in any earlier MR).