docs: plan zone reference contract hardening
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0291a-1e87-7151-9934-fcbfe3f65eb1
This commit is contained in:
parent
5ce5117506
commit
1a20bd6ba2
3 changed files with 334 additions and 5 deletions
13
SCOPE.md
13
SCOPE.md
|
|
@ -14,11 +14,10 @@ exception semantics. It does **not** run an engine or make policy decisions.
|
|||
|
||||
## Current lifecycle
|
||||
|
||||
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.
|
||||
The delivery workplan, `ZONE-WP-0001`, is finished and has `DoD-Ok`. All seven
|
||||
tasks are done. The standard is published in `net-kingdom`, two workload owners
|
||||
have adopted it, a third repository has read the declarations, ops-warden's
|
||||
global policy switch is retired, and the no-runtime decision is recorded.
|
||||
|
||||
Those facts satisfy `GOAL.md`'s success gates and retirement condition. This
|
||||
repository is therefore **complete and an archive candidate**, not an active
|
||||
|
|
@ -26,6 +25,10 @@ service backlog. Keeping it writable is useful only while the estate wants a
|
|||
reference implementation and the evidence history here; canon remains the
|
||||
published source for consumers.
|
||||
|
||||
`ZONE-WP-0002` is a ready follow-up hardening plan. It does not reopen the
|
||||
runtime decision: it makes canon lineage, reference output, owner provenance,
|
||||
conformance fixtures, and the final archive-or-retain choice explicit.
|
||||
|
||||
## Capability actually present
|
||||
|
||||
This repository contains:
|
||||
|
|
|
|||
|
|
@ -9,6 +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 |
|
||||
| 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 |
|
||||
|
|
@ -16,3 +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 |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,318 @@
|
|||
---
|
||||
id: ZONE-WP-0002
|
||||
type: workplan
|
||||
title: "Harden the reference contract and make retirement decidable"
|
||||
domain: infotech
|
||||
repo: zone-engine
|
||||
status: ready
|
||||
owner: zone-engine
|
||||
assignee: codex
|
||||
lane: yellow
|
||||
topic_slug: netkingdom
|
||||
planning_priority: P1
|
||||
created: "2026-08-23"
|
||||
updated: "2026-08-23"
|
||||
reviewed_at: "2026-08-23"
|
||||
reviewed_by: codex
|
||||
reviewed_against_commit: "5ce5117"
|
||||
origin: "history/2026-08-23-scope-against-intent.md"
|
||||
context_paths:
|
||||
- "GOAL.md"
|
||||
- "INTENT.md"
|
||||
- "SCOPE.md"
|
||||
- "docs/security-zones_v0.1.md"
|
||||
- "docs/exception-lifecycle-2026-08-22.md"
|
||||
- "tools/resolve_zones.py"
|
||||
- "tests/test_resolve_zones.py"
|
||||
quality_dor: DoR-Ok
|
||||
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."
|
||||
---
|
||||
|
||||
# ZONE-WP-0002 — Harden the reference contract and make retirement decidable
|
||||
|
||||
## Goal
|
||||
|
||||
Make the repository safe to retain as a reference and safe to archive when its
|
||||
handoff is complete. Close the places where the checked-in resolver and local
|
||||
standard can overstate their authority or fall short of the canonical resolved
|
||||
view: canon lineage, workload-reference applicability, source-bound revisions,
|
||||
change observability, control-profile provenance, and exception conformance.
|
||||
|
||||
The workplan does **not** revive the rejected runtime. It leaves live decisions,
|
||||
control stance, failure behavior, exception grants, and exception expiry with
|
||||
their existing owners.
|
||||
|
||||
## Why these gaps are the relevant ones
|
||||
|
||||
| Priority | Gap | Why address it here |
|
||||
| --- | --- | --- |
|
||||
| P0 | Canon is authoritative but remains `status: proposed`; the local copy remains `status: draft` | Two independently editable normative-looking copies create lifecycle and drift ambiguity |
|
||||
| P0 | The resolver embeds an unversioned control profile | It can look like zone-engine owns stance, contrary to the load-bearing authority invariant |
|
||||
| P1 | The resolver omits the Repo Manager applicability/reference projection and full provenance | Its output is narrower than the canonical resolved-view contract and cannot distinguish `unknown` from explicit `not-applicable` inputs |
|
||||
| P1 | Membership revisions omit source revision and there is no previous-snapshot delta | The standard promises source-bound identity and observable membership changes |
|
||||
| P1 | Exception semantics have prose but no executable conformance fixtures | A reference repository should prove expiry and invalid-record rules without becoming the live evaluator |
|
||||
| P1 | Archive versus retained-reference ownership is not decided | The no-runtime falsifier fired; indefinite accidental maintenance is not an acceptable default |
|
||||
|
||||
Estate-wide reference migration is intentionally excluded. Missing rapp
|
||||
references and unresolved catalog entries belong to their workload and catalog
|
||||
owners. This repo will consume an authoritative projection; it will not discover
|
||||
the fleet or infer a join.
|
||||
|
||||
## Authority and dependencies
|
||||
|
||||
- **net-kingdom** owns canon publication and must rule on the canonical
|
||||
standard's lifecycle state and the durable source/mirror policy.
|
||||
- **repo-manager** owns the v1 workload-reference tuple. This plan consumes
|
||||
RMGR-ADR-004 as-is and requests no placement or discovery authority.
|
||||
- **flex-auth** owns its policy profile; **ops-warden** owns its controls and
|
||||
PEP failure modes. They review profile provenance and the integration replay.
|
||||
- **zone-engine** owns the reference resolver, conformance fixtures, local
|
||||
evidence, and the final retirement recommendation.
|
||||
- **Operator action** is required only for an actual Forgejo archive/rename or
|
||||
for accepting a continuing maintenance owner. Implementation can proceed
|
||||
through the archive-readiness evidence before that decision.
|
||||
|
||||
No dependency blocks T01 or the local contract work. External owner responses
|
||||
must arrive before T03 and T07 can be marked done.
|
||||
|
||||
## Tasks
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T01
|
||||
status: todo
|
||||
priority: high
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Settle canon lifecycle and eliminate the duplicate-authority shape
|
||||
|
||||
Take the current state to `net-kingdom`: the canonical file is present and its
|
||||
adoption gates say complete, but its frontmatter is `status: proposed`, while
|
||||
the local source remains `status: draft`. Obtain and record the canon owner's
|
||||
ruling on:
|
||||
|
||||
1. the correct canonical lifecycle state;
|
||||
2. whether this repository keeps a marked non-authoritative source snapshot,
|
||||
a verified mirror, or only a canonical pointer; and
|
||||
3. how source revision and content identity are checked when canon changes.
|
||||
|
||||
Implement the ruling in this repository and offer the corresponding canon
|
||||
change to `net-kingdom`. A local normative-looking copy must not silently drift.
|
||||
|
||||
**Done when:** canon ownership and lifecycle are explicit; the local artifact
|
||||
cannot be mistaken for publication; a repeatable check detects lineage/content
|
||||
drift; and the owner ruling plus exact revisions are recorded under `history/`.
|
||||
|
||||
**Verify:** the lineage check passes against the reviewed canon checkout and
|
||||
fails against a deliberately altered fixture.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T02
|
||||
status: todo
|
||||
priority: high
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Bring membership resolution up to the canonical workload-reference boundary
|
||||
|
||||
Define and implement a versioned offline input contract that accepts:
|
||||
|
||||
- a direct authoritative workload declaration; or
|
||||
- Repo Manager's already-resolved
|
||||
`(rapp_id, workload_identity.name, deployable?)` projection with explicit
|
||||
`applicability`.
|
||||
|
||||
The resolver must emit `workload_ref`, authoritative identity binding(s),
|
||||
declared and effective zone, admission and reason, membership guarantees,
|
||||
source reference, and source revision. Explicit `not-applicable` remains
|
||||
distinct from unresolved applicable input; absence or ambiguity returns
|
||||
`unknown` and never path- or repo-name inference.
|
||||
|
||||
This task does not add cross-repository discovery. The caller supplies the
|
||||
authoritative Repo Manager projection.
|
||||
|
||||
**Done when:** single-service, multi-service, managed-workload, direct
|
||||
operational-workload, `unknown`, `unsatisfied`, and `not-applicable` fixtures
|
||||
all produce the canonical shapes, and ambiguous identities are rejected.
|
||||
|
||||
**Verify:** unit tests cover every result class and prove that paths, repo
|
||||
ownership, reefs, actors, and lane names cannot manufacture membership.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T03
|
||||
status: todo
|
||||
priority: high
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Remove implicit stance authority and require profile provenance
|
||||
|
||||
Separate membership/admission resolution from control-profile projection.
|
||||
Core resolution must work without any control profile. If controls are
|
||||
projected, require an explicit versioned profile owned by the relevant control
|
||||
and PEP owners; validate total coverage across all zone ids plus `unknown` and
|
||||
emit `policy_owner`, `pep_owner`, `policy_ref` or profile version, stance, and
|
||||
failure mode.
|
||||
|
||||
There must be no anonymous hard-coded default capable of appearing
|
||||
authoritative. A missing, partial, ambiguous, or ownerless profile fails profile
|
||||
projection without changing the membership result.
|
||||
|
||||
Have flex-auth and ops-warden review the fixtures that represent their rows.
|
||||
|
||||
**Done when:** changing zone-engine code alone cannot silently change a live
|
||||
control profile; every projected row carries owner and version provenance; and
|
||||
both affected owners accept the representative fixtures or publish a versioned
|
||||
replacement.
|
||||
|
||||
**Verify:** tests reject incomplete coverage, unknown control ids, missing
|
||||
owners, invalid stance/failure combinations, and unversioned profiles.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T04
|
||||
status: todo
|
||||
priority: medium
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Make membership revision and change observability truthful
|
||||
|
||||
Bind `membership_revision` to the canonicalized authoritative identity,
|
||||
membership declaration, and explicit source revision. Add deterministic
|
||||
comparison against a supplied previous snapshot and report additions,
|
||||
removals, and changes without consulting a service.
|
||||
|
||||
Define canonical ordering and serialization so identical facts produce the
|
||||
same digest across path locations and input ordering. A missing source revision
|
||||
must not produce a falsely source-bound digest.
|
||||
|
||||
**Done when:** the output meets the revision and observability claims in canon,
|
||||
including explicit handling for first snapshots and removed workloads.
|
||||
|
||||
**Verify:** golden tests prove stability, source-revision sensitivity, reorder
|
||||
insensitivity, and correct add/remove/change reports.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Add executable exception-lifecycle conformance fixtures
|
||||
|
||||
Turn the minimum exception record and expiry rules into offline validation and
|
||||
deterministic fixtures. The checker receives an explicit evaluation instant; it
|
||||
does not read a live clock in a decision path and does not grant or store an
|
||||
exception.
|
||||
|
||||
Cover designated grant authority, owner-qualified control, exact workload and
|
||||
zone scope, exclusive `not_after`, maximum duration, renewal with a new id,
|
||||
invalid/unevaluable records being inactive, wildcard rejection, and the rule
|
||||
that durable authority cannot outlive the exception.
|
||||
|
||||
**Done when:** owners can reuse the fixtures to prove their implementation of
|
||||
the lifecycle while zone-engine remains neither grant authority nor runtime
|
||||
evaluator.
|
||||
|
||||
**Verify:** boundary-time and malformed-record tests cover before, active,
|
||||
exclusive-expiry, over-duration, wrong-authority, unknown-workload, overlap,
|
||||
and durable-expiry cases.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T06
|
||||
status: todo
|
||||
priority: high
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Replay adoption against the hardened reference contract
|
||||
|
||||
Re-run the direct ops-warden and flex-auth declarations and add representative
|
||||
Repo Manager applicable and not-applicable projections. Confirm that membership
|
||||
digests, profile provenance, and exception fixtures are machine-readable and
|
||||
that consumer-owned suites still pass.
|
||||
|
||||
Record exact repository revisions, commands, outputs/digests, and owner review
|
||||
in a new evidence document. Do not require or deploy a zone-engine service.
|
||||
|
||||
**Done when:** the hardened resolver proves both existing adoption and the
|
||||
previously missing contract branches, and no consumer obtains stance or an
|
||||
authorization effect from an unversioned zone-engine default.
|
||||
|
||||
**Verify:** zone-engine tests and checks pass; affected owner test suites pass;
|
||||
canon validation passes; `git diff --check` is clean in every changed repo.
|
||||
|
||||
```task
|
||||
id: ZONE-WP-0002-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
quality_dor: DoR-Ok
|
||||
quality_dor_at: "2026-08-23"
|
||||
quality_dor_by: codex
|
||||
```
|
||||
|
||||
### Reconcile present-state documentation and execute the retirement decision
|
||||
|
||||
Update `README.md`, `INTENT.md`, `SCOPE.md`, and `GOAL.md` so historical
|
||||
hypotheses are distinguished from current capability. Record the final answer:
|
||||
|
||||
- **archive** after canon lineage, fixtures, and evidence are durably owned; or
|
||||
- **retain** as a reference-conformance repository with a named maintainer,
|
||||
canon-sync policy, and concrete change triggers.
|
||||
|
||||
An actual Forgejo archive or rename is an attended operator action. Do not take
|
||||
it merely because the technical checklist passes.
|
||||
|
||||
**Done when:** the documents agree, the archive/retain decision names its
|
||||
authority and date, no open task is hidden in prose, and either the attended
|
||||
archive is recorded or the continuing maintenance contract is explicit.
|
||||
|
||||
**Verify:** work-record consistency and quality-debt checks pass; the workplan
|
||||
has a DoD assessment; the final history record links all canonical and consumer
|
||||
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.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- A zone-engine API, daemon, database, controller, scheduler, or synchronous lookup.
|
||||
- Cross-repository fleet discovery or repair of missing workload references.
|
||||
- Changes to Repo Manager placement/reef semantics or its v1 reference authority.
|
||||
- Choosing flex-auth policy stance or an ops-warden PEP failure mode.
|
||||
- Granting, storing, scheduling, or centrally expiring live exceptions.
|
||||
- Migrating pre-rapp deployables or unresolved catalog entries for their owners.
|
||||
- Renaming or archiving the Forgejo repository without attended operator approval.
|
||||
|
||||
## Stop conditions
|
||||
|
||||
Stop and return to the relevant owner if implementation would require any of
|
||||
the following:
|
||||
|
||||
- inferring workload identity or applicability;
|
||||
- making zone-engine's profile authoritative over an owner policy package;
|
||||
- adding zone-engine to a live authorization or enforcement path;
|
||||
- changing Repo Manager's v1 tuple rather than consuming it; or
|
||||
- performing an unattended destructive archive/rename.
|
||||
Loading…
Add table
Add a link
Reference in a new issue