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	active	codex	tenant-lifecycle	2026-08-10	2026-08-14	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: done
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.

Done 2026-08-10: lifecycle (active/retired), allow-listed mutable metadata (display_name, contact_email), record version, and lifecycle timestamps are in the domain contract. All four routes exist; the allow-list is enforced by the request schema (extra: forbid) so it is visible in the OpenAPI document. Consumer contract written up in docs/tenant-lifecycle-api.md. No hard-delete operation was defined.

T02 - Implement durable lifecycle state and migration

id: TEN-WP-0005-T02
status: done
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.

Done 2026-08-10, against SQLite rather than PostgreSQL: this workplan was drafted assuming Postgres, but TEN-WP-0004 shipped SQLite on a PVC as the production store, so the migration and conformance target the store that actually runs. Adding an unused Postgres path would have been dead code. The TenantStore Protocol keeps the seam if the backend changes later.

mutate_tenant() carries idempotency replay, version CAS, mutation, and audit event in one commit -- splitting them would leave a window where a crash yields a bumped version with no receipt (a retry then double-applies). The migration is forward-only and idempotent: existing rows default to active at version 1 with identifiers, grants, and plans untouched.

T03 - Implement authorized update and lifecycle endpoints

id: TEN-WP-0005-T03
status: done
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.

Done 2026-08-10: tenant.update, tenant.retire, and tenant.reactivate are distinct flex-auth actions, so policy can permit a metadata edit without permitting a retirement. Authorization runs before the store is touched, so an unauthorized caller cannot probe which tenants exist. 503s are redacted.

One deviation, deliberate: role revocation stays available while retired -- it only reduces privilege, and blocking it would be fail-open.

T04 - Add lifecycle security and compatibility conformance

id: TEN-WP-0005-T04
status: done
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.

Done 2026-08-10: 124 tests pass (was 66). The store-conformance suite is parametrised over both backends so the durable store cannot silently diverge from the reference semantics. All 66 pre-existing tests still pass unchanged; POST /tenants returns a superset of its previous body.

The concurrent-writer test caught a real pre-existing defect: reads on the shared SQLite connection ran unguarded and could observe a row mid-transaction from another thread, producing a spurious tenant_not_found. Reads now take the same lock as writes.

Not covered: no PostgreSQL tests exist, per the T02 note above.

T05 - Integrate and verify the production authority

id: TEN-WP-0005-T05
status: progress
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.

Status 2026-08-10: still open, and it is the only thing between user-engine and USER-WP-0021. Blocked on work outside this repo: the three flex-auth actions must be added to the policy package (until then every lifecycle check correctly resolves to deny), and image build plus rollout need cluster access. The consumer-facing contract is finalized and ready to hand over: docs/tenant-lifecycle-api.md.

Status 2026-08-14: flex-auth reports the seven-action policy live on flex-auth-tenant-engine (@sha256:9320df394a642eff24da8af4a0ee8886a7bb78b0f14d8ee1deeb30ea8eeeaba7, commit e9911eb). Production tenant-engine still runs the TEN-WP-0004 image (@sha256:2249e8c6…85149207); its OpenAPI has no lifecycle routes. Recovered the live manifests into deploy/ and added the fleet CI image workflow so the lifecycle image is built from a forge revision rather than a workstation.