coulomb/zone-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: finish zone reference hardening workplan

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

15
GOAL.md
View file

@ -1,7 +1,7 @@
--- ---
repo: zone-engine repo: zone-engine
repo_flavor: project repo_flavor: project
project_status: active project_status: complete
started: "2026-08-19" started: "2026-08-19"
--- ---
@ -63,3 +63,16 @@ runtime exists with an owner or the decision that none is needed is recorded.
`ZONE-WP-0002` is the final reference-contract hardening and retirement pass. `ZONE-WP-0002` is the final reference-contract hardening and retirement pass.
It does not reopen the no-runtime decision; it makes the retained artifacts It does not reopen the no-runtime decision; it makes the retained artifacts
truthful enough for an explicit archive-or-maintain decision. truthful enough for an explicit archive-or-maintain decision.
## Retirement decision — 2026-08-23
Retain the repository as an offline reference-conformance repository while the
canonical v0.1 standard remains `proposed`. The maintainer is zone-engine; the
maintenance surface is limited to canon lineage, conformance fixtures, and
concrete owner-driven revisions. There is no service or routine delivery
backlog.
Reassess archival when net-kingdom accepts or supersedes v0.1, when the fixtures
are durably adopted by canon/control owners, or when no adopting control needs
the reference. An actual Forgejo archive or rename remains attended operator
work.

42
INTENT.md
View file

@ -6,13 +6,25 @@
--- ---
## Current disposition — 2026-08-23
The argument below is retained as design history. Its desired sentence is now
sayable: the standard is in net-kingdom canon, ops-warden and flex-auth have
adopted it, the repo-wide switch is retired, and exception expiry is enforced
at each owning decision or enforcement point.
The runtime hypothesis was falsified. zone-engine is retained only as an
offline reference-conformance repository while canon v0.1 remains proposed; it
is not an engine, PDP, exception service, or consumer policy owner. Current
capability is `SCOPE.md`, and the retain/archive triggers are in `GOAL.md`.
## 1. The sentence this repo exists to make sayable ## 1. The sentence this repo exists to make sayable
> *"This control is enforced **there**, advisory **here**, and relaxed **in this > *"This control is enforced **there**, advisory **here**, and relaxed **in this
> band until Friday** — and all three of those are written down, reviewable, and > band until Friday** — and all three of those are written down, reviewable, and
> expire on their own."* > expire on their own."*
NetKingdom cannot say that today. It can say how exposed a workload is At inception NetKingdom could not say that. It could say how exposed a workload was
(environment posture), how ready it is (`M0`–`M3`), and what state the (environment posture), how ready it is (`M0`–`M3`), and what state the
organization is in (`organization_posture`). Every one of those **describes**. organization is in (`organization_posture`). Every one of those **describes**.
None of them **decides**. So every enforcement control in the estate has been a None of them **decides**. So every enforcement control in the estate has been a
@ -21,7 +33,8 @@ boolean over a whole repo.
## 2. Where that bit ## 2. Where that bit
ops-warden built a pre-sign authorization gate, flex-auth enforced its side, and ops-warden built a pre-sign authorization gate, flex-auth enforced its side, and
the gate verified clean. Then it was deliberately not switched on. the gate verified clean. It was deliberately not switched on until the zone
model replaced its global scope.
`policy.enabled` is one boolean over the entire repo. With `fail_closed: true` `policy.enabled` is one boolean over the entire repo. With `fail_closed: true`
it makes flex-auth a hard dependency of *every* `warden sign` — including the it makes flex-auth a hard dependency of *every* `warden sign` — including the
@ -74,11 +87,11 @@ it decides something, so the model must carry:
the bite is; `fail_closed` is what turns a dead tunnel into an outage. the bite is; `fail_closed` is what turns a dead tunnel into an outage.
- **Exceptions that expire without anyone remembering them.** - **Exceptions that expire without anyone remembering them.**
The last is the reason this is a repo rather than a document. A standing The last was the runtime hypothesis. A standing classification needs no engine
classification needs no engine — canon plus a declaration file covers it, which — canon plus a declaration file covers it, which is exactly how tenancy posture
is exactly how tenancy posture works. **A relaxation with an expiry is state**, works. The implementation proved that exception state can remain with the
and state wants an owner, an audit trail, and something other than good control owner when `not_after` is evaluated where the effect occurs. That gives
intentions enforcing the deadline. it an owner, audit trail, and enforced deadline without a central service.
## 5. The line this repo must not cross ## 5. The line this repo must not cross
@ -102,6 +115,8 @@ point is neither.**
## 6. What success looks like from outside ## 6. What success looks like from outside
These conditions are now met for the adopted v0.1 path:
Someone who has never read this repo should be able to: Someone who has never read this repo should be able to:
- open a service's `tenancy.yaml`, read its `zones:` key, and know which - open a service's `tenancy.yaml`, read its `zones:` key, and know which
@ -120,11 +135,10 @@ failed at being a standard and has succeeded only at being a service.
Stated up front, because a repo created on a recommendation should say what Stated up front, because a repo created on a recommendation should say what
would falsify it: would falsify it:
- **The exception lifecycle turns out not to need a runtime.** If reviewed - **The exception lifecycle turns out not to need a runtime.** This falsifier
declarations in git, with expiry evaluated at decision time, are sufficient, triggered. Reviewed owner records plus decision-time expiry are sufficient.
then the honest outcome is a canon standard and no engine — and this repo The honest outcome is canon plus offline conformance tooling, not an engine.
should be archived rather than kept for the sake of existing. `GOAL.md` gate 5 Retention is bounded to the proposed-standard reference need in `GOAL.md`.
and `ZONE-WP-0001-T04` both hold that door open deliberately.
- **The zones do not partition the real estate.** If the model needs a residue - **The zones do not partition the real estate.** If the model needs a residue
of special cases to cover today's 27 routing lanes and actor inventory, it is of special cases to cover today's 27 routing lanes and actor inventory, it is
describing an aspiration, not a structure. describing an aspiration, not a structure.
@ -152,3 +166,7 @@ called adopted, the first being ops-warden retiring `policy.enabled`.
A runtime only if `ZONE-WP-0001-T04` proves the exception lifecycle needs one — A runtime only if `ZONE-WP-0001-T04` proves the exception lifecycle needs one —
and the cheaper answer is a legitimate result, not a disappointment. and the cheaper answer is a legitimate result, not a disappointment.
That direction is delivered. `ZONE-WP-0002` hardened the offline contracts and
made canon lineage, owner provenance, revision/delta evidence, and exception
fixtures executable without reopening the runtime decision.

