---
id: USER-WP-0011
type: workplan
title: "Prepared Accounts And Entitlement Claims"
domain: communication
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: high
planning_order: 11
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - USER-WP-0010
state_hub_workstream_id: "39ac9f87-c61d-42d8-a45f-bece4848ed47"
---

# USER-WP-0011 - Prepared Accounts And Entitlement Claims

## Goal

Allow NetKingdom operators, tenant admins, family owners, service owners, or
upstream systems to prepare account intent and access packages before the user
registers. When the user later proves matching factors, user-engine can attach
the prepared package to the canonical user and activate the right lifecycle
steps.

## Scope Direction

Prepared accounts are not credentials. They are pending user-domain facts:
expected factor matches, tenant or group references, planned memberships,
profile defaults, onboarding journey hints, approval gates, expiry, and audit
history.

## Non-Goals

- Do not create login credentials for users who have not registered.
- Do not bypass factor verification or approval policies.
- Do not make user-engine the source of truth for external organization, HR, or
  directory records.
- Do not implement final authorization policy decisions.

## Tasks

```task
id: USER-WP-0011-T1
status: done
priority: high
state_hub_task_id: "11508f77-170b-4b22-bfdc-115a69bfe4db"
```

Add prepared account and prepared entitlement models with status, expiry,
preparer identity, tenant/scope references, factor match requirements, and
audit metadata.

```task
id: USER-WP-0011-T2
status: done
priority: high
state_hub_task_id: "86ca36d4-721b-48fe-8c0c-c6a1e6740d2f"
```

Implement create, update, revoke, expire, and list operations for prepared
accounts, guarded by the authorization port.

```task
id: USER-WP-0011-T3
status: done
priority: high
state_hub_task_id: "fe5a08e8-1101-4cec-b02f-b2eee8928604"
```

Implement claim matching during registration. Match verified factor evidence to
prepared account requirements and produce explicit claim decisions.

```task
id: USER-WP-0011-T4
status: done
priority: high
state_hub_task_id: "8aef6d9e-5e76-4e44-bf81-58049b22a25c"
```

Convert claimed prepared entitlements into user-engine-owned facts:
memberships, tenant accounts, profile defaults, application bindings, and
onboarding journey starts.

```task
id: USER-WP-0011-T5
status: done
priority: medium
state_hub_task_id: "527519a1-48ed-45fc-a6fc-739986ae6303"
```

Add conflict and safety rules for duplicate prepared accounts, weak factor
matches, expired packages, privileged roles, and manual approval requirements.

```task
id: USER-WP-0011-T6
status: done
priority: medium
state_hub_task_id: "9530c8d6-82af-4635-8af8-aa79c54be94d"
```

Add audit/outbox events and evidence references for preparation, claim,
activation, denial, expiry, and revocation.

## Acceptance Criteria

- A prepared account can be created before user registration without issuing
  credentials.
- A registering user can claim prepared rights only when required factor
  evidence matches.
- Claimed rights become explicit user-engine memberships, profile values,
  tenant account state, and onboarding events.
- Expired, revoked, ambiguous, or privileged claims fail closed.
- Every preparation and claim decision is auditable.

## Expected Outputs

- Prepared account domain model.
- Prepared entitlement activation facade.
- Claim matching rules and tests.
- Documentation for account preparation boundaries.

## Implementation Notes

Implemented on 2026-06-15:

- Added `PreparedAccountStatus`, `PreparedEntitlementKind`,
  `PreparedFactorRequirement`, `PreparedEntitlement`, and `PreparedAccount`
  domain models.
- Added prepared-account persistence to `UserEngineStore` and
  `InMemoryUserEngineStore`, including transaction rollback snapshots and
  adapter-neutral record counts.
- Added `UserEngineService` prepared-account facade methods:
  `prepare_account`, `update_prepared_account`, `list_prepared_accounts`,
  `revoke_prepared_account`, `expire_prepared_account`, and
  `claim_prepared_account`.
- Added factor-match claim resolution for completed registrations, explicit
  claim decisions, duplicate pending package checks, expiry handling,
  weak-factor rejection, ambiguous-match rejection, expired-factor rejection,
  and approval-required fail-closed behavior.
- Added entitlement activation into tenant accounts, memberships, catalog
  validated profile values, application bindings, and onboarding-request
  outbox events.
- Added audit/outbox behavior for preparation, update, claim, onboarding
  request, expiry, and revocation while keeping normalized factor values out
  of event payloads.
- Added `docs/prepared-accounts-and-entitlement-claims.md`, public contract
  updates, and scenario tests for successful claim, mismatch, ambiguity,
  approval-required denial, list, and revoke behavior.

Verification:

```text
make test
Ran 55 tests in 0.362s
OK
```