resource-control/workplans/RESOURCE-WP-0005-resource-procurement-facility.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	origin	origin_ref	state_hub_workstream_id
RESOURCE-WP-0005	workplan	Build the resource procurement facility	financials	resource-control	ready	grok	railiance	2026-08-14	2026-08-14	RESOURCE-WP-0003 RESOURCE-WP-0004 FIN-WP-0004	residual	RESOURCE-WP-0004	0c710416-e469-45a7-b007-d08ff3210c04

RESOURCE-WP-0005 — build the resource procurement facility

Goal

Turn docs/TermsOfResourceProcurement.md V0.1 into an operational facility in this repository: executable entity register, terms parameters, association on every cost-bearing record, delivered-cost and transfer-price calculation, monthly settlement statements, credit-state evaluation, and the signals fin-hub and Railiance operations need.

This is the implementation residual of RESOURCE-WP-0004, which published the terms. The facility must be usable for a monthly close before any entity bank account exists: statements and credit state are computed from committed evidence; payment recognition stays unknown until fin-hub projects a payment.

Boundaries

• resource-control owns the register, the arithmetic, the statements, and the consumption-mode signal.
• fin-hub owns booked provider cost, recognized payments, tax, and any later posting of internal settlement. This workplan does not create a second ledger.
• Railiance platform repos enforce restricted consumption. This workplan publishes the signal; it does not throttle a cluster.
• Human financial authority opens accounts, changes P1–P12, and waives limits. The facility stores the resulting parameters, not the conversation.
• Schema changes stay compatible with docs/fin-hub-resource-control-contract-v0.1.md. New fields are additive. Unknown remains explicit; no silent default to Railiance or Binky.
• Money is EUR, two decimal places, round-half-even, matching tools/financial_exchange.py.

Facility shape

When this workplan is finished, an operator can:

make test
make settlement PERIOD=2026-08
make portfolio-report

and get, from committed evidence:

• one settlement statement per consuming entity that has a charge, credit, interest, or open balance;
• open or restricted consumption mode and the next month's allowance (max(0, 50.00 − monthly_interest) at the default limit);
• transfer prices at cost plus 20 % except Railiance self-use at cost;
• a report that names unattributed cost instead of spreading it.

The three worked examples in Terms § 15 are executable fixtures.

T01 — Entity register and terms parameters

id: RESOURCE-WP-0005-T01
status: todo
priority: high
state_hub_task_id: "f8df895b-9959-4bb2-958e-f2444b558aac"

Publish the six financial entities and the V0.1 parameter table as versioned data, not only as prose.

Expected shape (refine as needed):

• data/entities/register.json — entity:binky, entity:frontier, entity:railiance, entity:netkingdom, entity:helixforge, entity:coulomb; display name; role (umbrella, provider, consumer); default credit limit; non-secret account_ref (null until banking exists); status.
• data/terms/procurement-v0.1.json — P1–P15 from Terms § 14, including markup 0.20, payment term 10 days, interest 0.05 per year, credit limit 1000.00, restricted cap 50.00. Record terms_version: "0.1".
• Schemas and validator coverage so an unknown entity ID or a parameter set that does not match the published terms fails closed.

Done when make test loads the register and the V0.1 parameter file, rejects an unknown entity: id, and the numeric parameters match Terms § 14 exactly.

T02 — Associate every cost-bearing schema

id: RESOURCE-WP-0005-T02
status: todo
priority: high
state_hub_task_id: "5a18a74a-db07-4ab6-8bb5-ed4321ab7e11"

Add financial_entity_id (consuming entity) and procuring_entity_id (default entity:railiance) to:

• schemas/resource-inventory.schema.json
• schemas/planning-evidence.schema.json
• schemas/resource-control-cycle.schema.json

and to the semantic validators in tools/. Historical records that cannot yet be tagged carry an explicit unattributed gap, never a guessed entity.

A new cost-bearing record is invalid if it has neither a consuming entity nor an explicit gap. Shared resources keep procuring_entity_id: entity:railiance and produce per-consumer shares each tagged with a financial_entity_id.

Done when validators reject an untagged new record, accept an explicit gap, accept all six entity IDs, and existing tests still pass after additive schema changes.

T03 — Backfill the live portfolio

id: RESOURCE-WP-0005-T03
status: todo
priority: high
state_hub_task_id: "14d450fb-e1f2-4443-a284-4439579f3709"

Tag every record in data/resources/ from source evidence:

Record	Procuring	Consuming / allocation
coulomb-social-production	entity:railiance	entity:coulomb
binky-rapp-qonto	entity:railiance	entity:binky
helix-forge workloads	entity:railiance	entity:helixforge
Railiance host, cluster, forge, apps-pg	entity:railiance	Railiance self-use and/or shared allocation; unattributed where no driver exists
proposed backup storage	entity:railiance	the entity that will bear the transfer price, or an explicit gap

