docs: reconcile delivered scope with intent
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0291a-1e87-7151-9934-fcbfe3f65eb1
This commit is contained in:
parent
d6e74a55f6
commit
5ce5117506
2 changed files with 189 additions and 130 deletions
212
SCOPE.md
212
SCOPE.md
|
|
@ -1,159 +1,111 @@
|
||||||
# SCOPE
|
# SCOPE
|
||||||
|
|
||||||
> What this repository is about, 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 checkable gates and the
|
> The argument for its existence is `INTENT.md`; the completed gates and the
|
||||||
> retirement condition are `GOAL.md`.
|
> retirement condition are `GOAL.md`.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## One-liner
|
## One-liner
|
||||||
|
|
||||||
Authority for security zones — the bands of enforcement rigidity that scope
|
`zone-engine` is the model-owner and reference-conformance repository for
|
||||||
*where* a control bites, and the lifecycle of time-boxed exceptions that relax
|
NetKingdom security-zone identity, membership, admission, and time-boxed
|
||||||
them during deep refactors without leaving a permanent hole.
|
exception semantics. It does **not** run an engine or make policy decisions.
|
||||||
|
|
||||||
---
|
## Current lifecycle
|
||||||
|
|
||||||
## Why this exists
|
The repository's only 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.
|
||||||
|
|
||||||
Enforcement controls in this estate have been repo-wide booleans. ops-warden's
|
Those facts satisfy `GOAL.md`'s success gates and retirement condition. This
|
||||||
flex-auth pre-sign gate (`policy.enabled` with `fail_closed: true`) was the
|
repository is therefore **complete and an archive candidate**, not an active
|
||||||
first to become flippable, and flipping it would have made flex-auth a hard
|
service backlog. Keeping it writable is useful only while the estate wants a
|
||||||
dependency of every `warden sign` — including the SSH certificates the
|
reference implementation and the evidence history here; canon remains the
|
||||||
ops-bridge tunnels depend on, one of which carries the policy call itself.
|
published source for consumers.
|
||||||
|
|
||||||
Across an estate under continuous deep refactor, uniform enforcement hardens
|
## Capability actually present
|
||||||
exactly the access needed to perform the refactor. The flip was deferred under
|
|
||||||
ops-warden's `ADR-0006` — *enforcement is zone-scoped, never a global flag* —
|
|
||||||
and this repo is what that ADR defers to.
|
|
||||||
|
|
||||||
---
|
This repository contains:
|
||||||
|
|
||||||
## In scope
|
- 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.
|
||||||
|
|
||||||
- **Zone identity and admission standards.** What zones exist, and the standard
|
The resolver is a **reference and adoption-proof tool**, not a complete
|
||||||
a **workload** must meet to be admitted to one. Security policy is about the
|
production compiler. In particular, it accepts already-located declarations;
|
||||||
running workload and whoever answers for it — the repo providing the software
|
it does not discover the estate or resolve Repo Manager's cross-repository
|
||||||
only *suggests*. A zone is a floor a workload qualifies against, not a label
|
`(rapp_id, workload_identity.name, deployable?)` references. Its control rows
|
||||||
applied to it, and it is the `tenancy-posture` Decision 8.2 tier-minimum
|
are a snapshot of the accepted v0.1 profile, not an authority that can override
|
||||||
mechanism rather than a new one.
|
the versioned policy and PEP configuration owned by `flex-auth` and
|
||||||
- **Time-boxed exception lifecycle.** A relaxation with an expiry enforced by
|
`ops-warden`.
|
||||||
something rather than intended, plus the record of who widened what, when,
|
|
||||||
and until when. **This is the task that decides whether this repo needs a
|
|
||||||
runtime at all.**
|
|
||||||
- **The membership declaration**, carried in each repo's `tenancy.yaml` under
|
|
||||||
the reserved top-level `zones:` key, with `tenancy-posture_v0.1` §6 carried
|
|
||||||
over verbatim: *accuracy, not altitude*.
|
|
||||||
- **Drafting the canon standard**, offered to `net-kingdom` for publication in
|
|
||||||
the family of `tenancy-posture_v0.1` and the `*-engine` boundary contracts.
|
|
||||||
- **Naming stance vocabulary** — `enforced` / `advisory` / `exempt` — as
|
|
||||||
something owners express, not as something this repo evaluates.
|
|
||||||
|
|
||||||
## Out of scope
|
## Authority boundary
|
||||||
|
|
||||||
- **Authorization decisions.** `flex-auth` is the PDP and stays the only one.
|
| Concern | Authority | This repository's role |
|
||||||
- **Stance for controls flex-auth decides.** Settled on review: for the
|
|
||||||
pre-sign gate, stance lives in a flex-auth **policy package**, not in
|
|
||||||
compiled membership. flex-auth's decision envelope stamps
|
|
||||||
`matched_policy_version` and `policy_package`, and registry content appears
|
|
||||||
nowhere in that provenance — stance in the registry would let two decisions
|
|
||||||
with the same policy version and the same request differ, with nothing in the
|
|
||||||
audit trail explaining why. **Membership is ours; stance is theirs.**
|
|
||||||
- **The fail-open / fail-closed axis.** Also settled on review: a PDP returns
|
|
||||||
an effect. Fail-open describes what a *policy enforcement point* does when
|
|
||||||
the PDP is unreachable — no decision is rendered, so no compiled data and no
|
|
||||||
policy rule can reach it. The failure-mode axis is modelled PEP-side, by the
|
|
||||||
repo that owns the control.
|
|
||||||
- **`organization_posture`.** Ruled out of the declaration by canon: a
|
|
||||||
fleet-wide, time-varying scalar describing the estate is not a property of a
|
|
||||||
declaring service, and a per-repo copy of a global goes stale in as many
|
|
||||||
places as there are repos. It is an **input** to stance selection, read by
|
|
||||||
the model, never absorbed into it.
|
|
||||||
- **Network segmentation.** "Zone" is overloaded; the routing sense is someone
|
|
||||||
else's word.
|
|
||||||
- **Substrate placement.** Reefs are `repo-manager`'s. That
|
|
||||||
`reef-railiance` is single-node and therefore *caps availability* for
|
|
||||||
everything bound to it is a canon composition defect (`NK-WP-0027`), not a
|
|
||||||
zone problem — and zone-engine is explicitly not blocked on it.
|
|
||||||
- **Identity, secrets, tenancy** — `key-cape`, OpenBao / `secrets-engine`,
|
|
||||||
`tenant-engine`.
|
|
||||||
- **Implementing anyone's controls.** Owners keep them; this model says where
|
|
||||||
they bite.
|
|
||||||
- **Publishing canon.** `net-kingdom` owns canon; `policy-nexus` publishes.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Settled by review (2026-08-19)
|
|
||||||
|
|
||||||
`ZONE-WP-0001` was reviewed by both affected owners before any modelling began.
|
|
||||||
Their answers are binding on this repo and are recorded in the workplan.
|
|
||||||
|
|
||||||
| Question | Answer | Ruled by |
|
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| A new standard, or a seventh axis of `tenancy-posture_v0.1`? | **Separate standard.** The six axes are ladders where higher is stronger and desirable; enforcement stance is not monotone — `ADR-0006` *is* the finding that the top rung is wrong for the SSH lane. And an accurately declared `exempt` as an axis would be conformant *and* exempt: a conformance rule handing out its own exemption. | net-kingdom, Decision 5.6 |
|
| Workload identity and requested membership | Workload's responsible repo | Defines and reference-validates the contract |
|
||||||
| Then where is membership declared? | **`tenancy.yaml`, reserved top-level `zones:` key.** One declaration surface, one review cadence, one validator; two standards, because they have different owners and different conformance semantics. | net-kingdom, Decision 5.6 |
|
| Zone ids and admission standard | zone-engine model, published by net-kingdom | Maintains the source model and conformance evidence |
|
||||||
| Does membership need a flex-auth schema change? | **No.** Resource `metadata` / `labels` / `attributes` are already flattened into the Rego input, so a compiler emitting a zone field is readable today. | flex-auth |
|
| Canon publication | net-kingdom | Offers source material; does not publish canon |
|
||||||
| Is "never synchronously in a decision path" the right invariant? | **No** — that is a latency guarantee, not an authority one. Replaced: identity and membership here, effect in a flex-auth policy package. | flex-auth |
|
| Control stance | Owner of the control | Records the vocabulary and an owner-qualified reference profile |
|
||||||
| Are reefs ours to reconcile? | **No**, and the attempt surfaced a canon defect instead (`NK-WP-0027`). | net-kingdom |
|
| 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 |
|
||||||
|
|
||||||
### Two constraints inherited from that review
|
The invariant remains: **membership is ours; stance is theirs; the decision
|
||||||
|
point is neither.** `flex-auth` remains the only PDP for decisions it renders.
|
||||||
|
|
||||||
- **`trust_zone` already exists inside the PDP, and is dead.**
|
## Deliberately absent
|
||||||
`ops-warden/scripts/build_flex_auth_registry.py` hardcodes
|
|
||||||
`"trust_zone": "platform"` on every ssh-cert resource; it reaches the Rego
|
|
||||||
input and **no policy rule reads it**. This repo's own warning about "zone"
|
|
||||||
being overloaded named network segmentation as the hazard; the live collision
|
|
||||||
is a dormant, plausibly-named field sitting exactly where membership would go.
|
|
||||||
The compiler must resolve it — reuse or rename, deliberately.
|
|
||||||
- **flex-auth has no reload path.** Registry and policy are loaded once at
|
|
||||||
process start from a digest-pinned image. An exception compiled as inert
|
|
||||||
registry data therefore expires only when a human redeploys — expiry by
|
|
||||||
*intention*, which is precisely what the exception lifecycle must not be. An
|
|
||||||
exception carrying `not_after`, evaluated against decision time in policy,
|
|
||||||
does expire on its own: granting costs a redeploy, lapsing is automatic.
|
|
||||||
|
|
||||||
---
|
There is no:
|
||||||
|
|
||||||
## Relationship to what already exists
|
- 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.
|
||||||
|
|
||||||
| Mechanism | Owner | Relationship |
|
Exception expiry is enforced at decision or enforcement time by each owning
|
||||||
| --- | --- | --- |
|
control. Adding a central runtime without new evidence would cross the decided
|
||||||
| `tenancy-posture_v0.1` | net-kingdom canon | Sibling standard and **carrier file**. Structural model: graduated levels, per-repo declaration with evidence and review dates, accuracy over altitude |
|
authority boundary and introduce an unnecessary availability dependency.
|
||||||
| Environment posture + workload maturity `M0`–`M3` | ops-warden (WP-0015) | Candidate membership inputs |
|
|
||||||
| `organization_posture: build` | ops-warden (WP-0029) | An **input** to stance selection. Explicitly not part of the declaration |
|
|
||||||
| Reefs / `bound_reefs` | repo-manager | Separate axis. Their interaction with availability is `NK-WP-0027`, not ours |
|
|
||||||
| Compiled registry snapshot | flex-auth | How membership reaches the PDP — no schema change needed, one name collision to resolve |
|
|
||||||
| Policy package | flex-auth | Where **stance** lives for controls flex-auth decides |
|
|
||||||
| `warden plan` verdicts + `reasons` | ops-warden (WP-0029) | Existing verdict machinery to extend, not parallel |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Current state (2026-08-22)
|
|
||||||
|
|
||||||
`ZONE-WP-0001` is finished. T01–T05 established the model: ownership is
|
|
||||||
confirmed, the estate is partitioned, stance and failure mode are modelled, the
|
|
||||||
exception lifecycle requires **no zone-engine runtime**, and the
|
|
||||||
declaration/compiler contract is drafted. The integrated owner draft is
|
|
||||||
`docs/security-zones_v0.1.md`.
|
|
||||||
|
|
||||||
Net-kingdom Decisions 5.6.1 and 5.6.2 settle the workload boundary. Operational
|
|
||||||
execution units declare authoritative workload identity directly in
|
|
||||||
`tenancy.yaml`; absence resolves to `unknown`, never inference. The standard is
|
|
||||||
published in net-kingdom canon, and T07 proves adoption in ops-warden and
|
|
||||||
flex-auth with zone-engine compiling both declarations. No API, storage, or
|
|
||||||
synchronous lookup has been shipped because the exception lifecycle showed
|
|
||||||
that none is needed.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Relevant when
|
## Relevant when
|
||||||
|
|
||||||
- A control is about to be enabled and "enforced *where*?" has no answer
|
- Evolving the zone identities, admission rules, or exception-lifecycle
|
||||||
- A deep refactor needs relaxed rigidity in a band of the estate, with an expiry
|
contract before offering a corresponding canon change to `net-kingdom`.
|
||||||
- A repo is filling in the `zones:` key of its `tenancy.yaml`
|
- 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
|
## Not relevant when
|
||||||
|
|
||||||
- Asking whether a specific request is allowed → `flex-auth`
|
- Determining the authoritative published rule: read `net-kingdom` canon.
|
||||||
- Placing a workload on a substrate → `repo-manager` reefs
|
- Asking whether a specific request is allowed: use `flex-auth` or the owning
|
||||||
- Anything about network reachability
|
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.
|
||||||
|
|
|
||||||
107
history/2026-08-23-scope-against-intent.md
Normal file
107
history/2026-08-23-scope-against-intent.md
Normal file
|
|
@ -0,0 +1,107 @@
|
||||||
|
# Scope assessment against `INTENT.md` — 2026-08-23
|
||||||
|
|
||||||
|
## Assessment
|
||||||
|
|
||||||
|
There is no open repository work. `ZONE-WP-0001` is the only workplan; it is
|
||||||
|
`finished`, all seven tasks are `done`, and its delivery assessment is
|
||||||
|
`DoD-Ok`. `GOAL.md` marks the project `complete`, and the checked-in work-record
|
||||||
|
index contains no ready or in-progress item.
|
||||||
|
|
||||||
|
The intended outcome was achieved, but the runtime hypothesis was falsified in
|
||||||
|
the useful direction anticipated by `INTENT.md` §7. The repository proved that
|
||||||
|
reviewed declarations plus enforcement-time expiry at the owning control are
|
||||||
|
sufficient. The thing delivered here is therefore a standard source, a partial
|
||||||
|
reference resolver, tests, and evidence—not a running zone engine.
|
||||||
|
|
||||||
|
## Intent-to-outcome map
|
||||||
|
|
||||||
|
| Intent claim or test | Assessment | Evidence / boundary |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| A control can vary by workload zone rather than one repo-wide switch (§§1–2) | Met | The five-zone model and total owner-qualified profiles were adopted; ops-warden retired `policy.enabled` and global `policy.fail_closed`. |
|
||||||
|
| The workload is the policy subject and qualifies against a floor (§3) | Met | Direct `workload_identity` plus `zones:` declarations are validated; missing facts resolve `unknown` without inference. |
|
||||||
|
| Identity, admission, stance, failure mode, and expiring exceptions all have owners (§4) | Met by a distributed contract | zone-engine owns the identity/membership model; control owners own stance; PEP owners own failure behavior; exception expiry runs where the effect occurs. No central runtime is required. |
|
||||||
|
| flex-auth remains the only PDP for its decisions (§5) | Met | zone-engine performs no live lookup or authorization decision. flex-auth owns its versioned policy package. |
|
||||||
|
| Consumers can understand posture without reading this repo (§6) | Met for the adopted path | The standard is in net-kingdom canon, declarations are in owning repos, and decision/verdict evidence belongs to control owners. |
|
||||||
|
| Exception lifecycle needs no runtime (§7 falsifier) | Falsifier triggered | `docs/exception-lifecycle-2026-08-22.md` records decision-time expiry and explicitly rejects a central service. Under the Intent, this makes the repo an archive candidate. |
|
||||||
|
| Zones partition the real estate (§7 falsifier) | Met at model level | The estate study classifies applicable workloads and explicitly represents `unknown` and `not-applicable`; it does not manufacture zones for unresolved inventory. |
|
||||||
|
| Two owners declare and a third reads (§7 falsifier) | Met | ops-warden and flex-auth declare; zone-engine's reference resolver reads both. |
|
||||||
|
| No second decision point appears (§7 falsifier) | Met, with a reference-tool caveat | The local resolver projects an accepted profile for evidence, but cannot render an authorization effect and is not authoritative policy. |
|
||||||
|
| Canon-first direction and conditional runtime (§9) | Met | Canon was published and adoption proven; T04 selected the cheaper no-runtime result. |
|
||||||
|
|
||||||
|
## Gaps and residual boundaries
|
||||||
|
|
||||||
|
These are gaps between the broad language of `INTENT.md`, the full canonical
|
||||||
|
contract, and what this repository itself can execute. They are not open tasks
|
||||||
|
in the completed workplan.
|
||||||
|
|
||||||
|
### 1. Repository name and lifecycle no longer match the delivered shape
|
||||||
|
|
||||||
|
The name `zone-engine` suggests a running service. No engine was needed or
|
||||||
|
shipped. `INTENT.md` §7 says this exact outcome should lead to archival rather
|
||||||
|
than preserving a repository for its own sake. The remaining governance choice
|
||||||
|
is to archive it or deliberately retain it as a clearly named reference and
|
||||||
|
evidence repository. That choice belongs outside the completed implementation
|
||||||
|
workplan.
|
||||||
|
|
||||||
|
### 2. `INTENT.md` is now historical argument, not present-state description
|
||||||
|
|
||||||
|
Phrases such as “NetKingdom cannot say that today,” “the gate ... was
|
||||||
|
deliberately not switched on,” and “a relaxation with an expiry is state”
|
||||||
|
describe the initiating problem and hypothesis. Adoption has since made the
|
||||||
|
sentence sayable, retired the global switch, and shown that state can live in
|
||||||
|
versioned owner policy with expiry evaluated at the enforcement point.
|
||||||
|
`SCOPE.md`, not those present-tense passages, must be used for current
|
||||||
|
capability.
|
||||||
|
|
||||||
|
### 3. The checked-in resolver implements only part of the resolved-view contract
|
||||||
|
|
||||||
|
The reference resolver validates direct declaration files and emits an
|
||||||
|
admission result. It does not:
|
||||||
|
|
||||||
|
- resolve Repo Manager's managed-workload tuple or emit applicability and
|
||||||
|
`workload_ref` results;
|
||||||
|
- discover declarations or join a fleet catalog;
|
||||||
|
- include source revision in `membership_revision` (the digest covers the
|
||||||
|
workload identity and `zones:` content);
|
||||||
|
- report membership changes against a preceding snapshot;
|
||||||
|
- emit the full authority/provenance fields illustrated by the standard, such
|
||||||
|
as identity binding, policy owner, PEP owner, and policy reference; or
|
||||||
|
- represent active exception ids and expiry in its output.
|
||||||
|
|
||||||
|
Consequently it is sufficient for the recorded direct-declaration adoption
|
||||||
|
proof, but must not be presented as the complete compiler described by the
|
||||||
|
canonical standard.
|
||||||
|
|
||||||
|
### 4. The local standard is a source snapshot, not canon
|
||||||
|
|
||||||
|
`docs/security-zones_v0.1.md` remains marked `status: draft` even though the
|
||||||
|
standard has been published and subsequently updated in `net-kingdom`. The
|
||||||
|
published copy is authoritative. Maintaining two independently editable copies
|
||||||
|
creates drift risk; an archived repository avoids that risk, while a retained
|
||||||
|
reference repository needs an explicit canon-sync policy.
|
||||||
|
|
||||||
|
### 5. The reference control profile could be mistaken for local stance authority
|
||||||
|
|
||||||
|
`tools/resolve_zones.py` embeds the initial flex-auth and ops-warden control
|
||||||
|
rows and emits them without policy-package provenance. This was adequate to
|
||||||
|
prove the v0.1 adoption profile, but the owning policy packages and PEP
|
||||||
|
configuration remain authoritative. Any future profile change must happen at
|
||||||
|
those owners and in canon; changing this table alone must never change a live
|
||||||
|
effect.
|
||||||
|
|
||||||
|
### 6. Estate-wide completeness remains consumer migration work
|
||||||
|
|
||||||
|
The model can represent resolved workloads, `unknown`, and `not-applicable`,
|
||||||
|
but this repository does not make every catalog entry resolvable. Pre-rapp
|
||||||
|
deployables and missing owner references remain migration debt in the owning
|
||||||
|
catalogs and workloads. That does not require a zone-engine runtime and is not
|
||||||
|
unclosed work in this repository.
|
||||||
|
|
||||||
|
## Recommendation
|
||||||
|
|
||||||
|
Treat `zone-engine` as complete and make no new runtime workplan. Prefer
|
||||||
|
archival once its history/evidence value is accepted elsewhere. If it is kept,
|
||||||
|
retain it explicitly as a reference-conformance repository, make net-kingdom
|
||||||
|
canon the only consumer-facing authority, and open future work only for a
|
||||||
|
concrete canon revision or a demonstrated adopting-control need that cannot be
|
||||||
|
met at its existing enforcement point.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue