Introduce typed age eligibility decisions

[JorgeMucientes]

Fixes WOOMOB-3765

⚠️ Do not merge. I'll merge all 4 stacked PRs together as a final working solution.

Recommended reading before checking any of the following 4 PRs: pe5sF9-5Ch-p2

Description

Introduces the stable app-owned decision, persistence, and coordination layer needed before activating Age Signals SDK 0.0.4.

• Adds typed Allowed, VerificationRequired, and Restricted decisions with explicit restriction reasons.
• Migrates a persisted legacy restriction into the typed model.
• Clears a restriction only after an authoritative eligible result; unknown results and failures preserve it.
• Runs the startup check against the current resumed Activity, re-arms it after lifecycle cancellation, and uses an atomic single-flight guard for overlapping requests.
• Retains the derived Boolean eligibility property for existing UI consumers during the stack.

This PR keeps SDK 0.0.3 and maps its responses through a small app-owned compatibility model. LegacyAgeVerificationStatus, AgeCheckResult, and evaluateLegacyResult() are temporary scaffolding that keeps this layer behavior-preserving and independently buildable. PR #16376 replaces that adapter path with the SDK 0.0.4 access-status flow; the typed decisions, persistence rules, and coordination introduced here remain.

This is PR 1 of 4:

1. This PR — typed decisions and durable restriction state
2. PR #16375 — Recoverable verification gate
3. PR #16376 — Play Age Signals SDK 0.0.4 activation
4. PR #16377 — Telemetry, cleanup, and release validation

Test Steps

No standalone manual QA is required for this temporary compatibility layer. It retains SDK 0.0.3 behavior and has no user-visible changes. Exercise the startup, recovery, and final SDK behavior through the test instructions in the subsequent PRs.

Images/gif

N/A — no UI changes in this PR.

• I have considered if this change warrants release notes and determined it is an internal migration layer with no independently user-visible change.

[dangermattic]

	1 Error
🚫	This PR is tagged with status: do not merge label(s).

Generated by 🚫 Danger

[wpmobilebot]

📲 You can test the changes from this Pull Request in WooCommerce Android by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce Android
	Platform	📱 Mobile
	Flavor	Jalapeno
	Build Type	Debug
	Build Number	776
	Version	25.3-rc-1
	Application ID	com.woocommerce.android.prealpha
	Commit	47474be
	Installation URL	1v078tn03l8ng

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[wpmobilebot]

Version 25.4 has now entered code-freeze, so the milestone of this PR has been updated to 25.5.

[claude]

AI Code Review - Found 2 potential issues

Overall this is a well-structured refactor: the eligibility logic is extracted into a pure, thoroughly unit-tested AgeEligibilityEvaluator, the typed AgeRestrictionReason is persisted so a prior restriction survives inconclusive results, and the single-flight guard plus preserved-restriction handling look correct. The two notes below are minor.

---

_{Automatic review · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[claude]

AI Code Review [nit]

Issue: AgeEligibilityDecision.VerificationRequired is declared but never produced by the evaluator or handled anywhere. AgeEligibilityState.isUserAgeRangeEligible returns false for any non-Allowed decision, so if this variant were ever emitted it would restrict access with the generic supervised message and no dedicated handling.

Suggestion: Remove the unused variant, or wire it up (evaluator output + message mapping + UI handling) if it's intended for an upcoming step.

[JorgeMucientes]

Keeping it. It is temporary dormant scaffolding wired immediately in the next PR