zone-engine/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md

---
id: ZONE-WP-0002
type: workplan
title: "Harden the reference contract and make retirement decidable"
domain: infotech
repo: zone-engine
status: active
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: "d2ed3f0"
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."
state_hub_workstream_id: "c349aa5c-d7fd-5c48-83aa-422cc42b9c67"
---

# 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: progress
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "d15053e8-d2a1-51ba-9a8f-45b899dbcab1"
```

### 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
state_hub_task_id: "2bbf0936-041c-548d-91af-2746925a88e8"
```

### 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
state_hub_task_id: "f2477679-e057-5dc9-87f1-0944e3f45642"
```

### 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
state_hub_task_id: "91242013-3ab8-5a16-a479-a77eb0233bab"
```

### 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
state_hub_task_id: "9773cdc3-cc86-5cfb-bd00-fecaf68c8405"
```

### 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
state_hub_task_id: "233c926f-00d4-5ebf-a867-154508c905d5"
```

### 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
state_hub_task_id: "aef75984-a5c4-573f-8fe4-90d1ee0ba695"
```

### 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.