docs: finish zone reference hardening workplan

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0291a-1e87-7151-9934-fcbfe3f65eb1
This commit is contained in:
tegwick 2026-08-23 12:35:01 +02:00
parent 4f676e2439
commit 6f667d20c2
10 changed files with 308 additions and 129 deletions

140
SCOPE.md
View file

@ -1,75 +1,76 @@
# 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`.
> The historical argument is `INTENT.md`; completed gates and retirement are
> recorded in `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.
`zone-engine` is the retained reference-conformance repository for NetKingdom
security-zone membership, admission, owner-provenanced control profiles, and
time-boxed exception semantics. It does **not** run an engine or make policy
decisions.
## Current lifecycle
## 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.
`ZONE-WP-0001` delivered and proved the model. `ZONE-WP-0002` hardened the
retained reference boundary. Both are finished with `DoD-Ok`; no runtime is
needed and there is no continuing implementation backlog.
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.
The repository is retained while `security-zones_v0.1` remains `proposed` in
net-kingdom canon, with zone-engine as maintainer of fixtures and reference
tooling. Retention is not service ownership. A future canon lifecycle change,
an owner-requested conformance revision, or evidence that an adopting control
cannot enforce the contract at its existing point are the only normal change
triggers. Archival remains an attended action once the reference artifacts are
durably handed off or no longer needed.
## Capability actually present
This repository contains:
This repository provides:
- 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.
- a non-authoritative pointer and machine-checked lineage record for the
canonical `net-kingdom/canon/standards/security-zones_v0.1.md`;
- an offline resolver for direct declarations and caller-supplied Repo Manager
v1 workload projections;
- explicit `applicable` and `not-applicable` handling, with unresolved facts
remaining `unknown` and no path, repo, reef, actor, or lane inference;
- validation of authoritative identity bindings, zone declarations, review
dates, context floors, and continuity evidence;
- canonical `satisfied`, `unsatisfied`, `unknown`, and `not-applicable` results
with workload references, identity bindings, guarantees, sources, and source
revisions;
- deterministic membership revisions bound to canonicalized identity,
membership, workload reference, and source revision;
- deterministic first/previous-snapshot addition, removal, and change reports;
- optional control projection from an explicit, total, versioned profile that
names policy owner, PEP owner, and policy reference for every row;
- an offline exception checker with an explicit evaluation instant, covering
grant authority, maximum duration, exclusive expiry, overlap, renewal,
wildcard rejection, and durable-authority bounds; and
- reusable manifests, profiles, exception fixtures, evidence, and 29 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`.
The resolver consumes already-located declarations and already-resolved
workload-reference projections. It does not discover a fleet, repair an
ambiguous join, read a live clock, or publish a consumer registry. Its profile
fixture records owner-approved v0.1 behavior; only the referenced owner policy
and PEP configuration can change a live effect.
## 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 |
| Workload identity and requested membership | Workload's responsible repo | Reference-validates supplied facts |
| Managed workload tuple and applicability | Repo Manager / owning catalog | Consumes the explicit projection |
| Zone ids and admission standard | zone-engine model, published by net-kingdom | Maintains conformance fixtures and lineage |
| Canon publication and lifecycle | net-kingdom | Detects change; never promotes by inference |
| Control stance | Owner of the control | Projects only explicit versioned owner data |
| Failure behavior | Owner of the PEP | Records provenance and 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 |
| Exception grant and expiry | Designated control authority and enforcement point | Checks reusable fixtures offline |
The invariant remains: **membership is ours; stance is theirs; the decision
point is neither.** `flex-auth` remains the only PDP for decisions it renders.
@ -79,36 +80,35 @@ point is neither.** `flex-auth` remains the only PDP for decisions it renders.
There is no:
- API, daemon, database, controller, scheduler, watch loop, or reload path;
- synchronous zone lookup in an authorization or enforcement path;
- synchronous 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;
- fleet discovery, reference repair, registry publication, or workload
migration;
- 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.
Exception expiry remains enforced at decision or enforcement time by each
owning control. The offline checker is conformance evidence, not a live
decision point.
## 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.
- Reproducing or extending v0.1 conformance fixtures.
- Checking direct declarations or explicit Repo Manager projections offline.
- Verifying a versioned owner profile is total and fully attributed.
- Testing an owner exception implementation against the lifecycle boundaries.
- Reviewing a net-kingdom canon lifecycle/content change.
- Auditing why no zone-engine runtime exists.
## 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
- Determining the published rule: read net-kingdom canon.
- Asking whether a request is allowed: use `flex-auth` or the owning control.
- Discovering or repairing managed workloads: use Repo Manager and the owning
catalog.
- Granting, applying, or expiring a live 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.
- Placing a workload, routing a network, managing identity/tenancy, or handling
secrets.