41
README.md
View file

@ -1,17 +1,36 @@
# zone-engine # zone-engine
Headless authority for **security zones** — named bands of the estate with Offline reference conformance for NetKingdom **security zones**. This repository
different enforcement rigidity, and the lifecycle of time-boxed exceptions to validates workload membership and admission, projects only explicit
them. owner-versioned control profiles, checks time-boxed exception fixtures, and
verifies the lineage of the canonical standard.
A zone answers a question no existing axis answers: *is this control enforced It is not a service or policy decision point. Canon is published by
here, and what happens when it fails?* NetKingdom can already say how exposed a `net-kingdom`; flex-auth and each enforcement-point owner retain live policy
workload is (environment posture), how ready it is (workload maturity `M0`–`M3`), authority.
and what state the organization is in (`organization_posture`). All three
describe. None decides.
`zone-engine` is **not** a policy decision point. `flex-auth` remains the only ## Checks
PDP; zone membership reaches it by compilation into the registry it already
consumes, never by a synchronous lookup in the decision path. ```bash
make check
make canon-lineage CANON_ROOT=/path/to/net-kingdom
```
Resolve the versioned reference manifest and optional owner profile:
```bash
python3 tools/resolve_zones.py \
--manifest fixtures/manifests/reference.yaml \
--control-profile profiles/netkingdom-build-v0.1.yaml
```
Evaluate exception conformance at an explicit instant:
```bash
python3 tools/check_zone_exceptions.py \
fixtures/exceptions/valid-active.yaml \
--policy fixtures/exceptions/policy.yaml \
--at 2026-08-23T10:00:00Z
```
Orient: `GOAL.md` → `SCOPE.md` → `workplans/`. Orient: `GOAL.md` → `SCOPE.md` → `workplans/`.

140
SCOPE.md
View file

