From a18f83c4aff8e80a99125d3c76be73e150686cf4 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 23 Jul 2026 16:01:55 +0200 Subject: [PATCH] ADR-0013: tenant onboarding grouping taxonomy, orthogonal to capability role Replaces the sandbox/customer suggested tenant identifiers in iam-profile_v0.2.md's Tenant Claim section with an onboarding-risk/ entity-shape grouping (trial, friendly, single, small, medium, large, enterprise, consumer, family, community, association, agentic) that stays orthogonal to the separate, still-unratified capability-role model (PLTF/IAM/VEN/CUS) a tenant can also hold. Role words as a grouping would collide the moment a tenant's roles evolve -- Binky Hedgehog GmbH is CUS now and VEN later, so tenant:customer:binky was already the wrong shape. First application: tenant:friendly:binky (key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md). tenant:platform and tenant:coulomb proposed as reserved/ungrouped, flagged for explicit confirmation. Classified as an editorial change per ADR-0011's governance (no required-claim schema change) -- the iam-profile_v0.2.md Tenant Claim section edit itself is tracked as a follow-up, not bundled here. Co-Authored-By: Claude Sonnet 5 --- ...013-tenant-onboarding-grouping-taxonomy.md | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md diff --git a/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md b/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md new file mode 100644 index 0000000..1c8ceb1 --- /dev/null +++ b/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md @@ -0,0 +1,143 @@ +# ADR-0013 - Tenant Onboarding Grouping Taxonomy + +**Status:** Accepted +**Date:** 2026-07-23 +**Deciders:** Bernd Worsch, Codex + +## Context + +`canon/standards/iam-profile_v0.2.md`'s "Tenant Claim" section lists four +*suggested* (not exhaustive) tenant identifiers: `tenant:platform`, +`tenant:coulomb`, `tenant:sandbox:`, `tenant:customer:`. + +Separately, an unratified exploration +(`docs/princedom-isolation-exploration.md`) proposes a non-exclusive +**capability-role** model for tenants: `PLTF` (operates the platform), +`IAM` (organizes its own users/secrets), `VEN` (provides apps/services to +others), `CUS` (consumes apps/services from `PLTF` or `VEN` tenants) — one +tenant can hold multiple roles simultaneously. + +Binky Hedgehog GmbH is being onboarded as the platform's first tenant +outside `tenant:coulomb` (`key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md`), +forcing a concrete identifier decision. Binky already exercises both `CUS` +(consumes `qonto-assistant`) and, per `binky-control/INTENT.md`, will exercise +`VEN` (packages and sells offers built on the ecosystem to real external +customers) — it is not purely a "customer" in the role sense. + +Using a capability-role word (`customer`, `vendor`, ...) as the tenant +*grouping* segment collides with that separate role dimension: a tenant +labeled `tenant:customer:binky` would carry a stale, misleading label the +moment it also starts acting as a vendor, and tenant identifiers are +expensive to rename once tokens, OpenBao paths, and downstream config +reference them. + +## Decision + +Adopt an onboarding-risk / entity-shape **grouping** taxonomy for the tenant +identifier's second segment, replacing the `sandbox`/`customer` suggested +identifiers in `iam-profile_v0.2.md`'s "Tenant Claim" section: + +```text +tenant:: + +trial - test/trial/showcase tenants only +friendly - known, easily reached, tolerant of experimentation/instability +single - one-person business entities (freelance consultants) +small - up to 10 employees at time of onboarding (attoo) +medium - up to 100 employees (attoo) +large - up to 1000 employees (attoo) +enterprise - 1001+ employees (attoo) +consumer - private individuals +family - a legal family +community - a non-legal group of people +association - a legal association of people +agentic - financially enabled AI entities +``` + +This grouping is deliberately **orthogonal to capability role** +(`PLTF`/`IAM`/`VEN`/`CUS`, still unratified): the grouping describes *what +kind of entity a tenant is and how it was onboarded*; role describes *what +it does on the platform*. Both may need to be carried as tenant metadata, +but never conflated into one identifier segment — that conflation is exactly +what this ADR avoids. + +`tenant:platform` and `tenant:coulomb` remain **reserved, ungrouped +identifiers outside this taxonomy**: `tenant:platform` is the control-plane +root, not a business entity being onboarded; `tenant:coulomb` is the +reference tenant established by ADR-0006, predating this taxonomy, and none +of the twelve groupings meaningfully describe "the platform building +itself." The taxonomy applies to tenants onboarded from here forward. +*(This sub-point completes an open question raised during KEY-WP-0004 +drafting and is Codex's reasoned proposal — flagged for Bernd's explicit +confirmation rather than assumed settled.)* + +First application: Binky Hedgehog GmbH maps to `friendly` — known, +reachable, tolerant of early instability — giving **`tenant:friendly:binky`** +(`key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md`). + +## Scope and Governance Classification + +Per ADR-0011's breaking-change governance, this does **not** meet the +breaking-change bar: it doesn't add, remove, or rename a required claim; it +doesn't change `tenant`'s type or validation rule (still an opaque string); +it doesn't affect acceptance of any previously-issued token +(`tenant:platform`, `tenant:coulomb` tokens remain valid as-is, and no +`tenant:customer:*` or `tenant:sandbox:*` tokens have been issued yet). It +only replaces non-normative suggested-identifier guidance for tenants +onboarded going forward. + +Per ADR-0011's own versioning rule ("New versions are added as new files... +except for clearly editorial fixes that do not affect semantics"), this +qualifies as an **editorial update** to `iam-profile_v0.2.md`'s Tenant Claim +section — not a new versioned profile document. + +## Consequences + +- `canon/standards/iam-profile_v0.2.md`'s "Tenant Claim" section needs a + follow-up edit replacing the `sandbox`/`customer` suggested identifiers + with this taxonomy. Not made by this ADR itself — tracked as follow-up so + the change is reviewable on its own. +- `key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md` + already reflects this decision (`tenant:friendly:binky`). +- Future tenant onboarding work should classify a tenant against this list + before minting an identifier, rather than reaching for a role word. +- The capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) remains a separate, + still-unratified dimension; this ADR does not ratify that model, only + avoids colliding with it. If/when it is ratified, role metadata should be + carried alongside — not instead of — the grouping segment decided here. +- `tenant:platform` and `tenant:coulomb` are reserved outside the taxonomy, + pending Bernd's explicit confirmation (see Decision). + +## Alternatives Considered + +### Keep using capability-role words as the tenant grouping + +Rejected: tenants are already known to hold multiple roles at once (Binky is +`CUS` now, `VEN` later); a role-word grouping would need renaming as a +tenant's roles evolve, which tenant identifiers are specifically expensive +to do once tokens, OpenBao paths, and config reference them. + +### Retrofit `tenant:coulomb` into the new taxonomy + +Considered `tenant:friendly:coulomb` or similar. Rejected for now: Coulomb +is structurally the reference tenant from ADR-0006, predating this taxonomy, +and none of the twelve entity-shape groupings describe "the platform's own +ecosystem-development tenant." Revisit if a future grouping is ever added +that genuinely fits it. + +### Do nothing / keep the four original suggested identifiers + +Rejected: `tenant:customer:binky` was the working default going into Binky's +onboarding despite the role-collision problem above; the fleet needs this +resolved before the first non-Coulomb tenant goes live, not after. + +## Follow-Up + +- Edit `canon/standards/iam-profile_v0.2.md`'s Tenant Claim section to + replace the old suggested identifiers with this taxonomy (separate, + reviewable change). +- Confirm the `tenant:platform`/`tenant:coulomb` reserved/ungrouped + treatment explicitly. +- If/when the `PLTF`/`IAM`/`VEN`/`CUS` capability-role model is ratified, + define how role metadata is carried alongside the grouping segment + decided here.