# RESOURCE-WP-0003 portfolio model v0.2

Date: 2026-08-11
Task: `RESOURCE-WP-0003-T01`
Schema: `schemas/resource-inventory.schema.json`

## Result

The inventory model is generalized from a storage purchase record into a
managed-infrastructure portfolio record. Version 0.2 represents:

- provider-managed elastic storage;
- self-managed services hosted on rented capacity;
- Kubernetes or other shared capacity;
- shared platform services; and
- future compute, network, database, managed-service, and license records.

The existing proposed Scaleway backup resource was migrated as the only
authoritative inventory record. The Garage, Kubernetes-capacity, and ingress
records live under `examples/portfolio/`, carry `record_scope: example`, and
contain explicit example evidence. They are schema proofs, not claims about
live infrastructure.

## Model decisions

- Resource identity uses the stable `resource:` namespace independently of
  provider-native identifiers.
- Lifecycle separates proposed, ordered, commissioning, active, suspended,
  retiring, retired, and rejected states.
- Provider-managed, self-managed, and shared-capacity management models are
  explicit.
- Capacity is a set of typed dimensions and distinguishes provisioned, usable,
  allocated, observed, limiting, and unknown values.
- Ownership supports multiple workloads, optional tenant identity, and a
  dedicated, shared, or unattributed allocation mode.
- Shared allocations require a driver and versioned method. Unknown allocation
  remains explicit rather than receiving an invented key.
- Relationships express hosting, composition, dependency, replacement,
  capacity consumers, and backup placement without embedding another
  repository's graph authority.
- Requirements and evidence carry their kind, reference, observation date,
  and authoritative source.
- Exit path is mandatory for every resource class.

## Semantic controls

`tools/portfolio.py` adds controls not conveniently expressed as shape alone:

- valid lifecycle transitions;
- ordered lifecycle dates;
- commissioned dates for operational resources;
- order evidence for operational provider-managed resources;
- allocation-key and shared-driver consistency;
- unique capacity metric/kind dimensions;
- prevention of self-relationships; and
- unmistakable example evidence.

Verification:

```text
18 tests passed
resource-control declarations: valid
git diff --check: pass
```

## Next use

`RESOURCE-WP-0003-T03` should now discover real portfolio records for Helix
Forge, Coulomb Social, shared Railiance services, and one representative tenant
workload. It must replace example assumptions with source evidence and preserve
unknown values where authority is not yet available.