diff --git a/INTENT.md b/INTENT.md index 1000d79..d32c6de 100644 --- a/INTENT.md +++ b/INTENT.md @@ -20,6 +20,13 @@ Its control loop is: > demand -> estimate -> compare -> approve -> procure -> commission -> allocate > -> monitor -> optimize -> renew, migrate, or retire -> learn from variance +Every estimate, usage observation, allocation, and expense evaluation in that +loop is associated with exactly one financial entity. The six entities are +Binky, Frontier, Railiance, Netkingdom, Helixforge, and Coulomb. They are +profit centers of Binky Hedgehog GmbH (future Operational Knowledge GmbH). +Railiance procures and manages IT resources; other centers consume them on +the internal terms in `docs/TermsOfResourceProcurement.md`. + `resource-control` supports each stage with evidence and recommendations. It does not silently assume authority to sign contracts, spend money, deploy workloads, or operate services. @@ -48,7 +55,7 @@ requires evidence; retaining one requires continuing value. proposed, and retired resources. - Resource identity, provider, account, region, service class, capacity, lifecycle, contract term, renewal or cancellation window, owner, workload, - tenant, environment, and cost-attribution key. + tenant, financial entity, environment, and cost-attribution key. - Demand and capacity forecasts derived from workload requirements. - Comparable total-cost models for provider-managed and self-managed options, separating infrastructure, usage, internal labor, external services, @@ -56,8 +63,10 @@ requires evidence; retaining one requires continuing value. - Technical usage, utilization, saturation, reliability, and service-level evidence projected from the systems that produce it. - Explainable allocation of shared resource consumption and cost to services, - workloads, environments, and tenants. Allocation evidence is not customer - billing. + workloads, environments, tenants, and financial entities. Allocation + evidence is not customer billing. Internal transfer prices (Railiance + delivered cost plus published markup) are settlement evidence, not booked + spend. - Unit economics and periodic rightsizing, consolidation, commitment, migration, renewal, retirement, and provider-switching recommendations. - Forecast-to-actual variance control: preserve assumptions and predictions, @@ -86,9 +95,9 @@ become the implementation repository for the whole control loop. Delegated repositories should expose stable, provenance-bearing interfaces rather than duplicate authority. The common join should support at least -`resource_id`, `service_id`, `workload_id`, `tenant_id`, `environment`, -`cost_attribution_key`, provider account, accounting period, and source -evidence where applicable. +`resource_id`, `financial_entity_id`, `procuring_entity_id`, `service_id`, +`workload_id`, `tenant_id`, `environment`, `cost_attribution_key`, provider +account, accounting period, and source evidence where applicable. ## Relationship with fin-hub @@ -122,7 +131,8 @@ resources and utilization; the booked financial fact remains authoritative in and recovery-test cost. 4. **No unowned spend or capacity.** Every resource has an accountable owner, purpose, lifecycle state, workload or shared-allocation rule, environment, - and cost-attribution key. + cost-attribution key, and a consuming financial entity (or an explicit + unattributed gap). Silent default to Railiance or Binky is forbidden. 5. **Allocation must be explainable.** Shared costs identify their driver, uncertainty, unapportioned remainder, and source evidence. 6. **Forecasts are falsifiable records.** Material estimates preserve their diff --git a/SCOPE.md b/SCOPE.md index 1abf84c..273a516 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -17,6 +17,11 @@ resource-control exists to provide the capability described in INTENT.md. resources across Host Europe, Scaleway, Hetzner, and future providers. - Normalize price, commitment, utilization, capacity, ownership, workload, location, failure domain, renewal, and exit data. +- Associate every expense, estimate, usage observation, and expense + evaluation with exactly one financial entity (Binky, Frontier, Railiance, + Netkingdom, Helixforge, Coulomb) per `docs/TermsOfResourceProcurement.md`. +- Compute Railiance delivered cost and internal transfer prices (cost plus + published markup); emit monthly settlement and credit-state evidence. - Research and compare procurement options against provider-neutral requirements. - Publish resource allocation, forecast, realized-cost, and optimization @@ -41,5 +46,6 @@ resource-control exists to provide the capability described in INTENT.md. ## Getting Oriented - Start with: INTENT.md +- Internal procurement terms: docs/TermsOfResourceProcurement.md - Agent instructions: AGENTS.md - Workplans: workplans/ diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index c3cd20e..98d66a6 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -11,6 +11,7 @@ | workplan | RESOURCE-WP-0001 | finished | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md | | workplan | RESOURCE-WP-0002 | active | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | | workplan | RESOURCE-WP-0003 | finished | — | workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md | +| workplan | RESOURCE-WP-0004 | active | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.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 | @@ -28,3 +29,8 @@ | task | RESOURCE-WP-0003-T05 | done | — | workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md | | task | RESOURCE-WP-0003-T06 | done | — | workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md | | task | RESOURCE-WP-0003-T07 | done | — | workplans/RESOURCE-WP-0003-managed-infrastructure-portfolio-control.md | +| task | RESOURCE-WP-0004-T01 | done | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md | +| task | RESOURCE-WP-0004-T02 | todo | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md | +| task | RESOURCE-WP-0004-T03 | todo | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md | +| task | RESOURCE-WP-0004-T04 | todo | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md | +| task | RESOURCE-WP-0004-T05 | todo | — | workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md | diff --git a/docs/TermsOfResourceProcurement.md b/docs/TermsOfResourceProcurement.md new file mode 100644 index 0000000..e5fefe4 --- /dev/null +++ b/docs/TermsOfResourceProcurement.md @@ -0,0 +1,725 @@ +# Terms of Resource Procurement + +| Field | Value | +| --- | --- | +| **Version** | V0.1 | +| **Status** | Baseline operating framework; open for refinement | +| **Effective** | 2026-08-14 | +| **Owner** | `resource-control` (operating policy for the control plane) | +| **Approving authority** | Human financial authority of Binky Hedgehog GmbH | +| **Supersedes** | none | + +These terms tell `resource-control` how to attribute, estimate, evaluate, and +internally charge infrastructure resources once the six financial entities +operate on separate banking accounts. They are a management-accounting +framework, not a commercial contract between legal persons and not a second +booked ledger. + +V0.1 records the founder's stated baseline. Parameters in +[§ 14](#14-default-parameters) are expected to move first; principles in +[§ 5](#5-how-resource-control-operates) should move more slowly. + +--- + +## 1. Purpose + +Binky Hedgehog GmbH is separating **Binky**, **Frontier**, **Railiance**, +**Netkingdom**, **Helixforge**, and **Coulomb** onto individual banking +accounts so each can develop as a **profit center** under the umbrella +company. Railiance procures and manages IT resources for the group. The other +centers consume those resources on published internal terms. + +`resource-control` is the control plane that makes that arrangement operable: + +- every expense, estimate, usage observation, and expense evaluation belongs + to exactly one financial entity; +- Railiance's delivered cost is reconstructed from provider facts, allocation + evidence, and attributable labor; +- consuming entities are charged that cost plus the published markup; +- monthly settlement, overdue interest, credit-limit state, and restricted + consumption are computed from those records; +- booked money, legal invoices, tax treatment, and payment execution stay + with `fin-hub` and human financial authority. + +This document is the baseline rule set for that loop. + +--- + +## 2. Legal and organizational setting + +The legal person today is **Binky Hedgehog GmbH**. The intended later +identity is **Operational Knowledge GmbH**. The rename is a milestone, not a +change of entity identifiers in this control plane. + +Until a profit center is incorporated separately, the six names are +**internal financial entities** of one GmbH. They will have dedicated bank +accounts (or equivalent account partitions). Internal charges under these +terms are transfer prices between profit centers, not customer invoices and +not intercompany invoices between distinct legal persons. + +Consequences for V0.1: + +- `resource-control` produces settlement statements and credit-state + evaluations. It does not emit a legal invoice, book a DATEV posting, or + move money. +- `fin-hub` remains authoritative for booked financial facts, tax and + currency treatment, budgets, commitments, burn, and runway, per + `docs/fin-hub-resource-control-contract-v0.1.md`. +- Consolidation and elimination of internal markup at GmbH level is an + accounting concern, not a resource-control concern. +- If an entity later becomes a separate legal person, these terms become the + draft of a real supply agreement. That step requires human legal and tax + review; it is out of scope for V0.1. + +--- + +## 3. Financial entities + +Every cost object in `resource-control` is associated with one of the +following entities. Identifiers are stable. Display names may change. +Adding, splitting, or retiring an entity is a versioned change to these +terms. + +| ID | Display name | Role under these terms | +| --- | --- | --- | +| `entity:binky` | Binky | Umbrella / company-operations profit center. Residual corporate identity of Binky Hedgehog GmbH. Consumes IT resources like any other center. Holds non-IT company costs (desk, Steuerberater, banking fees) **outside** this document. | +| `entity:frontier` | Frontier | Recognized profit center. Commercial mandate is defined by its own canon, not by this document. Consumes IT resources on the same terms as the other non-provider centers. | +| `entity:railiance` | Railiance | **Sole procuring and managing entity** for in-scope IT resources. Pays external providers. Delivers usage to the other centers. Consumes resources for its own platform at cost, without markup. | +| `entity:netkingdom` | Netkingdom | Profit center for identity, access, security, and operational sovereignty. Consumes IT resources on transfer-price terms. | +| `entity:helixforge` | Helixforge | Profit center for the capability-forging product line. Consumes IT resources on transfer-price terms. | +| `entity:coulomb` | Coulomb | Profit center for capability discovery, packaging, and related products (including Coulomb Social). Consumes IT resources on transfer-price terms. | + +Existing portfolio identities continue to work as join keys. They do not +replace the financial entity: + +| Existing key | Financial entity | +| --- | --- | +| `tenant:coulomb`, workload `coulomb-social` | `entity:coulomb` | +| `tenant:friendly:binky`, workload `rapp-qonto` | `entity:binky` | +| workload `helix-forge` | `entity:helixforge` | +| Railiance platform, cluster, host, forge, and shared services | `entity:railiance` as procuring entity; consuming entity is whoever uses the allocated share | + +A workload, tenant, or repository may belong to only one financial entity at +a time. Shared infrastructure is procured by Railiance and **allocated** to +consuming entities; it is not owned by several entities at once. + +Unknown association is a control defect. It is recorded as +`financial_entity_id: null` with an explicit gap, never as a silent default +to Railiance or Binky. + +--- + +## 4. Roles + +### 4.1 Railiance — provider of IT resources + +Railiance procures and manages at least: + +- compute +- storage +- network +- domains and DNS +- intelligence (model APIs, reserved weights storage, inference capacity) +- databases and managed services +- shared platform services (cluster, forge, identity runtimes, ingress) +- licenses required to operate the above + +Railiance may add resource classes already represented in +`schemas/resource-inventory.schema.json` without a terms revision. A class +outside that model needs a schema change and a note in the next terms +revision. + +Railiance: + +1. holds the provider contract and the provider billing relationship; +2. pays the provider from the Railiance bank account; +3. commissions, operates, measures, and retires the resource; +4. exposes usage and allocation evidence into `resource-control`; +5. invoices the consuming entities internally at **cost plus markup**; +6. receives settlement into the Railiance bank account. + +### 4.2 Consuming entities + +Binky, Frontier, Netkingdom, Helixforge, Coulomb, and Railiance-for-itself +are consumers. A consumer: + +1. declares demand and service requirements in its owning repositories; +2. accepts the allocated share of shared resources it actually uses; +3. is charged the transfer price for that use; +4. pays Railiance from its own bank account on the settlement calendar; +5. may carry a published overdue balance up to its credit limit. + +### 4.3 Binky Hedgehog GmbH — umbrella + +The GmbH is the legal counterparty to external providers and banks until +that is deliberately changed. Profit-center accounts are internal +partitions of that legal reality. The future Operational Knowledge GmbH +name does not, by itself, change procurement authority, entity IDs, or +these rates. + +### 4.4 Human financial authority + +Only a human may: + +- open or close entity bank accounts; +- change markup, interest, credit-limit, or payment-term parameters; +- approve a provider contract or a commitment that binds the GmbH; +- grant an entity a non-default credit limit; +- waive interest or write off an internal balance; +- suspend or restore an entity's consumption. + +--- + +## 5. How resource-control operates + +These rules are the organizational change this version introduces. + +### 5.1 Association is mandatory + +Every record that estimates, observes, allocates, or evaluates cost or +usage carries: + +| Field | Meaning | +| --- | --- | +| `financial_entity_id` | The consuming entity that will bear the transfer price. Required on forecasts, usage observations, allocations, expense evaluations, and settlement lines. | +| `procuring_entity_id` | The entity that pays the external provider. V0.1 default: `entity:railiance`. | + +Inventory records carry both. A dedicated resource used by one center has +that center as `financial_entity_id`. A shared resource has +`entity:railiance` as procuring entity and an allocation method that +produces per-consumer shares, each tagged with a consuming +`financial_entity_id`. + +No inventory item, forecast, actual, allocation, optimization case, or +variance row may be published without a consuming entity or an explicit +unattributed gap. + +### 5.2 Two money views, never mixed + +For each resource and period, `resource-control` keeps three figures +separate: + +| Figure | Definition | Authority | +| --- | --- | --- | +| **Delivered cost** | What it cost Railiance to provide the resource in the period. See [§ 8](#8-delivered-cost). | Reconstructed here from fin-hub booked facts plus allocation and labor evidence. | +| **Transfer price** | Delivered cost × (1 + markup), except Railiance self-consumption. See [§ 9](#9-transfer-price). | Computed here; proposed to fin-hub. | +| **Booked fact** | What was posted as a provider invoice, credit, tax line, or (later) an internal settlement posting. | `fin-hub` only. | + +A forecast is not a transfer price. A transfer price is not a booked +payment. Variance is explained against the figure that was actually +predicted. + +### 5.3 Control loop with entities + +The existing loop is unchanged in stages and now closed per entity: + +```text +demand[entity] → estimate[entity] → compare → approve → procure[Railiance] + → commission → allocate[entity] → monitor[entity] + → evaluate expense[entity] → settle[entity → Railiance] + → apply credit state[entity] → optimize → renew / migrate / retire +``` + +Monthly cadence already defined in `docs/portfolio-operating-cadence.md` +gains one output: a **settlement statement** per consuming entity, plus a +credit-state evaluation that Railiance operations can enforce. + +### 5.4 What this repository will not do + +Unchanged from `INTENT.md`, restated so these terms cannot be read as a +license to exceed it: + +- no contract signature, no payment, no DATEV booking; +- no provider or banking credentials in this repository; +- no customer invoicing (external customers remain a fin-hub / commercial + concern); +- no silent approval of consumption above a restricted allowance. + +--- + +## 6. Resource classes in scope + +In scope when procured or managed by Railiance for any financial entity: + +- compute instances and cluster capacity +- object, block, and backup storage +- network, ingress, egress, and connectivity +- domains, DNS, and certificates +- intelligence: commercial model APIs, reserved weights, inference hosts +- databases and managed data services +- shared platform services and self-managed services on rented capacity +- licenses required to run the above + +Out of scope for these terms (tracked elsewhere, typically Binky / fin-hub): + +- office rent and non-IT company overhead +- Steuerberater and statutory accounting fees +- banking plan fees, except when a fee is the direct cost of a + resource-specific payment instrument +- founder-private cards and uncleared Auslagen, until they are booked to + an entity and a resource + +A cost that is out of scope must not be laundered into a Railiance transfer +price. + +--- + +## 7. Association, allocation, and identity + +### 7.1 Join keys + +The common join already required by `INTENT.md` is extended, not replaced: + +- `resource_id` +- `financial_entity_id` **(new, required)** +- `procuring_entity_id` **(new, default `entity:railiance`)** +- `service_id`, `workload_id`, `tenant_id`, `environment` +- `cost_attribution_key` +- provider account, accounting period, source evidence + +`tenant_id` remains a workload/tenancy key. It is not the profit-center +key. Mapping from tenant or workload to `financial_entity_id` is an +explicit table, not a string prefix rule. + +### 7.2 Dedicated versus shared + +- **Dedicated.** One consuming entity. Delivered cost of the resource in + the period is that entity's cost. Transfer price follows [§ 9](#9-transfer-price). +- **Shared.** Railiance procures. An allocation driver (already required + by the portfolio model) splits delivered cost across consuming entities + **before** markup. Each share is then marked up independently. +- **Unattributed.** No transfer price is issued. The cost remains visible + as a Railiance residual and as a coverage defect. It is not spread by + convenience. + +### 7.3 Railiance self-use + +Capacity Railiance uses to deliver the platform (control plane, forge used +as a production tool of Railiance, cluster system pods, backup of +Railiance's own state) is consumed by `entity:railiance` at delivered cost. +No markup. That cost may later be allocated *into* a shared driver that +other entities pay; it is not marked up twice. + +--- + +## 8. Delivered cost + +**Delivered cost** is the amount it cost Railiance to provide a resource +(or an allocated share) in the accounting period, in EUR. + +V0.1 cost base, when known: + +| Component | Included | Source | +| --- | --- | --- | +| Provider infrastructure charges | yes | fin-hub booked facts joined to `resource_id` | +| Usage, egress, request, and minimum charges | yes | same | +| Provider credits and discounts | yes, as reductions | fin-hub corrections | +| Tax | as treated by fin-hub; never reconstructed here | fin-hub `tax_status` | +| External services required to deliver the resource | yes | booked facts or priced evidence | +| Attributable Railiance operations labor | yes, at the current internal labor rate | resource-control labor evidence | +| Setup / migration in the period it is recognized | yes | forecast and actual setup evidence | +| Internal markup | **no** — applied after cost | this document | +| Corporate overhead of Binky (desk, StB, …) | **no** | out of scope | +| Uncertainty / missing price | recorded as unknown, not as zero | existing portfolio rule | + +Missing components stay `null`. A transfer price is issued only for the +**known** portion of delivered cost, and the statement labels the unknown +remainder. Inventing a complete price from a partial base is forbidden. + +Currency is EUR. Other currencies are converted only by fin-hub; this +repository does not imply a rate. + +--- + +## 9. Transfer price + +### 9.1 Rule + +For a consuming entity other than Railiance: + +```text +transfer_price = delivered_cost × (1 + markup_rate) +``` + +V0.1 `markup_rate` = **0.20** (cost plus 20 %). + +For `entity:railiance` as consumer: + +```text +transfer_price = delivered_cost +``` + +Markup is Railiance's internal margin for procurement and management. It is +the same rate for every consuming entity and every in-scope resource class +unless a later version publishes a class-specific or entity-specific +exception. + +### 9.2 What the 20 % covers + +The markup is Railiance's compensation for: + +- holding the provider relationship and payment timing risk; +- managing the resource; +- providing monthly usage evidence and settlement; +- extending the credit facility in [§ 11](#11-credit-interest-and-restricted-consumption). + +It is not a customer margin, not a tax, and not a license to hide +unallocated cost. Unallocated cost stays unallocated. + +### 9.3 Estimates + +Forecasts and procurement comparisons show, per consuming entity: + +- estimated delivered cost (low / base / high as today); +- estimated transfer price (same scenarios, markup applied); +- estimated effect on the entity's credit headroom. + +A decision that only quotes provider list price is incomplete under these +terms. + +--- + +## 10. Settlement + +### 10.1 Period and statement + +- Accounting period: calendar month `M`. +- `resource-control` closes usage, allocations, and delivered-cost + reconstruction in the first week of `M+1`, on the existing monthly + observation cadence. +- It then issues one **settlement statement** per consuming entity that + has any charge, credit, interest, or open balance. + +Statement contents (minimum): + +- `financial_entity_id`, period, statement date, due date +- line items: `resource_id`, usage summary, delivered cost by component, + markup, transfer price +- known-cost total, unknown-cost remainder +- prior outstanding, payments recognized (as projected from fin-hub), + interest for the period, new transfer charges, new outstanding +- credit limit, headroom, consumption mode (`open` or `restricted`) +- restricted new-consumption allowance for the coming month, if applicable +- Railiance pay-to account reference (non-secret) +- consuming entity pay-from account reference (non-secret) + +### 10.2 Payment terms + +- Settlement is **monthly**. +- The statement is payable **within 10 calendar days** of the statement + date. +- Payment is from the consuming entity's bank account to the Railiance + bank account. +- If the statement is issued late, the due date follows the statement + date, not month-end. Consumers are not punished for a late close. + +Recognized payment is a fin-hub fact (or a human-confirmed bank evidence +projection). `resource-control` does not declare a payment from a chat +message or an unverified screenshot. + +### 10.3 Railiance self-settlement + +Railiance's own consumption at cost is recorded for P&L completeness. It +does not generate a payment instruction to itself. + +--- + +## 11. Credit, interest, and restricted consumption + +This facility is internal working capital from Railiance to the other +centers. It is not a bank loan and not an external credit line. + +### 11.1 Parameters (V0.1 default) + +| Parameter | Default | Notes | +| --- | --- | --- | +| Credit limit | **€1 000.00** | Per consuming entity. A named entity may be granted a different limit by human financial authority. | +| Payment term | **10 calendar days** | After statement date. | +| Extension | **unlimited in time** | An overdue balance is not time-barred by these terms. | +| Interest | **5 % per year** | Applied to overdue outstanding. See open question OQ-1. | +| Interest convention | simple, monthly | `interest = overdue × 0.05 / 12` at each subsequent month-end close, on the overdue principal (and previously capitalized interest if any remains unpaid). | +| Restricted monthly consumption | **€50.00** transfer price | Applies when outstanding ≥ credit limit. | +| Restricted allowance | `max(0, 50.00 − interest_this_month)` | New resource consumption, not a waiver of interest. | + +Railiance as self-consumer has no credit limit under these terms. +External provider credit is a provider-contract concern. + +### 11.2 When a balance is overdue + +A statement amount not recognized as paid by the due date becomes +**overdue outstanding**. Interest starts the following calendar day and is +quantified at the next monthly close using the monthly convention above. +There is no additional late fee in V0.1. + +### 11.3 Credit limit as a consumption trigger + +The credit limit is a **consumption-control threshold**, not a legal debt +ceiling. + +When `outstanding ≥ credit_limit` at evaluation time, the entity enters +**restricted consumption** for the next operating month: + +```text +new_transfer_charges_allowed = + max(0, restricted_monthly_consumption − interest_this_month) +``` + +Worked default at a €1 000.00 overdue balance: + +```text +interest_this_month = 1000.00 × 0.05 / 12 = 4.17 +new_transfer_charges_allowed = max(0, 50.00 − 4.17) = 45.83 +``` + +That €45.83 is transfer price, so delivered cost that may be newly +consumed is `45.83 / 1.20 = 38.19` (Railiance self-use is not in this +mode). + +Interest continues to accrue for as long as any overdue amount remains. +These terms do not set a maximum duration. + +If the entity pays down below the limit, the next evaluation returns it to +`open` consumption. Partial payment first reduces interest, then overdue +principal (V0.1 convention; accountants may supersede). + +### 11.4 Enforcement + +`resource-control` publishes the consumption mode and the remaining +allowance. It does not throttle a cluster. + +Enforcement is operational: + +- Railiance platform / procurement refuses or defers **new** orders that + would exceed the allowance; +- elastic usage that would exceed the allowance is rate-limited or + rejected where the platform can do so; +- already-committed provider contracts (annual domains, committed VMs) are + not silently cancelled — they are flagged to human financial authority + if they would breach the allowance; +- shared-platform system safety (backups, identity, ingress needed to + keep an already-running service from data loss) may continue, and the + overage is recorded as an exception, not hidden. + +A restricted entity that nevertheless accrues more than the allowance +creates an **exception line** on the next statement and stays restricted. + +### 11.5 Waivers and limit changes + +Only human financial authority may raise a limit, lower a limit, waive +interest, or grant a temporary unrestricted window. The grant is a dated +decision record; `resource-control` stores the resulting limit, not the +conversation that produced it. + +--- + +## 12. Banking + +Each financial entity will have its own bank account or a dedicated +partition of the GmbH's banking (for example a Qonto account or +sub-account). V0.1 requirements: + +- `resource-control` stores only non-secret account references + (`account_ref`), never credentials or payment instruments. +- Provider charges for in-scope resources are paid from the **Railiance** + account. +- Internal settlement is paid from the **consuming entity** account to + the **Railiance** account. +- Binky may continue to hold the legal banking organization. That does + not make Binky the procuring entity for IT resources. +- Until an entity's account exists, charges may be computed and + statements issued, but payment recognition stays `unknown` and the + entity's credit state is reported rather than pretended to be settled. + +Opening the accounts is human / banking work. It is a dependency of +live settlement, not of adopting the association rules. + +--- + +## 13. Authority boundaries + +| Concern | Authoritative party | +| --- | --- | +| These terms, rates, limits | Human financial authority; this file is the published text | +| Resource identity, usage, allocation, forecasts, transfer-price calculation, credit-state evaluation | `resource-control` | +| Booked provider cost, tax, currency, budgets, runway, recognized payments | `fin-hub` | +| Provisioning, telemetry, enforcement of restricted consumption | Railiance platform / cluster / hosts repos | +| Demand and service requirements | Owning workload repositories | +| Provider contracts, bank execution, limit waivers | Human financial authority | +| Credentials | Approved OpenBao / credential-broker lanes | + +This document does not amend +`docs/fin-hub-resource-control-contract-v0.1.md`. Internal transfer prices +are a new planning/settlement artifact that fin-hub may later book. Until +that exchange exists, statements here are proposed charges with +provenance, not booked spend. + +--- + +## 14. Default parameters + +All amounts EUR. Changing a row without changing a principle is still a +terms revision (V0.1.1 or V0.2) so historical statements remain auditable +against the version that produced them. + +| ID | Parameter | V0.1 value | +| --- | --- | --- | +| P1 | Markup on delivered cost (non-Railiance consumers) | 20 % | +| P2 | Markup on Railiance self-consumption | 0 % | +| P3 | Settlement period | calendar month | +| P4 | Statement issue | first week of the following month | +| P5 | Payment term | 10 calendar days from statement date | +| P6 | Interest rate | 5 % per annum | +| P7 | Interest convention | simple monthly, `rate / 12` on overdue outstanding | +| P8 | Default credit limit | 1 000.00 | +| P9 | Restricted monthly consumption cap | 50.00 transfer price | +| P10 | Restricted allowance | `max(0, P9 − monthly interest)` | +| P11 | Credit-limit meaning | consumption trigger, not a legal cap | +| P12 | Overdue duration | unlimited under these terms | +| P13 | Currency | EUR | +| P14 | Procuring entity | `entity:railiance` | +| P15 | Labor rate used in delivered cost | the rate already used by `resource-control` cost models; not redefined here | + +--- + +## 15. Worked examples + +Figures are illustrative. They use V0.1 parameters and two-decimal money. + +### 15.1 Ordinary month + +Coulomb's allocated August delivered cost is €200.00 (known). No prior +balance. + +```text +transfer_price = 200.00 × 1.20 = 240.00 +statement_date = 2026-09-01 +due_date = 2026-09-11 +outstanding = 240.00 +credit_headroom = 1000.00 − 240.00 = 760.00 +consumption_mode = open +``` + +Coulomb pays €240.00 from its account to Railiance on 2026-09-08. +Recognized payment clears the balance. Interest is zero. + +### 15.2 Extended payment + +Same statement. No payment arrives by 2026-09-11. + +At the September close the €240.00 is overdue. Monthly interest: + +```text +interest = 240.00 × 0.05 / 12 = 1.00 +``` + +If Coulomb also consumed €100.00 delivered cost in September +(€120.00 transfer price) and still has not paid: + +```text +new_outstanding = 240.00 + 1.00 + 120.00 = 361.00 +consumption_mode = open # still below €1 000 +``` + +Interest continues each month until the overdue amount is paid. There is +no automatic write-off. + +### 15.3 Default limit reached + +Helixforge has €1 000.00 overdue outstanding at month-end. + +```text +interest_this_month = 1000.00 × 0.05 / 12 = 4.17 +new_transfer_charges_allowed = max(0, 50.00 − 4.17) = 45.83 +max_new_delivered_cost = 45.83 / 1.20 = 38.19 +consumption_mode = restricted +``` + +If Helixforge consumes exactly that allowance and pays nothing: + +```text +new_outstanding = 1000.00 + 4.17 + 45.83 = 1050.00 +``` + +The balance may exceed the limit by restricted-month charges. The entity +stays restricted. If instead it pays €200.00, outstanding falls to +€850.00 plus any new allowed charges, and the next evaluation can return +it to `open`. + +--- + +## 16. Adoption in resource-control + +V0.1 is in force as operating policy once this file is published. Schema +and inventory adoption follows; until then, association is required in +new evidence prose and in any new record that can already carry an owner +or tenant, and is an explicit gap on historical records that cannot. + +Adoption work (not completed by publishing this file): + +1. Add `financial_entity_id` and `procuring_entity_id` to inventory, + planning-evidence, and control-cycle schemas. +2. Publish a versioned entity register (the table in [§ 3](#3-financial-entities)) + as data, not only as prose. +3. Backfill current `data/resources/` records with procuring and consuming + entities; leave unknown where evidence is missing. +4. Extend monthly cadence to emit per-entity settlement statements and + credit-state evaluations. +5. Extend the fin-hub exchange so proposed transfer charges and recognized + internal payments can be reconciled without becoming a second ledger. +6. Give Railiance operations a consumption-mode signal they can enforce. + +Those steps should become a workplan rather than remaining only in this +list. + +--- + +## 17. Open questions for later versions + +| ID | Question | V0.1 stance | +| --- | --- | --- | +| OQ-1 | Is 5 % interest annual or monthly? Annual is the V0.1 reading (commercial convention). Monthly 5 % would zero the €50 allowance at the default €1 000 limit (`1000 × 0.05 = 50`). Confirm. | 5 % per annum | +| OQ-2 | Should committed provider terms (domains, reserved instances) be cancellable automatically in restricted mode? | No; flag for human decision | +| OQ-3 | Should markup apply to labor, or only to provider cash cost? | Labor is in delivered cost, therefore marked up | +| OQ-4 | Should Binky, as umbrella, pay markup to Railiance, or receive platform services at cost? | Binky pays markup; elimination is accounting | +| OQ-5 | What is Frontier's commercial mandate, and does it consume a distinct intelligence class? | Entity exists; mandate is out of scope here | +| OQ-6 | When a center is incorporated separately, do these terms become a written supply agreement with USt? | Requires StB / legal review | +| OQ-7 | Payment waterfall if a payment does not cover interest + principal? | Interest first, then principal | +| OQ-8 | Daily versus monthly interest accrual? | Monthly close is enough for V0.1 | +| OQ-9 | Default limit per entity, or a group limit? | Per consuming entity | +| OQ-10 | Does Railiance mark up pass-through domains and LLM APIs at the same 20 %? | Yes, one rate until a class exception is published | + +--- + +## 18. Change control + +- A new version is a new heading in this file or a successor file that + names the version it replaces. +- Statements and forecasts must record the terms version that produced + them. Later versions do not rewrite historical transfer prices. +- Parameter-only changes increment the minor label (V0.1.1). Principle or + entity-set changes increment the minor or major label (V0.2 / V1.0). +- Human financial authority approves versions that change P1–P12. +- Editorial clarification without numeric or role change may land as a + dated note under the current version. + +--- + +## 19. Related documents + +| Document | Relationship | +| --- | --- | +| `INTENT.md` | Control-plane purpose; these terms specialize entity association and internal charging | +| `SCOPE.md` | Repository boundary; in-scope work now includes entity-associated settlement evidence | +| `docs/fin-hub-resource-control-contract-v0.1.md` | Authority split with fin-hub; not amended | +| `docs/portfolio-operating-cadence.md` | Monthly observation cadence that will emit settlement statements | +| `docs/forecast-actual-control.md` | Forecast immutability and variance; transfer prices follow the same append-only rule | +| `binky-control/INTENT.md` | Umbrella company purpose and Operational Knowledge GmbH rename | +| `binky-control/EcosystemMap.md` | Pillar descriptions for Coulomb, Net Kingdom, Railiance, Helixforge | + +--- + +## 20. Document history + +| Version | Date | Change | +| --- | --- | --- | +| V0.1 | 2026-08-14 | Initial baseline: six financial entities; Railiance procures and manages; cost plus 20 %; monthly settlement; 10-day payment; 5 % p.a. interest with unlimited extension; €1 000 default credit limit; restricted consumption €50/month minus monthly interest. | diff --git a/docs/portfolio-operating-cadence.md b/docs/portfolio-operating-cadence.md index 8504295..5e20e64 100644 --- a/docs/portfolio-operating-cadence.md +++ b/docs/portfolio-operating-cadence.md @@ -42,6 +42,7 @@ reason, rather than being silently omitted from the ratios. | Rhythm | When | Inputs | Consumers | Output | |---|---|---|---|---| | **Monthly observation** | First week, for the closed month | Monthly actual records from delegated telemetry; booked costs from `fin-hub` | resource-control | `tools/control_cycle.py` variance per resource; a new optimization case where variance is attributed to demand, price, or allocation rather than data quality | +| **Monthly settlement** | With the observation, once entity association is live | Per-entity usage, delivered cost, transfer prices under `docs/TermsOfResourceProcurement.md`; recognized payments from `fin-hub` | consuming financial entities; Railiance operations; `fin-hub` | One settlement statement and credit-state evaluation (`open` or `restricted`) per consuming entity | | **Monthly portfolio report** | With the observation | Resource records, coverage, optimization cases | Human operator; owning repositories | `make portfolio-report`; the `next_actions` list is re-sent to the repositories named in it | | **Quarterly calibration** | End of quarter | Three months of variance | resource-control; `fin-hub` | Forecast revisions per `docs/forecast-actual-control.md` — revisions, never overwrites; refreshed provider prices in every open case | | **Pre-renewal review** | At least 60 days before the earliest `renews_on` or `cancel_by` | Contract evidence, utilization, open cases | Human financial authority | A `renewal` case, decided while cancellation is still possible | diff --git a/workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md b/workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md new file mode 100644 index 0000000..c93a1b8 --- /dev/null +++ b/workplans/RESOURCE-WP-0004-financial-entity-procurement-terms.md @@ -0,0 +1,136 @@ +--- +id: RESOURCE-WP-0004 +type: workplan +title: "Adopt financial-entity procurement terms" +domain: financials +repo: resource-control +status: active +owner: grok +topic_slug: railiance +created: "2026-08-14" +updated: "2026-08-14" +related: + - RESOURCE-WP-0003 + - FIN-WP-0004 +state_hub_workstream_id: "9d8a0f1b-468b-4e0e-b139-b5f8b1d42d03" +--- + +# RESOURCE-WP-0004 — adopt financial-entity procurement terms + +## Goal + +Make `docs/TermsOfResourceProcurement.md` V0.1 operational: every expense, +estimate, usage observation, and expense evaluation is associated with one of +Binky, Frontier, Railiance, Netkingdom, Helixforge, or Coulomb. Railiance +remains the procuring entity. Transfer prices, monthly settlement, and +credit-state evaluation follow those terms without becoming a second booked +ledger. + +## Boundaries + +- `resource-control` owns entity association, delivered-cost reconstruction, + transfer-price calculation, settlement statements, and credit-state + evaluation. +- `fin-hub` owns booked facts, recognized payments, tax, and any later + posting of internal settlement. +- Railiance platform repos enforce restricted consumption; this repo only + publishes the signal. +- Human financial authority approves parameter changes, account opening, + and limit waivers. +- Schema changes must remain compatible with + `docs/fin-hub-resource-control-contract-v0.1.md`. + +## T01 — Publish Terms of Resource Procurement V0.1 + +```task +id: RESOURCE-WP-0004-T01 +status: done +priority: high +state_hub_task_id: "7b2d73e6-f610-45bb-8391-61d6c480a5b9" +``` + +Write `docs/TermsOfResourceProcurement.md` V0.1 covering the six financial +entities, Railiance as procuring manager, cost plus 20 %, monthly settlement +payable in 10 days, 5 % p.a. interest with unlimited extension, €1 000 +default credit limit, and restricted consumption of €50/month reduced by +monthly interest. Point `INTENT.md`, `SCOPE.md`, and the portfolio cadence +at the terms. + +Done when the terms file is in `docs/` and the repo canon references it. + +Completed 2026-08-14: V0.1 published; INTENT, SCOPE, and monthly cadence +updated. + +## T02 — Entity register and schema association + +```task +id: RESOURCE-WP-0004-T02 +status: todo +priority: high +state_hub_task_id: "18576e8e-c159-42a1-88f1-61434c1fd298" +``` + +Add a versioned entity register for the six IDs. Extend inventory, +planning-evidence, and control-cycle schemas with `financial_entity_id` and +`procuring_entity_id`. Unknown remains explicit. Do not invent a default +entity. + +Done when validators reject new cost-bearing records that lack both an +entity and an explicit unattributed gap, and tests cover the six IDs plus +Railiance self-consumption (zero markup). + +## T03 — Backfill the live portfolio + +```task +id: RESOURCE-WP-0004-T03 +status: todo +priority: high +state_hub_task_id: "f15d552d-62ac-46fa-89e5-34218a1b65d2" +``` + +Tag current `data/resources/` records with procuring and consuming entities +from source evidence. Map `tenant:coulomb` to `entity:coulomb`, +`tenant:friendly:binky` / `rapp-qonto` to `entity:binky`, `helix-forge` to +`entity:helixforge`, and Railiance platform resources to +`entity:railiance` as procurer with allocated consumers where a driver +exists. + +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. + +## T04 — Settlement statements and credit state + +```task +id: RESOURCE-WP-0004-T04 +status: todo +priority: medium +state_hub_task_id: "0546dd87-bc8f-41ea-a4a6-b60a031e9bf6" +``` + +Define a settlement-statement artifact and compute monthly transfer prices, +overdue interest, credit headroom, and `open` / `restricted` mode from +Terms V0.1 parameters. Include worked-example fixtures for ordinary +settlement, extended payment, and the default-limit restriction. + +Done when a tool can emit one statement per consuming entity from committed +evidence and the restricted allowance matches +`max(0, 50.00 − monthly_interest)`. + +## T05 — Fin-hub and Railiance handoff + +```task +id: RESOURCE-WP-0004-T05 +status: todo +priority: medium +state_hub_task_id: "874151e0-4b34-426b-a2b9-f836df3265c8" +``` + +Propose the exchange additions fin-hub needs to recognize internal transfer +charges and payments without taking resource authority, and the +consumption-mode signal Railiance operations needs to enforce restricted +use. Hand off as work records in those repos. Do not book settlement in +this repository. + +Done when the handoff records exist and this repo documents the join keys +it will publish.