coulomb/tenant-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Finish TEN-WP-0010: mutable grouping, contract corrected, handoffs sent

Browse source 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-17 22:53:10 +02:00
parent 2e1c4e15e6
commit bdf9f5f643
4 changed files with 108 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

54
docs/tenant-lifecycle-api.md
View file

@ -39,15 +39,60 @@ state — those stay exactly as retirement left them.
## Immutability
`tenant_id`, `identifier`, and `grouping` are immutable. The identifier is the
IAM Profile `tenant` claim value that `key-cape` mints into tokens and
`flex-auth` authorizes against; mutating it would silently invalidate every
issued token that references it.
`tenant_id` and `identifier` are immutable. The identifier is the IAM Profile
`tenant` claim value that `key-cape` mints into tokens and `flex-auth`
authorizes against; mutating it would silently invalidate every issued token
that references it.
Mutable metadata is exactly: `display_name`, `contact_email`. Unknown fields
are rejected by the request schema (`extra: forbid`), so the allow-list is
visible in the OpenAPI document rather than discovered from a 400.
**`grouping` is mutable as of TEN-WP-0010**, but not through `PATCH` — see
below. This document previously said it was immutable; that is no longer true.
---
## Reclassification (`grouping`)
### `POST /tenants/{tenant_id}/grouping`
```http
POST /tenants/t-1/grouping
Idempotency-Key: 4f1c…
If-Match: "1"
{"grouping": "large", "actor": "ops",
"reason": "grew past the band", "correlation_id": "corr-1"}
```
Returns the full tenant record, `ETag`, and `Idempotent-Replay`, like the other
mutations.
**Why this is not a `PATCH` field.** `display_name` and `contact_email` are
cosmetic. `grouping` resolves spend ceilings (see
`tenant-guardrail-policy.md`), so a reclassification moves money. It gets its
own route, its own flex-auth action `tenant.grouping.set`, and its own audit
event `tenant_grouping_changed`, so policy can permit a rename without
permitting a reclassification and the audit trail shows which one happened.
**The identifier's grouping segment is historical.** A tenant created as
`tenant:small:acme` and reclassified to `large` keeps the identifier
`tenant:small:acme` and reports `"grouping": "large"`. The two are *expected*
to diverge.
> **Do not parse grouping out of the identifier.** The segment records the
> grouping at onboarding and is not authoritative afterwards. Read the
> `grouping` field from this API. (ADR-0013 amendment proposed under
> TEN-WP-0010; the identifier itself remains immutable either way.)
| Rule | Behaviour |
|---|---|
| unknown grouping | `400 invalid_grouping` |
| no-op | `400 invalid_update` |
| reserved tenant (`tenant:platform`, `tenant:coulomb`) | `400` — ungrouped by design; they resolve guardrails through the reserved profile |
| retired tenant | `409 invalid_lifecycle_transition` — reactivate first |
---
## Endpoints
@ -163,6 +208,7 @@ thereby granting a retirement:
| `tenant.update` | `tenant` |
| `tenant.retire` | `tenant` |
| `tenant.reactivate` | `tenant` |
| `tenant.grouping.set` | `tenant` |
These sit alongside the existing `tenant.create`, `tenant.role.grant`,
`tenant.role.revoke`, and `tenant.plan.assign` actions in package