tenant-engine/history/2026-08-29-security-layer-intent-scope-review.md

# Review: Security Layer Model v0.7 — INTENT, SCOPE, and implementation

**Date:** 2026-08-29
**Author:** grok
**Reviewed:**
- `net-kingdom/SECURITY-COMPANION.md` v0.2 (accepted; start here)
- `net-kingdom/canon/standards/security-layer-model_v0.7.md` (accepted 2026-08-29)
- `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`
- this repo's `INTENT.md` / `SCOPE.md` (before and after this session)
- shipped code under `src/tenant_engine/` and finished workplans `TEN-WP-0001`–`0007`, `0009`, `0010`
**Trigger:** gate-house broadcast that v0.7 is accepted; intake `TEN-IN-0003` asking this repository to declare its layer in its own voice, or contest it. Proposed layer: Engine.
**Outcome:** declared Engine / PIP; contested placing approval lifecycle here; remaining implementation gaps captured as `TEN-WP-0011`.

---

## 1. Executive summary

`tenant-engine` is the catalogued Engine / PIP for tenant-as-an-entity facts. That placement is correct, and this session declares it in `INTENT.md` frontmatter and prose. The gate-house review note that sat above an unadapted body is replaced.

`SCOPE.md` was the larger documentation failure. It still said the repo was bootstrapping with no implementation, while production already serves tenant records, role grants, plan assignment, lifecycle, guardrails, and a PostgreSQL store, gated on writes (and now reads) through `flex-auth`.

The implementation is a working PIP with a fail-closed write path. It is **not** yet a conforming PEP-shaped consumer, and it is **not** yet a conforming evidence source. Those are the evolution requirements.

| Question | Answer |
| --- | --- |
| Is Engine / PIP the right layer? | **Yes.** Same tenant state, same result. Facts as claims, never a decision. |
| Do we contest the proposed layer? | **No.** We contest only the live question about approvals. |
| Do approvals belong here? | **No.** Guardrails are ceilings. Approvals are `approval-engine` objects. |
| Does SCOPE match INTENT? | **After this session, yes** at the documentation layer. |
| Does implementation match INTENT? | **Partial.** PIP reads and fail-closed writes exist. Decision-record persistence, published stance, independent evidence, and claim-lifetime declaration do not. |

---

## 2. What the standard now requires of this repository

Companion v0.2 is the operative form. The statute governs on disagreement.

### 2.1 Declare (companion §2, statute §11)

Machine-readable `layer` in `INTENT.md` frontmatter, plus prose in our own voice. A layer stated *about* us is not a declaration. Engines also carry `role`. Catalog row: Engine / PIP, tenant-as-an-entity facts.

**Before this session:** a gate-house review note named Engine and admitted the body was unadapted. That is exactly the defect §11 now forbids.

**After this session:** `layer: Engine`, `role: PIP` in frontmatter; body rewritten. `TEN-IN-0003` closed by `TEN-DEC-2026-001`.

### 2.2 PIP rules that bind a fact engine

- One decision point: `access-engine` only. We do not render or cache a decision.
- Compiled data that determines an outcome is still deciding. An effective guardrail, a grouping, or a role set is a **claim**. Joining it with consumption to allow or deny is `access-engine`'s.
- Doctrine and tenancy context arrive as claims, never as a side channel.
- Live-lookup unavailability is input degradation at the consumer: fail to reduced authority is `access-engine`'s when it is reachable; our own read path already returns `503` rather than empty roles.

### 2.3 PEP-shaped writes (companion §5, statute §6.4 / §9.3)

Mutating tenant facts is a protected side effect. Being PEP-shaped does not change the layer. Four obligations:

1. No side effect without a decision record naming the request, **or** a recorded application of the published unreachable-engine stance.
2. Do not replay a verdict outside its binding and lifetime.
3. Publish the unreachable-engine stance map, total, no implicit default, tested equal to shipped behaviour, registered in statute §13.1.
4. Reconstructable, bounded by §9.6.

Shipped behaviour is fail-closed (`DefaultDenyWriteAuthorizer` when the URL is unset; `FlexAuthCheckClient.is_allowed()` returns `False` on any non-allow, including transport failure). That is the right stance for this engine. It is **not published**, and the decision envelope is **discarded**.

### 2.4 Evidence (companion §6, statute §9.6)

Local `events` rows share the production database and runtime credential with the facts they attest to (`TEN-IN-0001`). `TenantStore.events()` returns every tenant's event and payload (`TEN-IN-0002`). Grant/revoke *facts* are live PIP input; the *events* are attributive unless a control starts branching on their presence. Completeness must not be claimed. Independent custody is `audit-core`.

### 2.5 Two things not to plan around (companion §10)

Nothing is observed in production. Nothing can be contained automatically. This engine does not acquire actuation, and no workplan here should assume kings-guard is watching tenant mutations in operation.

