diff --git a/.custodian-brief.md b/.custodian-brief.md index 7e7050a..515f509 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -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` diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index dc51b2b..7b018d9 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -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 | diff --git a/docs/fin-resource-authority-contract-v0.1.md b/docs/fin-resource-authority-contract-v0.1.md new file mode 100644 index 0000000..99f56c3 --- /dev/null +++ b/docs/fin-resource-authority-contract-v0.1.md @@ -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:|app:|instance:` 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? diff --git a/workplans/FIN-WP-0004-resource-cost-evidence-contract.md b/workplans/FIN-WP-0004-resource-cost-evidence-contract.md index 08f2711..28da41e 100644 --- a/workplans/FIN-WP-0004-resource-cost-evidence-contract.md +++ b/workplans/FIN-WP-0004-resource-cost-evidence-contract.md @@ -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