@ -1,75 +1,76 @@
# SCOPE # SCOPE
> What this repository can do, when it is relevant, and when it is not. > 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 > The historical argument is `INTENT.md`; completed gates and retirement are
> retirement condition are `GOAL.md`. > recorded in `GOAL.md`.
--- ---
## One-liner ## One-liner
`zone-engine` is the model-owner and reference-conformance repository for `zone-engine` is the retained reference-conformance repository for NetKingdom
NetKingdom security-zone identity, membership, admission, and time-boxed security-zone membership, admission, owner-provenanced control profiles, and
exception semantics. It does **not** run an engine or make policy decisions. 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 `ZONE-WP-0001` delivered and proved the model. `ZONE-WP-0002` hardened the
tasks are done. The standard is published in `net-kingdom`, two workload owners retained reference boundary. Both are finished with `DoD-Ok`; no runtime is
have adopted it, a third repository has read the declarations, ops-warden's needed and there is no continuing implementation backlog.
global policy switch is retired, and the no-runtime decision is recorded.
Those facts satisfy `GOAL.md`'s success gates and retirement condition. This The repository is retained while `security-zones_v0.1` remains `proposed` in
repository is therefore **complete and an archive candidate**, not an active net-kingdom canon, with zone-engine as maintainer of fixtures and reference
service backlog. Keeping it writable is useful only while the estate wants a tooling. Retention is not service ownership. A future canon lifecycle change,
reference implementation and the evidence history here; canon remains the an owner-requested conformance revision, or evidence that an adopting control
published source for consumers. cannot enforce the contract at its existing point are the only normal change
triggers. Archival remains an attended action once the reference artifacts are
`ZONE-WP-0002` is a ready follow-up hardening plan. It does not reopen the durably handed off or no longer needed.
runtime decision: it makes canon lineage, reference output, owner provenance,
conformance fixtures, and the final archive-or-retain choice explicit.
## Capability actually present ## Capability actually present
This repository contains: This repository provides:
- the source model and local draft of `security-zones_v0.1`, including the five - a non-authoritative pointer and machine-checked lineage record for the
zone ids, workload authority boundary, admission semantics, and the initial canonical `net-kingdom/canon/standards/security-zones_v0.1.md`;
owner-qualified control profile; - an offline resolver for direct declarations and caller-supplied Repo Manager
- the decision record for time-boxed exceptions, including grant authority, v1 workload projections;
maximum duration, decision-time expiry, durable-authority bounds, and audit - explicit `applicable` and `not-applicable` handling, with unresolved facts
requirements; remaining `unknown` and no path, repo, reef, actor, or lane inference;
- estate-partition and adoption evidence showing the model against the real - validation of authoritative identity bindings, zone declarations, review
inventory and its use by `ops-warden` and `flex-auth`; dates, context floors, and continuity evidence;
- an offline reference resolver, `tools/resolve_zones.py`, which reads one or - canonical `satisfied`, `unsatisfied`, `unknown`, and `not-applicable` results
more local `tenancy.yaml`-shaped YAML documents, including single-service and with workload references, identity bindings, guarantees, sources, and source
`services:` forms; revisions;
- validation of direct workload identity bindings, required membership fields, - deterministic membership revisions bound to canonicalized identity,
review dates, maturity/context floors, and continuity evidence; membership, workload reference, and source revision;
- deterministic `satisfied`, `unsatisfied`, or `unknown` admission results, - deterministic first/previous-snapshot addition, removal, and change reports;
with no membership inference; and - optional control projection from an explicit, total, versioned profile that
- a resolved zone, declaration-content digest, and reference projection of the names policy owner, PEP owner, and policy reference for every row;
initial control profile, covered by eight unit tests. - 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 The resolver consumes already-located declarations and already-resolved
production compiler. In particular, it accepts already-located declarations; workload-reference projections. It does not discover a fleet, repair an
it does not discover the estate or resolve Repo Manager's cross-repository ambiguous join, read a live clock, or publish a consumer registry. Its profile
`(rapp_id, workload_identity.name, deployable?)` references. Its control rows fixture records owner-approved v0.1 behavior; only the referenced owner policy
are a snapshot of the accepted v0.1 profile, not an authority that can override and PEP configuration can change a live effect.
the versioned policy and PEP configuration owned by `flex-auth` and
`ops-warden`.
## Authority boundary ## Authority boundary
| Concern | Authority | This repository's role | | Concern | Authority | This repository's role |
| --- | --- | --- | | --- | --- | --- |
| Workload identity and requested membership | Workload's responsible repo | Defines and reference-validates the contract | | Workload identity and requested membership | Workload's responsible repo | Reference-validates supplied facts |
| Zone ids and admission standard | zone-engine model, published by net-kingdom | Maintains the source model and conformance evidence | | Managed workload tuple and applicability | Repo Manager / owning catalog | Consumes the explicit projection |
| Canon publication | net-kingdom | Offers source material; does not publish canon | | Zone ids and admission standard | zone-engine model, published by net-kingdom | Maintains conformance fixtures and lineage |
| Control stance | Owner of the control | Records the vocabulary and an owner-qualified reference profile | | Canon publication and lifecycle | net-kingdom | Detects change; never promotes by inference |
| Failure behavior | Owner of the policy enforcement point | Records semantics only | | 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 | | 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 The invariant remains: **membership is ours; stance is theirs; the decision
point is neither.** `flex-auth` remains the only PDP for decisions it renders. 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: There is no:
- API, daemon, database, controller, scheduler, watch loop, or reload path; - 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; - central exception store, grant workflow, clock, or expiry evaluator;
- live policy evaluation or implementation of another repository's control; - 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; - network segmentation, reef placement, tenancy, identity, or secrets service;
or or
- authority to publish canon or select a consumer's stance and failure mode. - 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 Exception expiry remains enforced at decision or enforcement time by each
control. Adding a central runtime without new evidence would cross the decided owning control. The offline checker is conformance evidence, not a live
authority boundary and introduce an unnecessary availability dependency. decision point.
## Relevant when ## Relevant when
- Evolving the zone identities, admission rules, or exception-lifecycle - Reproducing or extending v0.1 conformance fixtures.
contract before offering a corresponding canon change to `net-kingdom`. - Checking direct declarations or explicit Repo Manager projections offline.
- Checking a direct `tenancy.yaml` declaration against the v0.1 reference - Verifying a versioned owner profile is total and fully attributed.
admission rules. - Testing an owner exception implementation against the lifecycle boundaries.
- Reproducing the adoption evidence or using the fixtures as a starting point - Reviewing a net-kingdom canon lifecycle/content change.
for an owner-side implementation. - Auditing why no zone-engine runtime exists.
- Auditing why the estate chose no zone-engine runtime.
## Not relevant when ## Not relevant when
- Determining the authoritative published rule: read `net-kingdom` canon. - Determining the published rule: read net-kingdom canon.
- Asking whether a specific request is allowed: use `flex-auth` or the owning - Asking whether a request is allowed: use `flex-auth` or the owning control.
control. - Discovering or repairing managed workloads: use Repo Manager and the owning
- Resolving a managed deployable across repositories: use the Repo Manager catalog.
workload-reference contract and an owning consumer/compiler. - Granting, applying, or expiring a live exception: use the control owner's
- Granting, applying, or expiring an exception: use the control owner's
versioned policy or PEP configuration. versioned policy or PEP configuration.
- Placing a workload on a substrate: use Repo Manager reefs. - Placing a workload, routing a network, managing identity/tenancy, or handling
- Making a network-routing, identity, tenancy, or secrets decision. secrets.

