Draft resource cost authority contract
This commit is contained in:
parent
8338c501ed
commit
2895077b8c
4 changed files with 170 additions and 5 deletions
|
|
@ -2,11 +2,22 @@
|
|||
# Custodian Brief — fin-hub
|
||||
|
||||
**Domain:** financials
|
||||
**Last synced:** 2026-08-10 18:42 UTC
|
||||
**Last synced:** 2026-08-10 18:44 UTC
|
||||
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
|
||||
|
||||
## Active Workstreams
|
||||
|
||||
### Establish the resource cost evidence contract
|
||||
Progress: 0/6 done | workplan_id: `67b6de6c-4820-4478-9789-f50260204c27`
|
||||
|
||||
**Open tasks:**
|
||||
- ► T01 — Review and record the authority boundary `6616e6a0`
|
||||
- · T02 — Specify fin-hub to resource-control booked-cost evidence `0a90dd6f`
|
||||
- · T03 — Specify resource-control to fin-hub planning evidence `ad9dccb4`
|
||||
- · T04 — Expose budgets, commitments, and viability constraints `3620fc2a`
|
||||
- · T05 — Implement and reconcile the first round trip `9a411734`
|
||||
- · T06 — Generalize and operate the contract `a1309d51`
|
||||
|
||||
### Client attribution and billing basis
|
||||
Progress: 3/6 done | workplan_id: `ebc1d2de-ae11-4cde-b860-047922fc74b9`
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@
|
|||
| workplan | FIN-WP-0001 | finished | — | workplans/FIN-WP-0001-runway-operations-lane.md |
|
||||
| workplan | FIN-WP-0002 | active | — | workplans/FIN-WP-0002-client-attribution-and-billing-basis.md |
|
||||
| workplan | FIN-WP-0003 | proposed | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
|
||||
| workplan | FIN-WP-0004 | proposed | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| workplan | FIN-WP-0004 | active | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| task | FIN-WP-0000-T01 | done | — | workplans/FIN-WP-0000-repo-integration.md |
|
||||
| task | FIN-WP-0000-T02 | done | — | workplans/FIN-WP-0000-repo-integration.md |
|
||||
| task | FIN-WP-0000-T03 | done | — | workplans/FIN-WP-0000-repo-integration.md |
|
||||
|
|
@ -32,7 +32,7 @@
|
|||
| task | FIN-WP-0003-T01 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
|
||||
| task | FIN-WP-0003-T02 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
|
||||
| task | FIN-WP-0003-T03 | todo | — | workplans/FIN-WP-0003-fabric-authority-boundary.md |
|
||||
| task | FIN-WP-0004-T01 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| task | FIN-WP-0004-T01 | progress | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| task | FIN-WP-0004-T02 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| task | FIN-WP-0004-T03 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
| task | FIN-WP-0004-T04 | todo | — | workplans/FIN-WP-0004-resource-cost-evidence-contract.md |
|
||||
|
|
|
|||
147
docs/fin-resource-authority-contract-v0.1.md
Normal file
147
docs/fin-resource-authority-contract-v0.1.md
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
# Fin-hub ↔ resource-control authority contract v0.1
|
||||
|
||||
Status: draft for joint review
|
||||
Owners: `fin-hub` / `resource-control`
|
||||
Workplans: `FIN-WP-0004-T01`, `RESOURCE-WP-0003-T02`
|
||||
|
||||
## Boundary
|
||||
|
||||
One observed amount may appear in both systems, but only as an authoritative
|
||||
financial fact in fin-hub and as a referenced projection used for technical
|
||||
analysis in resource-control. Resource-control never posts a forecast,
|
||||
allocation, estimate, or variance as booked spend. Fin-hub never invents
|
||||
resource identity, technical utilization, or allocation-driver evidence.
|
||||
|
||||
Customer billing basis is separate from both provider booked cost and
|
||||
technical allocation. Fin-hub may compute it from authoritative price and
|
||||
cost evidence, but legal invoices, bookkeeping, and payments stay external.
|
||||
|
||||
## Authority matrix
|
||||
|
||||
| Concept | Authoritative writer | Consumer/projection | Rule |
|
||||
| --- | --- | --- | --- |
|
||||
| Provider invoice or booked-cost row | fin-hub | resource-control | Immutable source identity; corrections reference the prior fact. |
|
||||
| Credit, discount, tax, net/gross treatment | fin-hub | resource-control | Never reconstructed from resource-control estimates. |
|
||||
| Budget, financial commitment, burn, runway | fin-hub | resource-control | Exported as dated constraints/signals, not copied ledgers. |
|
||||
| Engagement price and customer margin | fin-hub | reporting/export consumers | A price is not an invoice or payment. |
|
||||
| Resource and provider-resource identity | resource-control | fin-hub | Stable external references; fin-hub does not own the catalog. |
|
||||
| Workload/tenant/resource relationships | resource-control, sourced from owning workload/platform repos | fin-hub | Unknown relationships remain explicit. |
|
||||
| Technical usage and utilization | resource-control, sourced from platform telemetry | fin-hub | Observation period and evidence provenance are required. |
|
||||
| Allocation method, driver and result | resource-control | fin-hub | Allocation never becomes booked cost; totals reconcile to referenced facts. |
|
||||
| Demand/cost forecast and uncertainty | resource-control | fin-hub | Immutable versions; never represented as actual spend. |
|
||||
| Optimization scenario or commitment candidate | resource-control | fin-hub/human authority | Candidate only until approved and recorded by fin-hub/human authority. |
|
||||
| Legal commitment approval | human financial authority | both | Neither service may approve contractual terms. |
|
||||
|
||||
## Shared identifiers
|
||||
|
||||
Exchange records use opaque strings. Each producer validates its own native
|
||||
identifier and consumers preserve it byte-for-byte.
|
||||
|
||||
- `financial_fact_id`: fin-hub identity for a booked cost, credit, or
|
||||
correction.
|
||||
- `resource_id`: resource-control identity (`resource:…`).
|
||||
- `provider_resource_id`: provider-native reference when non-secret.
|
||||
- `service_id`, `workload_id`, `tenant_id`, `environment`: optional join axes;
|
||||
absence is represented as `null`, never an invented placeholder.
|
||||
- `cost_attribution_key`: an external join key. Client workloads use fin-hub's
|
||||
validated `client:<id>|app:<id>|instance:<id>` form; infrastructure-wide
|
||||
keys owned by resource-control retain their own versioned namespace.
|
||||
|
||||
`cost_attribution_key` is not globally sufficient identity. Every financial
|
||||
exchange also carries `financial_fact_id`, period, currency, and provenance;
|
||||
every technical exchange carries its record ID and resource/workload context.
|
||||
|
||||
## Fin-hub → resource-control: booked-cost evidence
|
||||
|
||||
Minimum envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "0.1",
|
||||
"record_type": "booked_cost",
|
||||
"financial_fact_id": "opaque",
|
||||
"correction_of": null,
|
||||
"source_type": "provider_invoice",
|
||||
"provider": "opaque-provider-id",
|
||||
"provider_account_ref": null,
|
||||
"accounting_period": "YYYY-MM",
|
||||
"service_period_start": "YYYY-MM-DD",
|
||||
"service_period_end": "YYYY-MM-DD",
|
||||
"currency": "EUR",
|
||||
"net_amount": 0,
|
||||
"tax_amount": 0,
|
||||
"gross_amount": 0,
|
||||
"credit_amount": 0,
|
||||
"resource_id": null,
|
||||
"service_id": null,
|
||||
"workload_id": null,
|
||||
"tenant_id": null,
|
||||
"environment": null,
|
||||
"cost_attribution_key": null,
|
||||
"source_evidence_ref": "non-secret opaque reference",
|
||||
"recorded_at": "RFC3339 timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
Delivery is idempotent on `financial_fact_id`. Corrections append a new record
|
||||
with `correction_of`; consumers retain both and calculate the effective value.
|
||||
Unknown attribution stays null and remains visible in reconciliation.
|
||||
|
||||
## Resource-control → fin-hub: planning and allocation evidence
|
||||
|
||||
Minimum common envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "0.1",
|
||||
"record_type": "forecast|allocation|usage|optimization|commitment_candidate",
|
||||
"record_id": "opaque",
|
||||
"revision_of": null,
|
||||
"resource_id": "resource:opaque",
|
||||
"service_id": null,
|
||||
"workload_id": null,
|
||||
"tenant_id": null,
|
||||
"environment": "production",
|
||||
"cost_attribution_key": "opaque",
|
||||
"period_start": "YYYY-MM-DD",
|
||||
"period_end": "YYYY-MM-DD",
|
||||
"currency": "EUR",
|
||||
"scenario": "low|base|high|observed",
|
||||
"amount": 0,
|
||||
"uncertainty": null,
|
||||
"method": "versioned method identifier",
|
||||
"assumptions": [],
|
||||
"source_evidence": [],
|
||||
"created_at": "RFC3339 timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
Record-specific schemas add usage units, allocation drivers and shares,
|
||||
service constraints, or optimization-case economics. Delivery is idempotent
|
||||
on `record_id`; revisions are append-only. Fin-hub stores these as planning or
|
||||
analytical evidence and never in its booked-cost ledger.
|
||||
|
||||
## Reconciliation invariants
|
||||
|
||||
1. Each booked financial fact has exactly one authoritative fin-hub record.
|
||||
2. A resource-control allocation references the fact(s) it allocates and its
|
||||
shares plus explicit residual reconcile to the referenced effective total.
|
||||
3. Currency conversion is a separate, provenance-bearing transformation; no
|
||||
implicit conversion occurs during joins.
|
||||
4. Forecasts and commitment candidates cannot change burn, spend, or committed
|
||||
balances until the appropriate authority records the resulting fact.
|
||||
5. Duplicate delivery changes no totals. Corrections and revisions never
|
||||
overwrite their predecessors.
|
||||
6. Missing joins, unknown tax semantics, and unattributed residuals are
|
||||
observable data-quality states, not zero values.
|
||||
|
||||
## Review questions
|
||||
|
||||
- Should client attribution keys and infrastructure allocation keys share one
|
||||
namespaced grammar, or remain explicitly separate formats?
|
||||
- Which repository assigns `service_id` and `workload_id` where no workload
|
||||
repository already owns them?
|
||||
- Does resource-control's `actual` record type mean technical observation only,
|
||||
or should it be renamed to prevent confusion with fin-hub booked actuals?
|
||||
- Which transport and schema registry become canonical for v0.1 after the
|
||||
authority matrix is accepted?
|
||||
|
|
@ -4,7 +4,7 @@ type: workplan
|
|||
title: "Establish the resource cost evidence contract"
|
||||
domain: infotech
|
||||
repo: fin-hub
|
||||
status: proposed
|
||||
status: active
|
||||
owner: codex
|
||||
topic_slug: financials
|
||||
created: "2026-08-10"
|
||||
|
|
@ -38,7 +38,7 @@ only after both repository owners review the authority matrix.
|
|||
|
||||
```task
|
||||
id: FIN-WP-0004-T01
|
||||
status: todo
|
||||
status: progress
|
||||
priority: high
|
||||
state_hub_task_id: "6616e6a0-b0f3-4b82-a081-083891e2fb6e"
|
||||
```
|
||||
|
|
@ -59,6 +59,13 @@ Explicitly distinguish:
|
|||
Done when the boundary is reviewed jointly with `RESOURCE-WP-0003-T02` and
|
||||
there is no ambiguous ownership of a ledger, forecast, allocation, or resource.
|
||||
|
||||
Progress 2026-08-10: drafted
|
||||
`docs/fin-resource-authority-contract-v0.1.md` from both repositories' current
|
||||
models, resource schemas, forecast/actual controls, and workplans. The draft
|
||||
defines the authority matrix, directional envelopes, identifiers, correction
|
||||
and idempotency rules, reconciliation invariants, and four review questions.
|
||||
Joint resource-control review remains required before completion.
|
||||
|
||||
## T02 — Specify fin-hub to resource-control booked-cost evidence
|
||||
|
||||
```task
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue