tegwick
bee22db620
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb
109 lines
4.7 KiB
Markdown
109 lines
4.7 KiB
Markdown
# Reef posture-provider contract
|
|
|
|
Status: proposal for `repo-manager` agreement under `NK-WP-0027-T02`
|
|
|
|
Date: 2026-08-22
|
|
|
|
Canon owner: `net-kingdom`
|
|
|
|
Reef vocabulary and declaration owner: `repo-manager` / `railiance-master`
|
|
|
|
## Purpose
|
|
|
|
A reef states where workloads may be placed and which residual substrate risk
|
|
has been accepted. It is not a `P` level. It can nevertheless bound a posture
|
|
axis: the current single-member `reef-railiance` can never make V2 failover
|
|
reachable, regardless of how many replicas a workload declares.
|
|
|
|
This proposal extends Tenancy Posture Decision 5.5's provider shape to reefs
|
|
without moving reef vocabulary into NetKingdom. The block belongs in the
|
|
authoritative `declarations/reef.yaml`; it does not create a second reef file or
|
|
duplicate the derived `bound_rapps` projection.
|
|
|
|
## Proposed declaration block
|
|
|
|
```yaml
|
|
posture_provider:
|
|
framework: netkingdom-tenancy-posture
|
|
reviewed: "2026-08-22"
|
|
review_due: "2027-02-22"
|
|
axes:
|
|
V:
|
|
available: 0
|
|
maximum: 1
|
|
conditions:
|
|
- A bound workload documents and exercises restart or recreation recovery in this failure domain.
|
|
- The workload names every synchronous dependency used by the claimed operation.
|
|
evidence:
|
|
- evidence/verification/rail-runtime-2026-08-21.json
|
|
- evidence/admission/rail-kubernetes-baseline.json
|
|
reason: One observed member carries the control plane, etcd, and workloads; no automated failover is reachable.
|
|
```
|
|
|
|
The `reef-railiance` values are deliberately conservative:
|
|
|
|
- `available: 0` means the reef offers no unconditional, reusable recovery
|
|
guarantee to every bound workload today. A Ready node is not recovery
|
|
evidence.
|
|
- `maximum: 1` means a named workload can reach V1 by satisfying and evidencing
|
|
the restart/recreate conditions. One failure domain makes V2 unreachable.
|
|
|
|
The owner may raise `available` when the reef publishes a reusable recovery
|
|
guarantee that consumers can cite. Adding independent members and an exercised
|
|
failover path may raise `maximum`; topology alone does not.
|
|
|
|
## Semantics
|
|
|
|
Each declared axis contains:
|
|
|
|
| Field | Meaning |
|
|
| --- | --- |
|
|
| `available` | Highest level the provider guarantees unconditionally to every binding in scope, with current evidence. |
|
|
| `maximum` | Highest level a named consumer can reach after satisfying the listed conditions. |
|
|
| `conditions` | Consumer or binding work required above `available`; empty only when `available == maximum`. |
|
|
| `evidence` | Source-linked, current artifacts supporting the provider facts. |
|
|
| `reason` | Why the ceiling exists, especially when structural or accepted. |
|
|
|
|
A reef declares only axes it materially bounds. A compute reef normally
|
|
declares `V`; it does not declare `P` merely because data-bearing workloads sit
|
|
on it. A provider-delegated storage reef may bound `P`, `R`, or `V`, but only
|
|
where the substrate contract actually makes those properties reachable.
|
|
|
|
`available` and `maximum` use the axis vocabulary from
|
|
`tenancy-posture_v0.1`. `available` MUST NOT exceed `maximum`. Review dates and
|
|
evidence discipline follow Decisions 5.4, 5.5, and §13.
|
|
|
|
## Mechanical reconciliation
|
|
|
|
For each workload operation and each bound reef:
|
|
|
|
1. Resolve the reef from the workload's authoritative placement declaration.
|
|
Missing or conflicting placement is `unknown`; do not select a default reef.
|
|
2. Load the reef's `posture_provider` block from `declarations/reef.yaml`.
|
|
3. Reject a workload claim above the reef's `maximum`.
|
|
4. For a claim above `available`, require machine-readable evidence that every
|
|
listed condition is satisfied for that workload and operation.
|
|
5. Compose `V` with every synchronous provider using Decision 4.6.1's minimum
|
|
rule. A reef ceiling is one input, not the whole availability claim.
|
|
6. Emit the reef declaration revision and evidence references in the
|
|
reconciliation result so the decision is reproducible.
|
|
|
|
The result is one of `satisfied`, `unsatisfied`, or `unknown`. `unknown` covers
|
|
an absent provider block, unresolved reef binding, stale review, missing
|
|
evidence, or an unrecognised axis value. It is never converted to a permissive
|
|
ceiling.
|
|
|
|
## Ownership boundary
|
|
|
|
- `net-kingdom` owns the meaning of provider reachability and the `P`/`V`
|
|
composition rules.
|
|
- `repo-manager` / `railiance-master` owns whether and how this block is added
|
|
to the reef schema.
|
|
- Each `reef-*` repo owns its values, evidence, and review.
|
|
- The workload owner owns its claim and evidence that provider conditions are
|
|
met.
|
|
- The reconciler reports; it does not manufacture acceptance or posture.
|
|
|
|
T03 may implement the join only after `repo-manager` agrees the authoritative
|
|
field name and carrier. The semantics above are the canon-side acceptance
|
|
criteria; the exact reef-schema spelling remains the reef owner's decision.
|