16
WORK-RECORDS.md
View file

@ -9,7 +9,7 @@
| Kind | ID | Status | Lane | Source | | Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| workplan | ZONE-WP-0001 | finished | — | workplans/ZONE-WP-0001-security-zone-model.md | | workplan | ZONE-WP-0001 | finished | — | workplans/ZONE-WP-0001-security-zone-model.md |
| workplan | ZONE-WP-0002 | ready | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | workplan | ZONE-WP-0002 | finished | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0001-T01 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T01 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
| task | ZONE-WP-0001-T02 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T02 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
| task | ZONE-WP-0001-T03 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T03 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
@ -17,10 +17,10 @@
| task | ZONE-WP-0001-T05 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T05 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
| task | ZONE-WP-0001-T06 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T06 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
| task | ZONE-WP-0001-T07 | done | — | workplans/ZONE-WP-0001-security-zone-model.md | | task | ZONE-WP-0001-T07 | done | — | workplans/ZONE-WP-0001-security-zone-model.md |
| task | ZONE-WP-0002-T01 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T01 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T02 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T02 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T03 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T03 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T04 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T04 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T05 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T05 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T06 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T06 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |
| task | ZONE-WP-0002-T07 | todo | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md | | task | ZONE-WP-0002-T07 | done | — | workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md |

87
docs/evidence/reference-contract-hardening-2026-08-23.md Normal file
View file