---

## 3. INTENT success criteria

INTENT is aspirational. These are the properties the mature system must hold.

| # | Criterion | Status | Evidence / gap |
| --- | --- | --- | --- |
| 1 | Canonical owner of tenant-as-an-entity facts | **Met** | Domain + store + APIs; boundary contract |
| 2 | Deterministic Engine (same state → same result) | **Met** | Pure domain + total guardrail resolution |
| 3 | PIP, never PDP | **Met in design** | Reads return facts; writes ask `flex-auth`. Guardrail resolution is a ceiling, not an allow. |
| 4 | Cache-read for `key-cape` | **Shipped** | `GET /tenants/{id}/roles` |
| 5 | Live-lookup for `access-engine`, fail-closed on store loss | **Shipped** | `GET /tenants/{id}/roles/live` → `503` on `StoreUnavailableError` |
| 6 | Writes PEP-shaped, never self-authorized | **Partial** | Authorizer seam exists and fails closed. Decision id is not kept. Stance is unpublished. |
| 7 | Guardrails are PIP ceilings, not entitlements or decisions | **Shipped (policy)** | `TEN-WP-0006`; plan-derived layer is empty until `adaptive-pricing` feeds it |
| 8 | Grouping current vs identifier historical | **Shipped** | `TEN-WP-0010` |
| 9 | Approvals not stored or evaluated here | **Met by absence** | Contested in `TEN-DEC-2026-001` so it stays absent |
| 10 | No catalogued Tooling client | **Met** | No OpenBao / `key-cape` client in `src/` |
| 11 | Evidence independently custodied, bound claimed honestly | **Not met** | Local events only; `events()` unfiltered |
| 12 | Claim freshness / lifetime declared per input class | **Not met** | Relies on token TTL for cache-read; live path has no stated deadline |

**Score: 8 met, 1 partial, 2 not met, 1 met-by-absence.** The two not-met items and the partial are `TEN-WP-0011`.

---

## 4. SCOPE vs INTENT (documentation)

### Before this session

| Topic | INTENT (body) | SCOPE | Drift |
| --- | --- | --- | --- |
| Layer | Review note only; body unadapted | Silent | Non-conforming declaration |
| Guardrails | "Reserved, not yet implemented" | Same | Both stale vs `TEN-WP-0006` |
| Current state | Purpose written as if pre-code | "bootstrapping. No implementation yet" | False |
| Approvals | Unasked | Unasked | Live question from `TEN-IN-0003` unanswered |
| Writes | Gated by `flex-auth` | Same | Neither named the PEP shape |

### After this session

INTENT states the aspirational Engine / PIP role, the PEP-shaped write path, the evidence bound, and the approvals contest. SCOPE states what is shipped, what is not, and points at `TEN-WP-0011` for the rest. They no longer contradict each other. The remaining documentation debt is the **boundary contract** in `net-kingdom`, which still says guardrails are reserved and that this repo is "not a policy enforcement point" — true of decisions, false of the write-path shape.

---

## 5. SCOPE vs implementation (before the rewrite)

The pre-session `SCOPE.md` was not a conservative boundary. It was wrong about the current state.

Shipped and previously in SCOPE as "in scope": tenant records, role grants, plan assignment, cache-read, live-lookup, write API.

Shipped and previously missing from SCOPE, or marked reserved:

- Guardrail read/write API (`GET/PUT/DELETE /tenants/{id}/guardrails…`)
- Lifecycle (`PATCH`, retire, reactivate)
- Mutable grouping (`POST /tenants/{id}/grouping`)
- PostgreSQL production store
- ETag / If-Match / idempotency on lifecycle and guardrail mutations
- Authorized reads (`tenant.read`, `tenant.role.read`, `tenant.role.read.live`, `tenant.guardrail.read`)

Out of SCOPE and correctly absent from the code: identity, PDP, users, pricing terms, payments, secret custody, metering, rate limits, approvals, containment.

---

## 6. Implementation gaps against the accepted model

Prioritized. "Necessity" means the statute or companion requires it of an Engine / PIP with a PEP-shaped write path. "Should" is the companion's working-reference shape or a pre-existing intake the model now makes sharper.

