net-kingdom/docs/reef-posture-provider-contract.md

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

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.