@ -0,0 +1,87 @@
# Reference-contract hardening evidence — 2026-08-23
`ZONE-WP-0002` closes the executable gaps without creating a zone-engine
runtime.
## Revisions reviewed
| Repository | Revision | Role |
| --- | --- | --- |
| zone-engine | `be29c28` | Reference resolver, profile/exception fixtures, lineage checker, and tests |
| net-kingdom | `3491c29` checkout; canonical artifact last changed at `104d5c6` | Canon publication and lifecycle |
| repo-manager | `7b9fdaa` | RMGR-ADR-004 v1 workload-reference authority |
| flex-auth | `00a7bc4`; profile owner baseline `e521e7b` | Adopted declaration and pre-sign stance |
| ops-warden | `c8fa02a`; profile/PEP baseline `7ce58ae` | Adopted declaration, failure modes, and consumer registry |
No owner repository was changed by this workplan.
## Canon lineage
`make canon-lineage CANON_ROOT=/home/worsch/net-kingdom` passed. Both the
reviewed `104d5c6` artifact and current checkout hash to
`32e71e9c0d6946bb14099eb66193822da26f199de0e11d8488464207f3bd9906`
and report lifecycle `proposed`. A mutation fixture proves content drift fails;
a separate fixture proves lifecycle drift fails.
The local standard text is no longer a second normative copy. It is a pointer
to canon with a machine-readable lineage record.
## Resolved-view replay
`fixtures/manifests/adoption.yaml` resolved the two live declarations and one
native catalog subject:
| Subject | Result | Effective zone | Membership revision |
| --- | --- | --- | --- |
| flex-auth | `satisfied` | `z1-operational` | `sha256:841d3a251ca9f9fb5eb263b4fd90b557cb06de031ec3be06034c5e011039c16c` |
| ops-warden | `satisfied` | `z1-operational` | `sha256:0407d7a90e7f259163a0e1ec0907551a06ad7023a100261b911dcde62899bd5b` |
| human-operator | `not-applicable` | none | none |
The reference manifest also proves the managed Repo Manager tuple
`(rapp-fixture, fixture-workload, fixture-workload)`. Direct and managed
bindings, source revisions, guarantees, `unknown`, `unsatisfied`, and
`not-applicable` are explicit. Paths, repository ownership, reefs, actors, and
lane names cannot manufacture membership.
Snapshot tests prove deterministic additions, removals, changes, source
revision sensitivity, and order insensitivity. A missing source revision emits
no digest and no source-bound guarantee.
## Profile authority
Core membership resolution emits no controls. Projection requires
`profiles/netkingdom-build-v0.1.yaml`, whose version pins the previously
accepted owner revisions. Every row includes policy owner, PEP owner, and
policy reference, and the profile is total over all five zones plus `unknown`.
Fixtures reject missing coverage, ownerless/unqualified controls, invalid
stance/failure combinations, and unversioned profiles. Profile failure leaves
the independently resolved membership record intact and marks the overall
projection unsuccessful.
## Exception lifecycle
The offline checker evaluates only a supplied document, owner policy, and
explicit instant. It validates designated grant authority, exact workload and
zone scope, maximum duration, exclusive `not_after`, strict relaxation,
renewal ids, overlap, wildcard/unknown rejection, and durable-authority expiry.
Invalid or unevaluable records are inactive. It stores nothing, grants nothing,
reads no live clock, and is absent from every decision path.
## Verification
- zone-engine: `make check` — 29 tests passed; reference and exception fixture
commands passed, including expected rejection of the overlap fixture.
- canon lineage: passed at net-kingdom `104d5c6` and current checkout.
- flex-auth: `go test ./...` passed.
- ops-warden: 390 tests passed, 4 integration tests deselected; Ruff passed.
- net-kingdom tenancy validator: flex-auth and ops-warden declarations valid.
- repository whitespace checks passed.
## Outcome
The repository is safe to retain as a bounded reference and safe to archive
after handoff. The selected non-destructive disposition is retain while canon
v0.1 remains proposed, with only owner-driven conformance and lineage changes
permitted. No runtime, live policy authority, or estate-migration backlog was
created.

30
history/2026-08-23-retain-reference-decision.md Normal file
View file

