# SCOPE

> Lightweight boundary for agents and contributors. Full contract:
> `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`.

---

## One-liner

Canonical owner of tenant-as-an-entity facts for NetKingdom: existence,
onboarding grouping, capability roles, and plan/subscription assignment.

---

## Core Idea

`tenant-engine` answers "what is this tenant, what can it do, and what plan
is it on" for two consumers: `key-cape` (cached, at token issuance) and
`flex-auth` (live, for high-stakes decisions). It never stores users,
issues tokens, or makes authorization decisions.

---

## In Scope

- Tenant records: identifier, onboarding grouping (ADR-0013).
- Capability role grants/revocations: `PLTF`/`IAM`/`VEN`/`CUS` (ADR-0014),
  audited, mostly plan-linked.
- Plan/subscription assignment, referenced by `adaptive-pricing` plan id.
- Cache-read API for `key-cape` (token-issuance-time `tenant_roles` claim
  source).
- Live-lookup API for `flex-auth` (high-stakes, `aal2`-class decisions).
- Write API for grant/revoke/plan mutations, authorization-gated by
  `flex-auth`.
- Reserved, not yet implemented: guardrail/quota policy (spend limits,
  entity/action counts).

## Out of Scope

- Identity, authentication, MFA, token issuance — `key-cape`/Keycloak.
- Authorization decisions — `flex-auth` is the PDP; `tenant-engine` is a
  data source it queries, never the other way around.
- Users, profiles, memberships — `user-engine`. `tenant_id` is the only key
  shared between the two services.
- Pricing-model / plan term definitions — `adaptive-pricing`.
- Payment processing — not yet identified as owned by any repo.
- Runtime secret custody — OpenBao / `secrets-engine`.
- Irreversible operational decisions without human approval.

## Current State

- Status: bootstrapping. No implementation yet — see
  `workplans/TEN-WP-0001-statehub-bootstrap.md` and the first real
  implementation workplan it seeds.
- Ownership contract (`tenant-engine-boundary-contract_v0.1.md`) and the two
  governing ADRs (0013, 0014) are ratified in `net-kingdom` and predate this
  repo's code, by design.

## Getting Oriented

- Start with: `INTENT.md`
- Ownership contract: `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`
- Claim/carrying mechanism: `net-kingdom/canon/standards/iam-profile_v0.3.md`
- flex-auth write-authorization integration: `docs/flex-auth-integration.md`
- Agent instructions: `AGENTS.md`, `CLAUDE.md`
- Workplans: `workplans/`