docs: reef attribute refs and resource object workplan

Publish the operational reference convention (reef: and secret:
handles). Add a resource-control view of reef-railiance that excludes
S3. Open RESOURCE-WP-0006 for the five-facet inventory model.

docs/operational-reference-convention.md

@@ -0,0 +1,146 @@
+# Operational reference convention v0.1
+
+Status: baseline  
+Effective: 2026-08-14  
+Owners: `resource-control` (join keys), `reef-*` (operational facts)
+
+`resource-control` manages resources from **procurement, consumption, usage,
+and cost**. It does not operate them. A `reef-*` repo is the operational
+substrate. Non-secret operating attributes and credential *handles* are
+therefore **references**, never copies of the operating record and never
+secret values.
+
+This is the join convention. Schema adoption is `RESOURCE-WP-0006`.
+`reef-storage` materialization is `RMASTER-WP-0022`.
+
+---
+
+## Authority
+
+| Fact | Authoritative home |
+| --- | --- |
+| Why the resource exists, what was decided, who pays, who may consume, what it cost | `resource-control` |
+| How the substrate is named, reached, bound, and run | the `reef-*` repo |
+| Secret material (access keys, tokens, payment instruments) | approved OpenBao / credential-broker lane (`railiance-platform` today) |
+| Booked invoices and recognized payments | `fin-hub` |
+| Workload use of a reviewed destination | the consuming `rapp-*` |
+
+Do not duplicate a reef attribute into the inventory record “for convenience.”
+Cite it. If the reef path moves, update the reference, not a shadow copy.
+
+---
+
+## Reference forms
+
+### Reef attribute
+
+A non-secret operating fact owned by a reef:
+
+```text
+reef:<reef_id>/<repo-relative-path>#<json_or_yaml_key>
+```
+
+- `reef_id` equals the reef repo slug (`reef-railiance`, `reef-storage`).
+- Path is from the reef repo root, POSIX, no `..`.
+- Fragment is a dotted key into that file (`endpoint`, `bucket.prefix`).
+- The file is committed, non-secret, and the reef is authoritative for it.
+
+Examples (illustrative until `reef-storage` exists):
+
+```text
+reef:storage/substrate/object-stores/platform-audit-storage.yaml#endpoint
+reef:storage/substrate/object-stores/platform-audit-storage.yaml#bucket
+reef:storage/substrate/object-stores/platform-audit-storage.yaml#region
+reef:railiance/declarations/reef.yaml#current_members
+```
+
+Inventory stores the reference, not the endpoint string.
+
+### Credential handle
+
+A pointer to custody, never a value:
+
+```text
+secret:<custody_repo>/<secret_id>
+```
+
+Example already named by the backup split:
+
+```text
+secret:railiance-platform/platform-pg-backup-s3
+```
+
+The handle may also record `broker` (`openbao`) and `rotation` as non-secret
+metadata. The secret body stays in the broker.
+
+### Structured form
+
+When a record needs more than a string:
+
+```json
+{
+  "kind": "reef_attribute",
+  "reef_id": "reef-storage",
+  "repo": "reef-storage",
+  "path": "substrate/object-stores/platform-audit-storage.yaml",
+  "key": "endpoint",
+  "ref": "reef:storage/substrate/object-stores/platform-audit-storage.yaml#endpoint"
+}
+```
+
+```json
+{
+  "kind": "credential_handle",
+  "custody_repo": "railiance-platform",
+  "secret_id": "platform-pg-backup-s3",
+  "broker": "openbao",
+  "ref": "secret:railiance-platform/platform-pg-backup-s3"
+}
+```
+
+Both `ref` and the parsed fields must agree when both are present.
+
+---
+
+## What a resource-control resource then holds
+
+Five facets, all first-class in the forthcoming inventory v0.3:
+
+1. **Description** — purpose and class; why this resource exists.
+2. **Decision** — chosen option, approver, date, rejected alternatives
+   (or an explicit “not decided” gap). Required before status `ordered`.
+3. **Operational attribute refs** — `reef:…` pointers. Empty only with an
+   explicit gap (reef not created yet).
+4. **Credential handles** — `secret:…` pointers. Empty is allowed when no
+   credential exists yet; values are never stored here.
+5. **Consumers** — `potential` (intended / declared) vs `actual` (observed
+   using the resource). A name in `workload_ids` alone is not enough.
+
+---
+
+## Reef views
+
+`data/reefs/<reef_id>.json` is the **resource-control view** of a reef: which
+inventory records implement its procured capacity, which entities pay, which
+consumers are potential vs actual. It is not a second `reef.yaml` and must
+not restate member IPs, kubeconfig paths, or endpoints.
+
+`reef-railiance` is compute (Host Europe `railiance01`, k3s, platform
+services). It does **not** grow an S3 object store. Backup object storage is
+a different substrate boundary: `reef-storage`.
+
+---
+
+## Backup / S3 split (the proving case)
+
+| Concern | Owner |
+| --- | --- |
+| Demand, comparison, purchase approval, cost, settlement | `resource-control` (`RESOURCE-WP-0002`) |
+| Operate the Scaleway (or successor) object store: endpoint, bucket, region, lifecycle as committed facts | `reef-storage` (`RMASTER-WP-0022`) |
+| Credential custody and delivery | `railiance-platform` OpenBao |
+| Barman, schedule, retention, restore | `rapp-postgres` after a reviewed destination |
+| Consume the destination | `rapp-postgres` (actual once WAL flows) |
+
+Until `reef-storage` exists, the proposed backup record may cite a gap
+instead of a `reef:` URL. That gap is expected; inventing an endpoint here
+is not.