@ -0,0 +1,30 @@
# Retain the offline reference repository — 2026-08-23
**Decision:** retain `zone-engine` as an offline reference-conformance
repository while `security-zones_v0.1` remains proposed in net-kingdom canon.
**Authority:** zone-engine owner under the operator-directed execution of
`ZONE-WP-0002`; canon and control ownership remain unchanged.
## Maintenance contract
- Maintainer: zone-engine.
- Authoritative standard: net-kingdom canon, never the local pointer.
- Allowed changes: canon-lineage refresh, conformance fixtures, and a concrete
revision requested by canon or an adopting control owner.
- Forbidden expansion: runtime/API/storage, live policy decisions, implicit
workload discovery, central exception enforcement, or local stance authority.
- Routine backlog: none.
## Archive triggers
Reassess archival when any of the following is true:
1. net-kingdom accepts or supersedes v0.1 and owns the durable conformance
assets;
2. the adopting control owners absorb the fixtures and no shared reference is
needed; or
3. no adopting control depends on this reference surface.
Archiving or renaming the Forgejo repository remains an attended operator
action. This decision deliberately performs neither.

24
tools/check_zone_exceptions.py
View file

@ -12,14 +12,18 @@ from typing import Any, Mapping
import yaml import yaml
try:
from tools.resolve_zones import ZONE_FLOOR
except ModuleNotFoundError: # direct ``python tools/...`` execution
from resolve_zones import ZONE_FLOOR
POLICY_STANDARD = "security-zone-exception-policy_v0.1" POLICY_STANDARD = "security-zone-exception-policy_v0.1"
RECORD_STANDARD = "security-zone-exceptions_v0.1" RECORD_STANDARD = "security-zone-exceptions_v0.1"
ZONE_IDS = frozenset(
{
"z0-experimental",
"z1-operational",
"z2-protected",
"z2-continuity",
"z3-critical",
}
)
class ExceptionConformanceError(ValueError): class ExceptionConformanceError(ValueError):
@ -103,7 +107,7 @@ def _validate_relaxation(record: Mapping[str, Any], errors: list[str]) -> None:
"enforced": {"advisory", "exempt"}, "enforced": {"advisory", "exempt"},
"advisory": {"exempt"}, "advisory": {"exempt"},
} }
if relaxed_stance not in allowed.get(base_stance, set()): if relaxed_stance not in allowed.get(str(base_stance), set()):
errors.append("relaxation.stance must strictly relax the base stance") errors.append("relaxation.stance must strictly relax the base stance")
else: else:
changed = True changed = True
@ -155,10 +159,12 @@ def _record_result(
if value is None or value == "" or value == () or value == []: if value is None or value == "" or value == () or value == []:
errors.append(f"{key} is required") errors.append(f"{key} is required")
zone = record.get("security_zone") zone = record.get("security_zone")
if zone not in ZONE_FLOOR: if zone not in ZONE_IDS:
errors.append("security_zone must be a named zone") errors.append("security_zone must be a named zone")
control_id = record.get("control") control_id = record.get("control")
control_policy = policy["controls"].get(control_id) control_policy = (
policy["controls"].get(str(control_id)) if control_id is not None else None
)
if control_policy is None: if control_policy is None:
errors.append("control is absent from the owner exception policy") errors.append("control is absent from the owner exception policy")
workloads = record.get("workloads") workloads = record.get("workloads")
@ -226,7 +232,7 @@ def _record_result(
) )
valid = not errors valid = not errors
active = bool(valid and before and after and before <= at < after) active = bool(valid and before and after and before <= at < after)
if not valid: if not valid or before is None or after is None:
state = "invalid" state = "invalid"
elif at < before: elif at < before:
state = "future" state = "future"

8
tools/resolve_zones.py
View file

@ -124,9 +124,11 @@ def _validate_identity(service: str, identity: Any) -> dict[str, Any]:
_required(binding, key, where) _required(binding, key, where)
if binding["principal_type"] not in {"service", "agent"}: if binding["principal_type"] not in {"service", "agent"}:
raise DeclarationError(f"{where}.principal_type must be service or agent") raise DeclarationError(f"{where}.principal_type must be service or agent")
identity_key = tuple( identity_key = (
str(binding[key]) str(binding["scheme"]),
for key in ("scheme", "authority", "subject", "principal_type") str(binding["authority"]),
str(binding["subject"]),
str(binding["principal_type"]),
) )
if identity_key in seen: if identity_key in seen:
raise DeclarationError(f"{where} duplicates an identity binding") raise DeclarationError(f"{where} duplicates an identity binding")

34
workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md
View file

