---
id: TEN-WP-0006
type: workplan
title: "Guardrail and quota policy for tenants"
domain: infotech
repo: tenant-engine
status: ready
owner: claude
topic_slug: tenant-guardrails
created: "2026-08-16"
updated: "2026-08-16"
depends_on:
  - TEN-WP-0005
unblocks: []
state_hub_workstream_id: "bddb6699-cb53-472a-9757-a3ed0eb0ce27"
---

# TEN-WP-0006 - Guardrail and quota policy

Implement the guardrail/quota concern that `SCOPE.md`, `INTENT.md`, and
`.claude/rules/architecture.md` have reserved since the repo was created but
never built. `tenant-engine` owns *policy* — what a tenant is permitted to
spend and how many entities/actions it may hold — not metering, not billing,
and not the enforcement decision itself.

The concrete hole this closes: ADR-0013 specifies that `trial`-grouped tenants
default to a **zero** spend budget. No such default exists today, so every
trial tenant currently carries no ceiling at all.

## Boundary constraints

These are not negotiable without a new ADR, and every task below is bound by
them:

- **`tenant-engine` is a data source, never a PDP.** It answers "what is this
  tenant's limit" and "what is its recorded consumption". `flex-auth` decides
  whether an action is allowed. Never invert this.
- **No metering.** Consumption counters are written *to* this service by
  whoever meters; `tenant-engine` does not observe spend or count actions
  itself.
- **No plan terms.** A guardrail may be *derived from* an `adaptive-pricing`
  plan id, but plan definitions are never copied here.
- **Fail closed.** An unknown tenant, an unreadable store, or a missing
  guardrail resolves to the most restrictive answer, never to "unlimited".

## T01 - Specify the guardrail model and its boundary

```task
id: TEN-WP-0006-T01
status: done
priority: high
state_hub_task_id: "b0693ec3-b3a7-48fb-9f4f-baeedb488e9d"
```

Write the guardrail domain contract before any code. Decide and document:

- The **limit kinds** in scope. Start with spend budget (a currency amount
  over a period) and entity/action counts; leave rate limiting out unless it
  falls out for free.
- **Precedence.** A tenant may inherit a limit from its grouping (ADR-0013),
  from its assigned plan, and from an explicit per-tenant override. Define the
  resolution order and make it total — every tenant resolves to exactly one
  effective guardrail set, with no ambiguity and no "unset means unlimited".
- **The `trial` = zero-spend default**, and what the default is for each other
  grouping. An unmapped grouping must resolve restrictively, not openly.
- **Reserved identifiers.** `tenant:platform` and `tenant:coulomb` are
  ungrouped (see `domain.py`); state explicitly what they resolve to.
- Whether consumption lives in this repo at all. If it does, it is an opaque
  counter written by an external meter, with the writer named in the contract.

Document the consumer-facing shape in `docs/tenant-guardrail-policy.md`,
matching the style of `docs/tenant-lifecycle-api.md`.

Done when the precedence rules are unambiguous, the fail-closed default is
explicit for every grouping, and the doc states plainly what this service does
*not* do (meter, bill, decide).

Done 2026-08-16: `docs/tenant-guardrail-policy.md`. Decisions worth carrying:

- **Limit kinds:** `spend` (integer minor units + ISO-4217, never floats),
  `entity_count`, `action_count`. Rate limiting stays out — it is a gateway
  concern with different latency and storage needs, not a free by-product.
- **Registry, not open keys.** A limit key must be registered to resolve; an
  unregistered key errors (`unknown_limit_key`) rather than resolving to zero
  or unlimited. Zero would break a caller who merely misspelled a key;
  unlimited would fail open. Startup validation requires a default for every
  grouping, so an unmapped grouping cannot reach production.
- **Precedence, per key:** override → plan → grouping → fail-closed floor. Per
  key, not per set, so a plan supplying `spend.monthly` does not wipe out a
  grouping-derived `entity.*`. The floor is only reachable if the registry is
  internally inconsistent, and reports provenance `fail_closed` so that state
  is visible rather than mistaken for policy.
- **`unlimited` is an explicit sentinel**, never a default and never the result
  of absence. The rule is "no unset means unlimited" — that bans *inferring* an
  open ceiling, not deliberately declaring one.
- **Reserved identifiers** get a `reserved` profile at layer 3 rather than
  falling through: spend 0 (infrastructure identities are not billable
  spenders), counts explicitly unlimited. Falling through would clamp the
  platform's own identity to zero and take the platform down with it.
- **Lifecycle clamp** applies after resolution and may only reduce; `retired`
  clamps every limit to the floor while leaving reads working.
- **Consumption does not live in this repo.** tenant-engine is a low-write
  policy authority with audit and CAS semantics; consumption is high-frequency
  telemetry with opposite needs, and holding it here would drag metering into a
  service `SCOPE.md` disowns it from. Reads return limits plus provenance only.