| Prio | Gap | Kind | Why it matters | Track |
| --- | --- | --- | --- | --- |
| P0 | Layer declared only as a review note | Necessity | §11; `TEN-IN-0003` | **Closed this session** (`INTENT.md`, `TEN-DEC-2026-001`) |
| P1 | `FlexAuthCheckClient` discards the decision envelope; no `authorization_decision_id` on events | Necessity | §6.4 obligation 1; boundary-contract Audit Correlation Contract already required this field and the code never stored it | `TEN-WP-0011-T02` |
| P1 | Unreachable-engine stance unpublished | Necessity | §6.4 obligation 3 / companion §5. Fail-closed is correct and already coded; a map that lives only in `is_allowed()` / `DefaultDenyWriteAuthorizer` is not published. Must be tested equal to shipped behaviour and offered to the §13.1 register. | `TEN-WP-0011-T02` |
| P1 | Local events share the fact store's credential boundary | Necessity (honesty now; custody next) | §9.6. Attributive today. A database-credential compromise forges fact and evidence together. Independent custody is `audit-core`. | `TEN-WP-0011-T04` ← `TEN-IN-0001` |
| P1 | `TenantStore.events()` is unfiltered | Necessity | RISK-F-0004 / `TEN-IN-0002`. No HTTP route today, but the production protocol still offers a cross-tenant dump. | `TEN-WP-0011-T05` ← `TEN-IN-0002` |
| P2 | No machine-readable `layer.yaml` / conformance test | Should | Companion §2 working reference. Frontmatter satisfies "a `layer:` key". The check that *no new OpenBao client appeared* still wants a file and a test, including the non-Tooling inventory (Postgres, `flex-auth`, State Hub). | `TEN-WP-0011-T01` |
| P2 | No declared freshness / lifetime for PIP claims | Necessity (PDP-side, we owe the input class) | §9.7: a PDP states a deadline **per input class**. Cache-read is bounded by token TTL (IAM Profile). Live-lookup currently forbids cross-request caching in prose only. We must publish the input-class lifetime so `access-engine` can name it. | `TEN-WP-0011-T03` |
| P2 | Live-lookup re-enters `flex-auth` to authorize the read | Confirm | `GET /roles/live` calls `authorizer.authorize(tenant.role.read.live)` which `POST`s `/v1/check`. If that check itself live-looks up tenant roles, the path is cyclic. Likely saved by a static service-identity rule that does not consume tenant-engine claims — **must be proven**, not assumed. | `TEN-WP-0011-T03` |
| P3 | Boundary contract stale on guardrails and "not a PEP" | Docs / canon | Owned by `net-kingdom`. Request an amendment; do not fork the contract here. | `TEN-WP-0011-T06` |
| P3 | Staged promotion still open | Ops, not layer-model | `TEN-WP-0008`. Silent pin rollbacks. Orthogonal to v0.7; remains the other ready workplan. | `TEN-WP-0008` |
| — | Verdict caching | None found | Each write re-checks. Obligation 2 appears held. T02 should lock it with a test. | `TEN-WP-0011-T02` |
| — | Catalogued Tooling contact | None found | No OpenBao / `key-cape` client. Conforming on §5 if the inventory is declared. | `TEN-WP-0011-T01` |
| — | Production observation / automatic containment | Do not plan | Companion §10. No task here invents either. | — |

---

## 7. Approvals contest (the live question on `TEN-IN-0003`)

gate-house asked whether organizational approval lifecycle belongs nearer tenant governance, given that guardrail/quota policy was once a candidate home before `approval-engine` was seeded.

**Contest: no.**

A guardrail answers *how far this tenant may go before something must stop it*. That is a PIP fact, already modelled, already served to `flex-auth` as a ceiling. An approval answers *whether this act has been granted a durable, authenticated, atomically supersedable object*. Statute §4 and §9.4 assign that object to `approval-engine`. Putting it in `tenant-engine` would either mint a second approval store or turn a ceiling engine into a workflow engine.

If a tenant mutation should require an approval, the shape is: `approval-engine` holds the object; `access-engine` consumes it as a claim on `tenant.*` writes; this engine mutates only after that decision. That is the PEP write path we already owe. It is not a reason to own the object.

Recorded as `TEN-DEC-2026-001`.

---

## 8. What this session changed, and what it did not

Changed:

- `INTENT.md` — own-voice Engine / PIP declaration; body adapted; approvals contested.
- `SCOPE.md` — current state, layer table, guardrails and lifecycle in scope, known gaps named.
- `TEN-DEC-2026-001` — declaration + contest.
- `TEN-IN-0003` — closed, absorbed.
- `TEN-IN-0001` / `TEN-IN-0002` — promoted into `TEN-WP-0011`.
- `TEN-WP-0011` — evolution workplan.

Did not change: runtime code, deploy pin, `tenancy.yaml`, agent-rule files (`architecture.md` still says guardrails are reserved — residual, not this workplan's job unless an agent trips on it). Did not implement `layer.yaml`, decision-id persistence, stance publication, or audit-core emission.

---

## 9. Suggested next action

Execute `TEN-WP-0011` in order: T01 (checkable declaration) → T02 (PEP write path) → T03 (PIP freshness, including the live-lookup re-entry proof) → T04/T05 (evidence) → T06 (contract amendment request). Do not wait on `TEN-WP-0008`; it is a different axis (Railiance staged promotion) and both can run.

Do not add a containment, observation, or approval-object task to this repo on the strength of v0.7.