@ -4,7 +4,7 @@ type: workplan
title: "Harden the reference contract and make retirement decidable" title: "Harden the reference contract and make retirement decidable"
domain: infotech domain: infotech
repo: zone-engine repo: zone-engine
status: active status: finished
owner: zone-engine owner: zone-engine
assignee: codex assignee: codex
lane: yellow lane: yellow
@ -29,6 +29,10 @@ quality_dor_at: "2026-08-23"
quality_dor_by: codex quality_dor_by: codex
quality_dor_note: "The gaps are evidenced against the implementation and canon; scope, owners, dependencies, verification, and stop conditions are explicit." quality_dor_note: "The gaps are evidenced against the implementation and canon; scope, owners, dependencies, verification, and stop conditions are explicit."
state_hub_workstream_id: "c349aa5c-d7fd-5c48-83aa-422cc42b9c67" state_hub_workstream_id: "c349aa5c-d7fd-5c48-83aa-422cc42b9c67"
quality_dod: DoD-Ok
quality_dod_at: "2026-08-23"
quality_dod_by: codex
quality_dod_note: "Canon lineage is pinned and checked; the resolver covers authoritative workload references, source-bound revisions, deterministic deltas, and optional owner-provenanced profiles; exception fixtures are executable; owner/canon suites pass; and the bounded retain decision is recorded."
--- ---
# ZONE-WP-0002 — Harden the reference contract and make retirement decidable # ZONE-WP-0002 — Harden the reference contract and make retirement decidable
@ -82,7 +86,7 @@ must arrive before T03 and T07 can be marked done.
```task ```task
id: ZONE-WP-0002-T01 id: ZONE-WP-0002-T01
status: progress status: done
priority: high priority: high
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -114,7 +118,7 @@ fails against a deliberately altered fixture.
```task ```task
id: ZONE-WP-0002-T02 id: ZONE-WP-0002-T02
status: todo status: done
priority: high priority: high
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -149,7 +153,7 @@ ownership, reefs, actors, and lane names cannot manufacture membership.
```task ```task
id: ZONE-WP-0002-T03 id: ZONE-WP-0002-T03
status: todo status: done
priority: high priority: high
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -182,7 +186,7 @@ owners, invalid stance/failure combinations, and unversioned profiles.
```task ```task
id: ZONE-WP-0002-T04 id: ZONE-WP-0002-T04
status: todo status: done
priority: medium priority: medium
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -209,7 +213,7 @@ insensitivity, and correct add/remove/change reports.
```task ```task
id: ZONE-WP-0002-T05 id: ZONE-WP-0002-T05
status: todo status: done
priority: medium priority: medium
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -239,7 +243,7 @@ and durable-expiry cases.
```task ```task
id: ZONE-WP-0002-T06 id: ZONE-WP-0002-T06
status: todo status: done
priority: high priority: high
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -266,7 +270,7 @@ canon validation passes; `git diff --check` is clean in every changed repo.
```task ```task
id: ZONE-WP-0002-T07 id: ZONE-WP-0002-T07
status: todo status: done
priority: medium priority: medium
quality_dor: DoR-Ok quality_dor: DoR-Ok
quality_dor_at: "2026-08-23" quality_dor_at: "2026-08-23"
@ -296,13 +300,13 @@ revisions.
## Acceptance criteria ## Acceptance criteria
- [ ] Canon lifecycle and local-copy lineage are owner-approved and mechanically checkable. - [x] Canon lifecycle and local-copy lineage are owner-approved and mechanically checkable.
- [ ] The resolver represents direct, managed, `unknown`, `unsatisfied`, and `not-applicable` cases without inference. - [x] The resolver represents direct, managed, `unknown`, `unsatisfied`, and `not-applicable` cases without inference.
- [ ] Membership revisions include explicit source revision and snapshot deltas are deterministic. - [x] Membership revisions include explicit source revision and snapshot deltas are deterministic.
- [ ] Control projection is optional, versioned, total, and owner-provenanced; zone-engine owns no stance. - [x] Control projection is optional, versioned, total, and owner-provenanced; zone-engine owns no stance.
- [ ] Exception rules have executable offline fixtures without a runtime or live decision path. - [x] Exception rules have executable offline fixtures without a runtime or live decision path.
- [ ] Existing consumer adoption is replayed with exact revisions and passing tests. - [x] Existing consumer adoption is replayed with exact revisions and passing tests.
- [ ] Archive versus retained-reference ownership is explicitly decided and recorded. - [x] Archive versus retained-reference ownership is explicitly decided and recorded.
## Out of scope ## Out of scope