resource-control/docs/operational-reference-convention.md

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:

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):

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:

secret:<custody_repo>/<secret_id>

Example already named by the backup split:

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:

{
  "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"
}

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