net-kingdom/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md

id	type	title	status	owner	revision	decided	last_reviewed	review_interval
NK-ADR-0013	architecture-decision-record	Tenant Onboarding Grouping Taxonomy	accepted	net-kingdom	2	2026-07-23	2026-08-22	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:

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.