tegwick
bee22db620
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb
177 lines
8.2 KiB
Markdown
177 lines
8.2 KiB
Markdown
---
|
|
id: NK-ADR-0013
|
|
type: architecture-decision-record
|
|
title: "Tenant Onboarding Grouping Taxonomy"
|
|
status: accepted
|
|
owner: net-kingdom
|
|
revision: "2"
|
|
decided: "2026-07-23"
|
|
last_reviewed: "2026-08-22"
|
|
review_interval: 12m
|
|
---
|
|
|
|
# ADR-0013 - Tenant Onboarding Grouping Taxonomy
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-07-23
|
|
**Amended:** 2026-08-22 (current classification versus historical identifier segment)
|
|
**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:<name>`, `tenant:customer:<name>`.
|
|
|
|
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:<grouping>:<name>
|
|
|
|
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
|
|
```
|
|
|
|
The taxonomy has two deliberately different uses:
|
|
|
|
- At creation, the identifier's grouping segment records the tenant's
|
|
onboarding-time classification. The complete identifier is immutable, so
|
|
this segment is historical after creation.
|
|
- The tenant record's `grouping` field records current classification. It may
|
|
change as the entity changes and is authoritative for present-day policy,
|
|
including guardrails and spend ceilings.
|
|
|
|
No consumer may parse the identifier's middle segment and treat it as current
|
|
grouping. Consumers needing current grouping MUST read it from `tenant-engine`.
|
|
Identifier creation still validates the segment against this vocabulary;
|
|
historical does not mean free-form or optional.
|
|
|
|
Grouping is deliberately **orthogonal to capability role**
|
|
(`PLTF`/`IAM`/`VEN`/`CUS`, subsequently ratified by ADR-0014): grouping
|
|
describes *what kind of entity a tenant is and its current onboarding-risk
|
|
classification*; role describes *what it does on the platform*. Both are
|
|
carried as tenant metadata, but never conflated into the immutable 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.
|
|
- Tenant identifiers never change when current grouping changes. The middle
|
|
segment is creation-time history; `tenant-engine` is authoritative for the
|
|
current grouping value.
|
|
- Policy and commercial consumers, including spend-ceiling resolution, MUST
|
|
query `tenant-engine` and MUST NOT derive current grouping by splitting a
|
|
tenant identifier.
|
|
- The capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) remains a separate
|
|
dimension, now ratified by ADR-0014. Role metadata is carried alongside —
|
|
not instead of — current grouping and the historical identifier segment.
|
|
- `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.
|
|
- ADR-0014 and the Tenant Engine Boundary Contract define how capability-role
|
|
metadata is carried alongside grouping.
|
|
- Keep `tenant-engine`'s identifier parser vocabulary-validating for creation
|
|
and lookup compatibility, but do not expose parsed grouping as current
|
|
classification.
|