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.

INTENT.md

@@ -149,7 +149,13 @@ resources and utilization; the booked financial fact remains authoritative in
 10. **Avoid correlated failure silently.** Shared failure domains may be
     intentional, but they and their compensating controls must be explicit.
 11. **Credentials stay elsewhere.** Provider keys and billing credentials live
-    in approved secret-custody lanes, never in this repository.
+    in approved secret-custody lanes, never in this repository. Inventory
+    stores `secret:` handles only.
+12. **Operating attributes stay on the reef.** Endpoints, buckets, member
+    lists, and kubeconfig paths are cited as `reef:` references
+    (`docs/operational-reference-convention.md`). This repository does not
+    operate the resource. Compute substrate: `reef-railiance`. Object-store
+    substrate for backup: `reef-storage`, not an add-on to the home reef.
 
 ## What it does not own
 

SCOPE.md

@@ -47,5 +47,6 @@ resource-control exists to provide the capability described in INTENT.md.
 
 - Start with: INTENT.md
 - Internal procurement terms: docs/TermsOfResourceProcurement.md
+- Operational refs: docs/operational-reference-convention.md
 - Agent instructions: AGENTS.md
 - Workplans: workplans/

WORK-RECORDS.md

@@ -13,6 +13,7 @@
 | workplan | RESOURCE-WP-0003 | finished | — | workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md |
 | workplan | RESOURCE-WP-0004 | finished | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md |
 | workplan | RESOURCE-WP-0005 | finished | — | workplans/RESOURCE-WP-0005-resource-procurement-facility.md |
+| workplan | RESOURCE-WP-0006 | ready | — | workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md |
 | task | RESOURCE-WP-0001-T01 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md |
 | task | RESOURCE-WP-0001-T02 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md |
 | task | RESOURCE-WP-0001-T03 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md |
@@ -42,3 +43,7 @@
 | task | RESOURCE-WP-0005-T05 | done | — | workplans/RESOURCE-WP-0005-resource-procurement-facility.md |
 | task | RESOURCE-WP-0005-T06 | done | — | workplans/RESOURCE-WP-0005-resource-procurement-facility.md |
 | task | RESOURCE-WP-0005-T07 | done | — | workplans/RESOURCE-WP-0005-resource-procurement-facility.md |
+| task | RESOURCE-WP-0006-T01 | todo | — | workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md |
+| task | RESOURCE-WP-0006-T02 | progress | — | workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md |
+| task | RESOURCE-WP-0006-T03 | todo | — | workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md |
+| task | RESOURCE-WP-0006-T04 | todo | — | workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md |

data/reefs/reef-railiance.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "0.1",
+  "reef_id": "reef-railiance",
+  "repo": "reef-railiance",
+  "declaration_ref": "reef:railiance/declarations/reef.yaml",
+  "procuring_entity_id": "entity:railiance",
+  "financial_entity_id": "entity:railiance",
+  "role": "compute_substrate",
+  "resources": [
+    {"resource_id": "resource:hosteurope:railiance01", "role": "member_capacity"},
+    {"resource_id": "resource:railiance:reef-railiance:k3s", "role": "hosted_runtime"},
+    {"resource_id": "resource:railiance:apps-pg", "role": "hosted_service"},
+    {"resource_id": "resource:railiance:forgejo", "role": "hosted_service"},
+    {"resource_id": "resource:tenant:coulomb:coulomb-social", "role": "hosted_service"},
+    {"resource_id": "resource:tenant:friendly:binky:rapp-qonto", "role": "hosted_service"}
+  ],
+  "consumers_potential": [
+    "rapp-postgres",
+    "rapp-qonto",
+    "rapp-openbao",
+    "coulomb-social",
+    "helix-forge",
+    "railiance-platform"
+  ],
+  "consumers_actual": [
+    "coulomb-social",
+    "rapp-qonto",
+    "railiance-platform"
+  ],
+  "notes": [
+    "This is a resource-control cost and consumption view, not a copy of reef.yaml.",
+    "Member IPs, SSH, kubeconfig, and rail admission stay in reef-railiance.",
+    "S3-compatible backup storage is out of this reef; that substrate is reef-storage."
+  ]
+}

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.