Do not invent allocation drivers to make shared cost look attributed. Update examples/ only where they are schema proofs, and keep record_scope: example unmistakable.

Done when every live inventory record has a procuring entity and either a consuming entity, a shared allocation that yields per-entity shares, or an explicit unattributed gap, and make test passes.

T04 — Transfer-price and credit-state engine

id: RESOURCE-WP-0005-T04
status: todo
priority: high
state_hub_task_id: "4d2c87f7-6e50-4696-a041-e8502e9fab38"

Implement the V0.1 arithmetic as a library used by settlement, forecasts, and tests. Parameters come from the T01 terms file, not from literals scattered in tools.

Required calculations:

• transfer_price = delivered_cost × (1 + markup) for every consumer except Railiance;
• transfer_price = delivered_cost for entity:railiance;
• overdue after statement date + 10 calendar days;
• interest = overdue × 0.05 / 12 at month-end close (simple, monthly);
• payment waterfall: interest first, then principal;
• consumption_mode = restricted iff outstanding ≥ credit_limit;
• new_transfer_charges_allowed = max(0, 50.00 − interest_this_month) when restricted, else unconstrained by this facility;
• credit headroom max(0, credit_limit − outstanding).

Unknown delivered-cost components stay null. A transfer price is issued only for the known portion; the unknown remainder is labelled, never filled with zero.

Done when fixtures for Terms § 15.1–15.3 assert:

• Coulomb ordinary month: transfer 240.00, due +10 days, headroom 760.00, mode open;
• same statement unpaid: interest 1.00 on 240.00;
• Helixforge at 1000.00 overdue: interest 4.17, allowance 45.83, max new delivered cost 38.19, mode restricted.

T05 — Monthly settlement statements

id: RESOURCE-WP-0005-T05
status: todo
priority: high
state_hub_task_id: "cf55645b-b3ef-4cc4-ab51-23bdf5ff3af1"

Define a settlement-statement schema and emit one statement per consuming entity that has a charge, credit, interest, or open balance for period M.

Minimum contents (Terms § 10.1): entity, period, terms_version, statement date, due date, line items (resource_id, usage summary, delivered-cost components, markup, transfer price), known-cost total, unknown remainder, prior outstanding, recognized payments (projection from fin-hub, else unknown), interest, new charges, new outstanding, credit limit, headroom, consumption mode, next-month allowance if restricted, non-secret pay-to / pay-from account_ref.

Wire make settlement PERIOD=YYYY-MM into the monthly cadence in docs/portfolio-operating-cadence.md. Railiance self-consumption is recorded at cost and does not generate a payment instruction.

Until bank accounts and booked payments exist, statements still emit; payment recognition is unknown and credit state is reported, not pretended settled.

Done when the three § 15 scenarios can be produced as statements from fixtures, make settlement runs against the repo, and a period with no consumers emits nothing rather than invented zeros.

T06 — Entity views on forecasts, variance, and the portfolio report

id: RESOURCE-WP-0005-T06
status: todo
priority: medium
state_hub_task_id: "b8baa250-f189-4ae7-a4a6-5b09a199c1dd"

Estimates and expense evaluations show delivered cost, transfer price, and effect on the consuming entity's credit headroom. The portfolio report gains an entity section: charges, unattributed residuals, open / restricted state, and missing price evidence — still refusing to print a fake known_monthly_spend_eur of 0.

Forecasts remain immutable. A new terms version does not rewrite a historical transfer price; the statement and forecast record the terms version that produced them.

Done when make portfolio-report lists each financial entity, names unattributed resources, and a forecast fixture includes transfer price and headroom without becoming booked spend.

T07 — Fin-hub and Railiance handoff, plus the close runbook

id: RESOURCE-WP-0005-T07
status: todo
priority: medium
state_hub_task_id: "d91a2ffd-7557-4a9a-a846-e6449b037eec"

This repository does not book settlement or throttle workloads. Publish the join keys and artifacts the neighbours need, then hand off:

• to fin-hub: proposed transfer-charge and credit-state records; how recognized internal payments will join (financial_fact_id, entity, period); confirmation that this is not a second ledger. Spawn or update a fin-hub work record; do not register it by hand in the hub.
• to Railiance operations: the consumption-mode signal (open | restricted, remaining transfer-price allowance, period). Enforcement of new orders and elastic usage lives there. Committed provider contracts are flagged, not auto-cancelled (OQ-2).

Write docs/resource-procurement-facility.md as the operator runbook: monthly close steps, what remains unknown without bank accounts, how a human waiver is recorded, and which repo owns each failure mode.

Done when the runbook exists, the outbound artifact shapes are documented next to the fin-hub contract, and live work records exist in the owning repos (or an intake with origin: residual if those repos cannot take the work this session).