tenant-engine/workplans/TEN-WP-0005-tenant-update-and-retirement-api.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	unblocks	state_hub_workstream_id
TEN-WP-0005	workplan	Tenant metadata update and reversible retirement API	infotech	tenant-engine	ready	codex	tenant-lifecycle	2026-08-10	2026-08-10	TEN-WP-0004	USER-WP-0021	bc1bd413-381a-4aca-aded-73cb3d0af529

TEN-WP-0005 - Tenant update and retirement API

Extend tenant-engine, the canonical tenant authority, with safe metadata update and reversible retirement operations. Tenant identifiers remain immutable. Retirement must preserve referential integrity, grant history, plan history, and audit correlation; it is not a hard-delete endpoint.

T01 - Specify tenant lifecycle and HTTP contracts

id: TEN-WP-0005-T01
status: todo
priority: high
state_hub_task_id: "5b7d9022-4c0f-4bc3-9f63-b268836c8efc"

Add an explicit tenant lifecycle (active and retired), mutable display metadata, record version, and lifecycle timestamps to the domain contract. Specify:

• GET /tenants/{tenant_id} for authoritative lifecycle and metadata reads;
• PATCH /tenants/{tenant_id} for allow-listed metadata changes;
• POST /tenants/{tenant_id}/retire for reversible retirement;
• POST /tenants/{tenant_id}/reactivate for controlled recovery.

Every mutation requires Idempotency-Key, If-Match, actor, reason, and correlation ID. Tenant IDs and identifiers are immutable. Unknown fields, empty updates, stale versions, and invalid lifecycle transitions fail closed. Document stable response/error schemas for user-engine and other consumers.

Done when the OpenAPI contract makes concurrency, idempotency, authorization, and lifecycle semantics unambiguous without defining a hard-delete operation.

T02 - Implement durable lifecycle state and migration

id: TEN-WP-0005-T02
status: todo
priority: high
state_hub_task_id: "3596d8f2-06cf-4bf9-bdab-00cf48a25956"

Extend the domain and both store implementations with display metadata, lifecycle state, version, updated/retired/reactivated timestamps, and mutation reason/correlation evidence. Add a forward-only PostgreSQL migration that defaults existing tenants to active and preserves current identifiers, roles, and plan assignments. Persist idempotency receipts so retries return the same result across process restarts.

Done when in-memory and PostgreSQL conformance prove atomic compare-and-swap, restart-safe idempotency, and lossless migration of existing tenants.

T03 - Implement authorized update and lifecycle endpoints

id: TEN-WP-0005-T03
status: todo
priority: high
state_hub_task_id: "083bcd28-47f4-4337-9bbe-e2f9f67cc2d1"

Implement the read, patch, retire, and reactivate handlers through the store abstraction. Authorize mutations with distinct flex-auth actions: tenant.update, tenant.retire, and tenant.reactivate. Return 409 for stale versions or invalid transitions, 404 for unknown tenants, and redacted 503 responses for authority/store failures. Never reflect policy or database details.

Retirement prevents new role grants and plan changes while retaining existing history for audit and recovery. Reactivation does not silently restore revoked grants or invent plan state.

Done when all lifecycle mutations are authorized, versioned, idempotent, correlated, and provider-neutral.

T04 - Add lifecycle security and compatibility conformance

id: TEN-WP-0005-T04
status: todo
priority: high
state_hub_task_id: "b716d7bf-ef6b-4b1d-bac3-e3f716d1a0b8"

Cover successful update, no-op/unknown-field rejection, identifier mutation denial, stale-version conflict, duplicate idempotency replay, conflicting-key reuse, double retirement, reactivation, update-after-retirement denial, role/plan mutation denial while retired, cross-tenant authorization denial, store outage, and concurrent writers. Verify error redaction and correlation. Prove existing create, role-read, grant/revoke, and plan clients remain compatible.

Done when unit, API, store-conformance, PostgreSQL, and flex-auth tests pass and the existing API behavior has no unplanned breaking change.

T05 - Integrate and verify the production authority

id: TEN-WP-0005-T05
status: wait
priority: high
state_hub_task_id: "9b21782a-1b26-4fac-81a1-06bd7e8cf70f"

Publish an immutable tenant-engine image, apply the migration, add the three flex-auth actions, and roll out with rollback evidence. Exercise create, update, retire, denied mutation while retired, reactivate, and idempotent replay against a disposable production tenant. Hand the finalized contract to user-engine so USER-WP-0021 can implement its platform operator UI/API without duplicating tenant authority.

Done when production evidence confirms durable lifecycle behavior and the consumer handoff names the immutable image, API version, and authorization policy revision.