schemas/reef-view.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coulomb.social/resource-control/reef-view.schema.json",
+  "title": "Resource-control view of a reef v0.1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "reef_id",
+    "repo",
+    "declaration_ref",
+    "procuring_entity_id",
+    "role",
+    "resources",
+    "consumers_potential",
+    "consumers_actual"
+  ],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "reef_id": {"type": "string", "pattern": "^reef-[a-z0-9]+(-[a-z0-9]+)*$"},
+    "repo": {"type": "string", "pattern": "^reef-[a-z0-9]+(-[a-z0-9]+)*$"},
+    "declaration_ref": {"type": "string", "pattern": "^reef:"},
+    "procuring_entity_id": {"type": "string", "pattern": "^entity:[a-z0-9]+$"},
+    "financial_entity_id": {"type": ["string", "null"], "pattern": "^entity:[a-z0-9]+$"},
+    "role": {"enum": ["compute_substrate", "storage_substrate", "other_substrate"]},
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["resource_id", "role"],
+        "properties": {
+          "resource_id": {"type": "string", "pattern": "^resource:"},
+          "role": {"enum": ["member_capacity", "hosted_runtime", "hosted_service", "object_store", "other"]}
+        }
+      }
+    },
+    "consumers_potential": {"type": "array", "items": {"type": "string"}},
+    "consumers_actual": {"type": "array", "items": {"type": "string"}},
+    "notes": {"type": "array", "items": {"type": "string"}}
+  }
+}

tests/test_portfolio.py

@@ -77,5 +77,21 @@ class PortfolioTest(unittest.TestCase):
         )
 
 
+class ReefViewTest(unittest.TestCase):
+    def test_reef_railiance_view_cites_only_inventory_and_excludes_s3(self):
+        view = json.loads((ROOT / "data/reefs/reef-railiance.json").read_text())
+        inventory = {
+            json.loads(path.read_text())["id"]
+            for path in (ROOT / "data/resources").glob("*.json")
+        }
+        self.assertEqual("reef-railiance", view["reef_id"])
+        self.assertTrue(view["declaration_ref"].startswith("reef:"))
+        self.assertEqual("compute_substrate", view["role"])
+        for row in view["resources"]:
+            self.assertIn(row["resource_id"], inventory)
+        self.assertNotIn("resource:platform:audit-storage", {row["resource_id"] for row in view["resources"]})
+        self.assertTrue(any("reef-storage" in note for note in view["notes"]))
+
+
 if __name__ == "__main__":
     unittest.main()

tools/validate.py

@@ -114,6 +114,18 @@ def main() -> int:
     assert planning["transfer_price"] == "240.00"
     assert planning["credit_headroom"] == "760.00"
     assert planning["financial_entity_id"] == "entity:coulomb"
+    reef_view_schema = load("schemas/reef-view.schema.json")
+    assert reef_view_schema["$schema"].endswith("2020-12/schema")
+    inventory_ids = {resource["id"] for resource in resources if resource.get("record_scope") == "inventory"}
+    for path in Path("data/reefs").glob("*.json"):
+        view = load(str(path))
+        assert view["schema_version"] == "0.1"
+        assert view["declaration_ref"].startswith("reef:")
+        missing = [row["resource_id"] for row in view["resources"] if row["resource_id"] not in inventory_ids]
+        assert not missing, f"{path} cites unknown resources: {missing}"
+        if view["reef_id"] == "reef-railiance":
+            assert view["role"] == "compute_substrate"
+            assert any("reef-storage" in note for note in view.get("notes") or [])
     print("resource-control declarations: valid")
     return 0
 

workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md

@@ -69,6 +69,13 @@ This workplan owns requirements, comparison, procurement evidence, resource
 registration, cost/utilization monitoring, and proof that the purchased
 resource works.
 
+The purchased object is a five-facet resource (`RESOURCE-WP-0006`):
+description, decision, `reef:` attribute refs, `secret:` handles, and
+potential vs actual consumers. Non-secret operating attributes (endpoint,
+bucket, region) will be owned by `reef-storage` (`RMASTER-WP-0022`), not
+inlined here and not placed on `reef-railiance`. See
+`docs/operational-reference-convention.md`.
+
 - Human financial authority approves purchase and accepts contractual terms.
 - `railiance-platform` owns provider credential custody and the approved
   Kubernetes Secret/credential-broker delivery.

workplans/RESOURCE-WP-0006-resource-object-and-reef-refs.md

