From 6f667d20c26cd731d5c299940848cc01e9ed2847 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 23 Aug 2026 12:35:01 +0200 Subject: [PATCH] docs: finish zone reference hardening workplan Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0291a-1e87-7151-9934-fcbfe3f65eb1 --- GOAL.md | 15 +- INTENT.md | 42 ++++-- README.md | 41 +++-- SCOPE.md | 140 +++++++++--------- WORK-RECORDS.md | 16 +- ...reference-contract-hardening-2026-08-23.md | 87 +++++++++++ .../2026-08-23-retain-reference-decision.md | 30 ++++ tools/check_zone_exceptions.py | 24 +-- tools/resolve_zones.py | 8 +- ...rence-contract-hardening-and-retirement.md | 34 +++-- 10 files changed, 308 insertions(+), 129 deletions(-) create mode 100644 docs/evidence/reference-contract-hardening-2026-08-23.md create mode 100644 history/2026-08-23-retain-reference-decision.md diff --git a/GOAL.md b/GOAL.md index a4e811f..c13bbc6 100644 --- a/GOAL.md +++ b/GOAL.md @@ -1,7 +1,7 @@ --- repo: zone-engine repo_flavor: project -project_status: active +project_status: complete 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. It does not reopen the no-runtime decision; it makes the retained artifacts 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. diff --git a/INTENT.md b/INTENT.md index 7d76775..f073fc1 100644 --- a/INTENT.md +++ b/INTENT.md @@ -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 > *"This control is enforced **there**, advisory **here**, and relaxed **in this > band until Friday** — and all three of those are written down, reviewable, and > 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 organization is in (`organization_posture`). Every one of those **describes**. 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 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` 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. - **Exceptions that expire without anyone remembering them.** -The last is the reason this is a repo rather than a document. A standing -classification needs no engine — canon plus a declaration file covers it, which -is exactly how tenancy posture works. **A relaxation with an expiry is state**, -and state wants an owner, an audit trail, and something other than good -intentions enforcing the deadline. +The last was the runtime hypothesis. A standing classification needs no engine +— canon plus a declaration file covers it, which is exactly how tenancy posture +works. The implementation proved that exception state can remain with the +control owner when `not_after` is evaluated where the effect occurs. That gives +it an owner, audit trail, and enforced deadline without a central service. ## 5. The line this repo must not cross @@ -102,6 +115,8 @@ point is neither.** ## 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: - 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 would falsify it: -- **The exception lifecycle turns out not to need a runtime.** If reviewed - declarations in git, with expiry evaluated at decision time, are sufficient, - then the honest outcome is a canon standard and no engine — and this repo - should be archived rather than kept for the sake of existing. `GOAL.md` gate 5 - and `ZONE-WP-0001-T04` both hold that door open deliberately. +- **The exception lifecycle turns out not to need a runtime.** This falsifier + triggered. Reviewed owner records plus decision-time expiry are sufficient. + The honest outcome is canon plus offline conformance tooling, not an engine. + Retention is bounded to the proposed-standard reference need in `GOAL.md`. - **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 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 — 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. diff --git a/README.md b/README.md index 27767f4..eb51267 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,36 @@ # zone-engine -Headless authority for **security zones** — named bands of the estate with -different enforcement rigidity, and the lifecycle of time-boxed exceptions to -them. +Offline reference conformance for NetKingdom **security zones**. This repository +validates workload membership and admission, projects only explicit +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 -here, and what happens when it fails?* NetKingdom can already say how exposed a -workload is (environment posture), how ready it is (workload maturity `M0`–`M3`), -and what state the organization is in (`organization_posture`). All three -describe. None decides. +It is not a service or policy decision point. Canon is published by +`net-kingdom`; flex-auth and each enforcement-point owner retain live policy +authority. -`zone-engine` is **not** a policy decision point. `flex-auth` remains the only -PDP; zone membership reaches it by compilation into the registry it already -consumes, never by a synchronous lookup in the decision path. +## Checks + +```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/`. diff --git a/SCOPE.md b/SCOPE.md index 2a7ba58..cf64fc9 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index ce6d82f..9cd40de 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -9,7 +9,7 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | | 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-T02 | 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-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-0002-T01 | todo | — | 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-T03 | todo | — | 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-T05 | todo | — | 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-T07 | 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 | done | — | 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 | done | — | 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 | done | — | 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 | diff --git a/docs/evidence/reference-contract-hardening-2026-08-23.md b/docs/evidence/reference-contract-hardening-2026-08-23.md new file mode 100644 index 0000000..98b9df2 --- /dev/null +++ b/docs/evidence/reference-contract-hardening-2026-08-23.md @@ -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. diff --git a/history/2026-08-23-retain-reference-decision.md b/history/2026-08-23-retain-reference-decision.md new file mode 100644 index 0000000..01bc9f3 --- /dev/null +++ b/history/2026-08-23-retain-reference-decision.md @@ -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. diff --git a/tools/check_zone_exceptions.py b/tools/check_zone_exceptions.py index 471d9d4..3023968 100644 --- a/tools/check_zone_exceptions.py +++ b/tools/check_zone_exceptions.py @@ -12,14 +12,18 @@ from typing import Any, Mapping 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" RECORD_STANDARD = "security-zone-exceptions_v0.1" +ZONE_IDS = frozenset( + { + "z0-experimental", + "z1-operational", + "z2-protected", + "z2-continuity", + "z3-critical", + } +) class ExceptionConformanceError(ValueError): @@ -103,7 +107,7 @@ def _validate_relaxation(record: Mapping[str, Any], errors: list[str]) -> None: "enforced": {"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") else: changed = True @@ -155,10 +159,12 @@ def _record_result( if value is None or value == "" or value == () or value == []: errors.append(f"{key} is required") 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") 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: errors.append("control is absent from the owner exception policy") workloads = record.get("workloads") @@ -226,7 +232,7 @@ def _record_result( ) valid = not errors 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" elif at < before: state = "future" diff --git a/tools/resolve_zones.py b/tools/resolve_zones.py index cf8f387..bb7436c 100644 --- a/tools/resolve_zones.py +++ b/tools/resolve_zones.py @@ -124,9 +124,11 @@ def _validate_identity(service: str, identity: Any) -> dict[str, Any]: _required(binding, key, where) if binding["principal_type"] not in {"service", "agent"}: raise DeclarationError(f"{where}.principal_type must be service or agent") - identity_key = tuple( - str(binding[key]) - for key in ("scheme", "authority", "subject", "principal_type") + identity_key = ( + str(binding["scheme"]), + str(binding["authority"]), + str(binding["subject"]), + str(binding["principal_type"]), ) if identity_key in seen: raise DeclarationError(f"{where} duplicates an identity binding") diff --git a/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md b/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md index 8a9c414..1c4664d 100644 --- a/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md +++ b/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md @@ -4,7 +4,7 @@ type: workplan title: "Harden the reference contract and make retirement decidable" domain: infotech repo: zone-engine -status: active +status: finished owner: zone-engine assignee: codex lane: yellow @@ -29,6 +29,10 @@ quality_dor_at: "2026-08-23" 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." 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 @@ -82,7 +86,7 @@ must arrive before T03 and T07 can be marked done. ```task id: ZONE-WP-0002-T01 -status: progress +status: done priority: high quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -114,7 +118,7 @@ fails against a deliberately altered fixture. ```task id: ZONE-WP-0002-T02 -status: todo +status: done priority: high quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -149,7 +153,7 @@ ownership, reefs, actors, and lane names cannot manufacture membership. ```task id: ZONE-WP-0002-T03 -status: todo +status: done priority: high quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -182,7 +186,7 @@ owners, invalid stance/failure combinations, and unversioned profiles. ```task id: ZONE-WP-0002-T04 -status: todo +status: done priority: medium quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -209,7 +213,7 @@ insensitivity, and correct add/remove/change reports. ```task id: ZONE-WP-0002-T05 -status: todo +status: done priority: medium quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -239,7 +243,7 @@ and durable-expiry cases. ```task id: ZONE-WP-0002-T06 -status: todo +status: done priority: high quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -266,7 +270,7 @@ canon validation passes; `git diff --check` is clean in every changed repo. ```task id: ZONE-WP-0002-T07 -status: todo +status: done priority: medium quality_dor: DoR-Ok quality_dor_at: "2026-08-23" @@ -296,13 +300,13 @@ revisions. ## Acceptance criteria -- [ ] 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. -- [ ] 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. -- [ ] Exception rules have executable offline fixtures without a runtime or live decision path. -- [ ] Existing consumer adoption is replayed with exact revisions and passing tests. -- [ ] Archive versus retained-reference ownership is explicitly decided and recorded. +- [x] Canon lifecycle and local-copy lineage are owner-approved and mechanically checkable. +- [x] The resolver represents direct, managed, `unknown`, `unsatisfied`, and `not-applicable` cases without inference. +- [x] Membership revisions include explicit source revision and snapshot deltas are deterministic. +- [x] Control projection is optional, versioned, total, and owner-provenanced; zone-engine owns no stance. +- [x] Exception rules have executable offline fixtures without a runtime or live decision path. +- [x] Existing consumer adoption is replayed with exact revisions and passing tests. +- [x] Archive versus retained-reference ownership is explicitly decided and recorded. ## Out of scope