docs(canon): reconcile workload and tenant grouping semantics

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb

docs/reef-posture-provider-contract.md

@@ -0,0 +1,109 @@
+# 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.