@@ -0,0 +1,124 @@
+---
+id: RESOURCE-WP-0006
+type: workplan
+title: "Resource object model and reef operational references"
+domain: financials
+repo: resource-control
+status: ready
+owner: grok
+topic_slug: railiance
+created: "2026-08-14"
+updated: "2026-08-14"
+related:
+  - RESOURCE-WP-0002
+  - RESOURCE-WP-0003
+  - RESOURCE-WP-0005
+  - RMASTER-WP-0022
+state_hub_workstream_id: "2108f67a-c1a9-4e53-b427-7011168b1fd2"
+---
+
+# RESOURCE-WP-0006 — resource object model and reef operational references
+
+## Goal
+
+Make the inventory record a **managed resource object** with five facets:
+
+1. description
+2. decision
+3. operational attribute **references** (`reef:…`)
+4. credential **handles** (`secret:…`)
+5. potential vs actual consumers
+
+`resource-control` stays the procurement, consumption, usage, and cost
+plane. It does not operate the resource. Operating facts live on a reef.
+The convention is `docs/operational-reference-convention.md`.
+
+`reef-railiance` is the compute substrate. S3-compatible backup storage is
+**not** added there. `reef-storage` (RMASTER-WP-0022) will operate Scaleway
+object storage and own the non-secret attributes this repo will cite.
+
+## Boundaries
+
+- Secret values stay in OpenBao. This repo stores handles only.
+- Reef attribute values stay in the reef repo. This repo stores references
+  only.
+- `RESOURCE-WP-0002` procures the backup bucket against this model; it does
+  not invent endpoints.
+- `RMASTER-WP-0022` materializes `reef-storage`. This workplan only defines
+  the join.
+
+## T01 — Adopt the five-facet inventory schema
+
+```task
+id: RESOURCE-WP-0006-T01
+status: todo
+priority: high
+state_hub_task_id: "55d3ebc2-51b7-49d1-8d0d-57ccc6379ae7"
+```
+
+Publish inventory schema v0.3 with first-class description, decision,
+`operational_refs`, `credential_handles`, and `consumers.potential` /
+`consumers.actual`. Keep v0.2 records valid until migrated, or migrate all
+live records in the same change. Decision is required before status
+`ordered`.
+
+Done when validators reject an `ordered` resource without a decision, reject
+an inline secret or endpoint that should be a `reef:` / `secret:` ref, and
+accept the proposed backup record with an explicit attribute-ref gap until
+`reef-storage` exists.
+
+## T02 — Reef views and the reef-railiance projection
+
+```task
+id: RESOURCE-WP-0006-T02
+status: progress
+priority: high
+state_hub_task_id: "f2b38140-3d73-45a2-a2ff-fea12733e7b0"
+```
+
+Keep `data/reefs/*.json` as the cost/consumption view of a reef. Validate
+`data/reefs/reef-railiance.json` against
+`schemas/reef-view.schema.json`. Do not copy IPs, kubeconfig, or endpoints.
+Add a `reef-storage` view only after that repo exists.
+
+Done when `make test` validates reef views, every `resource_id` in the
+reef-railiance view exists in inventory, and the view states that S3 backup
+is out of `reef-railiance`.
+
+Started 2026-08-14: convention published; first reef-railiance view committed.
+
+## T03 — Migrate live inventory to the five facets
+
+```task
+id: RESOURCE-WP-0006-T03
+status: todo
+priority: high
+state_hub_task_id: "da959cf1-cbd2-492c-95ff-b9ab78c16697"
+```
+
+Backfill description, decision-or-gap, consumer potential/actual, and
+operational/credential refs or explicit gaps on every
+`data/resources/` record. The proposed backup resource is the proving
+case: consumers potential = `rapp-postgres`; actual = empty until WAL
+flows; attribute refs wait on `reef-storage`; credential handle =
+`secret:railiance-platform/platform-pg-backup-s3` once custody exists.
+
+Done when no live record relies on undifferentiated `workload_ids` as the
+only consumer list.
+
+## T04 — Wire WP-0002 to the convention
+
+```task
+id: RESOURCE-WP-0006-T04
+status: todo
+priority: medium
+state_hub_task_id: "a34fa806-ee34-4d3b-a823-2797fe260bbc"
+```
+
+Update `RESOURCE-WP-0002` so T03+ produce a resource object, not a v0.2
+card with a dangling endpoint. The decision record, reef-storage attribute
+refs, and the OpenBao handle are the procurement outputs. `rapp-postgres`
+remains a consumer, not the procurer.
+
+Done when WP-0002 cites this convention and will not accept an inventory
+update that inlines Scaleway endpoint or keys.