# 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 (live on `reef-storage` and `reef-railiance`):

```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/backup
```

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": "backup",
  "broker": "openbao",
  "ref": "secret:railiance-platform/backup"
}
```

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