zone-engine/SCOPE.md

# SCOPE

> What this repository can do, when it is relevant, and when it is not.
> The argument for its existence is `INTENT.md`; the completed gates and the
> retirement condition are `GOAL.md`.

---

## One-liner

`zone-engine` is the model-owner and reference-conformance repository for
NetKingdom security-zone identity, membership, admission, and time-boxed
exception semantics. It does **not** run an engine or make policy decisions.

## Current lifecycle

The delivery workplan, `ZONE-WP-0001`, is finished and has `DoD-Ok`. All seven
tasks are done. The standard is published in `net-kingdom`, two workload owners
have adopted it, a third repository has read the declarations, ops-warden's
global policy switch is retired, and the no-runtime decision is recorded.

Those facts satisfy `GOAL.md`'s success gates and retirement condition. This
repository is therefore **complete and an archive candidate**, not an active
service backlog. Keeping it writable is useful only while the estate wants a
reference implementation and the evidence history here; canon remains the
published source for consumers.

`ZONE-WP-0002` is a ready follow-up hardening plan. It does not reopen the
runtime decision: it makes canon lineage, reference output, owner provenance,
conformance fixtures, and the final archive-or-retain choice explicit.

## Capability actually present

This repository contains:

- the source model and local draft of `security-zones_v0.1`, including the five
  zone ids, workload authority boundary, admission semantics, and the initial
  owner-qualified control profile;
- the decision record for time-boxed exceptions, including grant authority,
  maximum duration, decision-time expiry, durable-authority bounds, and audit
  requirements;
- estate-partition and adoption evidence showing the model against the real
  inventory and its use by `ops-warden` and `flex-auth`;
- an offline reference resolver, `tools/resolve_zones.py`, which reads one or
  more local `tenancy.yaml`-shaped YAML documents, including single-service and
  `services:` forms;
- validation of direct workload identity bindings, required membership fields,
  review dates, maturity/context floors, and continuity evidence;
- deterministic `satisfied`, `unsatisfied`, or `unknown` admission results,
  with no membership inference; and
- a resolved zone, declaration-content digest, and reference projection of the
  initial control profile, covered by eight unit tests.

The resolver is a **reference and adoption-proof tool**, not a complete
production compiler. In particular, it accepts already-located declarations;
it does not discover the estate or resolve Repo Manager's cross-repository
`(rapp_id, workload_identity.name, deployable?)` references. Its control rows
are a snapshot of the accepted v0.1 profile, not an authority that can override
the versioned policy and PEP configuration owned by `flex-auth` and
`ops-warden`.

## Authority boundary

| Concern | Authority | This repository's role |
| --- | --- | --- |
| Workload identity and requested membership | Workload's responsible repo | Defines and reference-validates the contract |
| Zone ids and admission standard | zone-engine model, published by net-kingdom | Maintains the source model and conformance evidence |
| Canon publication | net-kingdom | Offers source material; does not publish canon |
| Control stance | Owner of the control | Records the vocabulary and an owner-qualified reference profile |
| Failure behavior | Owner of the policy enforcement point | Records semantics only |
| Authorization effect | Existing PDP or control owner | Makes no decision |
| Exception grant and expiry | Control owner's designated authority and enforcement point | Standardizes the lifecycle; stores or evaluates no grant |

The invariant remains: **membership is ours; stance is theirs; the decision
point is neither.** `flex-auth` remains the only PDP for decisions it renders.

## Deliberately absent

There is no:

- API, daemon, database, controller, scheduler, watch loop, or reload path;
- synchronous zone lookup in an authorization or enforcement path;
- central exception store, grant workflow, clock, or expiry evaluator;
- live policy evaluation or implementation of another repository's control;
- fleet discovery, Repo Manager reference resolution, or registry publication;
- network segmentation, reef placement, tenancy, identity, or secrets service;
  or
- authority to publish canon or select a consumer's stance and failure mode.

Exception expiry is enforced at decision or enforcement time by each owning
control. Adding a central runtime without new evidence would cross the decided
authority boundary and introduce an unnecessary availability dependency.

## Relevant when

- Evolving the zone identities, admission rules, or exception-lifecycle
  contract before offering a corresponding canon change to `net-kingdom`.
- Checking a direct `tenancy.yaml` declaration against the v0.1 reference
  admission rules.
- Reproducing the adoption evidence or using the fixtures as a starting point
  for an owner-side implementation.
- Auditing why the estate chose no zone-engine runtime.

## Not relevant when

- Determining the authoritative published rule: read `net-kingdom` canon.
- Asking whether a specific request is allowed: use `flex-auth` or the owning
  control.
- Resolving a managed deployable across repositories: use the Repo Manager
  workload-reference contract and an owning consumer/compiler.
- Granting, applying, or expiring an exception: use the control owner's
  versioned policy or PEP configuration.
- Placing a workload on a substrate: use Repo Manager reefs.
- Making a network-routing, identity, tenancy, or secrets decision.