Two things flagged rather than settled: the non-`trial` grouping ceilings are
conservative opening values needing product sign-off (only `trial` = 0 is
canon), and **no repo owns metering** — the same gap `SCOPE.md` records for
payment processing. Until canon names one, `flex-auth` can enforce
ceiling-presence semantics but not consumption-relative ones. A zero budget is
fully enforceable with no meter at all, which is why the ADR-0013 `trial`
default lands immediately.

## T02 - Implement the guardrail domain model

```task
id: TEN-WP-0006-T02
status: todo
priority: high
state_hub_task_id: "1b28d836-11d9-4ef3-967b-05bfa74c304a"
```

Add a `guardrail/` module (the namespace `architecture.md` reserves) holding
pure domain types with no framework dependency, mirroring how `domain.py` is
structured: frozen dataclasses, validation that raises typed errors, and
resolution logic as a pure function over (grouping, plan_id, overrides).

Guardrail changes are **audited like role grants** — append-only, carrying
actor, reason, and correlation id. A limit change is a privilege change and
must be as reconstructible as a `RoleGrant`.

Done when effective-guardrail resolution is a total, side-effect-free function
with unit tests covering every grouping, the reserved identifiers, missing
plans, and conflicting overrides.

## T03 - Persist guardrails in both stores

```task
id: TEN-WP-0006-T03
status: todo
priority: high
state_hub_task_id: "f1c93573-6322-4505-b738-7d66d67e60a8"
```

Extend the `TenantStore` Protocol and both implementations (`InMemoryTenantStore`
and the SQLite store) with guardrail persistence and its audit trail. Follow the
precedent set by `mutate_tenant()` in TEN-WP-0005: the mutation, the audit
event, and any idempotency receipt commit **in one transaction** — a crash must
never leave a changed limit with no audit record.

Add a forward-only, idempotent migration that backfills existing tenants with
their grouping-derived defaults. Existing tenants must not silently gain a
looser limit than a fresh tenant of the same grouping would get.

Interaction with lifecycle: decide and test what a `retired` tenant's
guardrails resolve to. Follow the TEN-WP-0005 precedent — operations that only
*reduce* privilege stay available while retired; loosening does not.

Done when the store-conformance suite (already parametrised over both backends)
covers guardrails, so the durable store cannot diverge from the reference
semantics.

## T04 - Expose guardrail read and write APIs

```task
id: TEN-WP-0006-T04
status: todo
priority: high
state_hub_task_id: "4a256517-2773-4679-ad57-2909f22ac8a4"
```

Add the API surface, authorized through the existing flex-auth `WriteAuthorizer`
with **distinct actions** so policy can permit reading a limit without
permitting a change to it — the same split TEN-WP-0005 used for
`tenant.update` / `tenant.retire` / `tenant.reactivate`:

- a read returning a tenant's effective guardrails plus their provenance
  (which layer each limit came from), for `flex-auth` to consume;
- a write to set or clear a per-tenant override, requiring `Idempotency-Key`,
  `If-Match`, actor, reason, and correlation id, consistent with the lifecycle
  mutation contract.

Authorization runs **before** the store is touched, so an unauthorized caller
cannot probe which tenants exist. Errors are redacted: never reflect policy
internals or store paths in `detail`.

New flex-auth actions mean a policy-package change outside this repo. Name the
required actions explicitly in the task record so the flex-auth side is a
tracked handoff and not a surprise — this is exactly what stalled
TEN-WP-0005-T05.

Done when the routes are authorized, versioned, idempotent, correlated, and
provider-neutral, and the OpenAPI document makes the semantics unambiguous.

## T05 - Conformance and consumer handoff

```task
id: TEN-WP-0006-T05
status: todo
priority: medium
state_hub_task_id: "92036fa3-9031-4b42-a67e-93196e236e08"
```

Cover: every grouping's default, `trial` resolving to zero spend, precedence
between grouping/plan/override, unmapped grouping failing closed, reserved
identifiers, guardrail reads on a retired tenant, stale-version conflict,
idempotent replay, cross-tenant authorization denial, store outage, and error
redaction. Prove the existing create/role/plan/lifecycle clients are unaffected.

Then write the consumer handoff for `flex-auth` — the guardrail read is only
useful once a PDP consults it — naming the API version, the authorization
actions, and the contract doc, in the table format TEN-WP-0005-T05 used.

**Do not** deploy to production as part of this workplan. Cluster rollout is a
separate, human-authorized step; see the note below.

Done when the full suite passes and the handoff is sent.

## Out of scope / explicitly deferred

- **Production rollout.** Image build and cluster apply need credentials and a
  human authorization decision. Track separately.
- **The live flex-auth regression** (`flex-auth-tenant-engine` rolled back to
  the four-action image, so `tenant.update` / `tenant.retire` /
  `tenant.reactivate` currently deny with `unknown_action`). Unrelated to this
  workplan, but it means any *new* actions from T04 land on a policy package
  that is already behind. Resolve the regression before shipping T04's actions.
- **Metering and billing.** Not this repo, at any point.