From 1a20bd6ba269b4bb150339a7ae901733480c121c Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 23 Aug 2026 11:29:20 +0200 Subject: [PATCH] docs: plan zone reference contract hardening Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0291a-1e87-7151-9934-fcbfe3f65eb1 --- SCOPE.md | 13 +- WORK-RECORDS.md | 8 + ...rence-contract-hardening-and-retirement.md | 318 ++++++++++++++++++ 3 files changed, 334 insertions(+), 5 deletions(-) create mode 100644 workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md diff --git a/SCOPE.md b/SCOPE.md index c92e09b..2a7ba58 100644 --- a/SCOPE.md +++ b/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: diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 5eb9595..ce6d82f 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -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 | diff --git a/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md b/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md new file mode 100644 index 0000000..c3dc169 --- /dev/null +++ b/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.