45 — Forgeyard Cost Accounting, FinOps, Chargeback/Showback & Resource Economics System Architecture
Document type: Core Cost Attribution, FinOps, Budgeting, Showback/Chargeback, Forecasting & Resource Economics System Architecture
Project: Forgeyard CI/CD
Subsystem: raw resource metering, cost attribution, provider pricing, internal cost models, tenant/project/workload allocation, budgets, forecasts, anomalies, showback, chargeback, unit economics, cost-aware optimization inputs, storage/network/device cost, release/deployment cost, plugin/external-service cost, and financial reporting
Architecture style: Raw usage first, pricing second, immutable attribution facts, explainable cost allocation, provider-neutral normalization, strong separation from billing authority, no cost-based correctness downgrade, and policy-governed optimization
Status: Target production architecture extending the Forgeyard series beyond the original 01–26 plan
Relationship to prior work: Builds on Multi-Tenancy/Quotas, Entitlements/Billing, Runner Fleet Autoscaling, Scheduler, CAS, Observability, Device Lab, Deployment, Search/Analytics, Dependency Governance, Notifications, and Audit. This subsystem explains what Forgeyard costs to operate and where that cost comes from without turning accounting into execution authority.
1. Purpose
Forgeyard can consume substantial resources:
CPU
memory
GPU
runner hours
macOS hosts
device lab time
CAS/object storage
logs
network egress
database usage
external scanners
SCM/provider API usage
release distribution
deployment infrastructure
Operators and organizations need answers such as:
what did this project cost this month?
which pipelines consume the most compute?
how much does a release cost?
how much does a cache hit save?
which runner pools are underutilized?
which tenant causes most egress?
what is the cost per successful build?
what will next month likely cost?
The central rule is:
Forgeyard records raw resource usage independently from price. Cost is a derived, versioned interpretation of immutable usage facts.
A second rule is:
Cost accounting and customer billing are separate domains. Cost facts may inform billing, but Forgeyard must never confuse provider cost, internal transfer price, subscription price, or invoice amount.
A third rule is:
Cost-aware scheduling or autoscaling may choose among semantically equivalent eligible options, but cost can never justify weaker isolation, weaker trust, missing tests, stale evidence, or policy bypass.
2. Architectural Position
Resource Consumption
┌──────────────┼──────────────┐
▼ ▼ ▼
Runners CAS Network
│ │ │
└──────────────┼──────────────┘
▼
Usage Records
│
▼
Attribution Engine
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Provider Cost Internal Cost Transfer Price
│ │ │
└──────────────┼──────────────┘
▼
Cost Facts
│
┌─────────┼─────────┐
▼ ▼ ▼
Showback Budget Optimization
3. Goals
The subsystem MUST:
- normalize raw resource usage;
- attribute usage to tenant/project/run/job;
- attribute storage consumption;
- attribute network consumption;
- attribute runner time;
- attribute GPU/device usage;
- attribute external-service usage;
- support provider pricing snapshots;
- support internal cost models;
- support cost allocation;
- support shared-cost allocation;
- support showback;
- support chargeback exports;
- support budgets;
- support forecast;
- support anomaly detection;
- support unit economics;
- support cost-aware optimization inputs;
- support historical pricing;
- support pricing corrections;
- support multi-currency normalization;
- support tenant isolation;
- support API/UI/CLI;
- support notifications;
- support audit for admin changes;
- support standalone mode;
- support distributed mode;
- support reconciliation;
- support DR;
- remain separate from invoice authority.
4. Non-Goals
This subsystem does not:
replace accounting software
issue invoices by itself
define subscription plans
become tax/accounting ledger authority
override scheduler hard constraints
replace provider invoices
5. Workspace Structure
crates/cost/
├── forgeyard-cost/
├── forgeyard-cost-model/
├── forgeyard-cost-metering/
├── forgeyard-cost-attribution/
├── forgeyard-cost-pricing/
├── forgeyard-cost-allocation/
├── forgeyard-cost-budget/
├── forgeyard-cost-forecast/
├── forgeyard-cost-anomaly/
├── forgeyard-cost-unit-economics/
├── forgeyard-cost-export/
├── forgeyard-cost-health/
└── forgeyard-cost-testkit/
Provider pricing adapters:
crates/cost-providers/
├── forgeyard-cost-aws/
├── forgeyard-cost-azure/
├── forgeyard-cost-gcp/
├── forgeyard-cost-neon/
├── forgeyard-cost-object-store/
├── forgeyard-cost-custom/
└── ...
Use modules first; split only where provider SDK dependencies justify.
6. Raw Usage Principle
Record usage independently from price.
Example:
Runner CPUSeconds = 420
MemoryByteSeconds = ...
GpuSeconds = ...
not:
cost = $0.37
as primary fact.
7. UsageRecordId
#![allow(unused)]
fn main() {
pub struct UsageRecordId(Ulid);
}8. Usage Record
#![allow(unused)]
fn main() {
pub struct UsageRecord {
pub id: UsageRecordId,
pub tenant: TenantId,
pub project: Option<ProjectId>,
pub subject: UsageSubject,
pub dimension: UsageDimension,
pub quantity: UsageQuantity,
pub occurred_at: TimeRange,
pub source: UsageSource,
}
}9. Usage Subject
#![allow(unused)]
fn main() {
pub enum UsageSubject {
Run(RunId),
Job(JobId),
Attempt(JobAttemptId),
Runner(RunnerId),
Device(DeviceId),
Artifact(ArtifactId),
Deployment(DeploymentId),
Release(ReleaseId),
Tenant(TenantId),
System,
}
}10. Usage Dimension
#![allow(unused)]
fn main() {
pub enum UsageDimension {
CpuSeconds,
MemoryByteSeconds,
GpuSeconds,
RunnerSeconds,
DeviceSeconds,
StorageByteHours,
LogByteHours,
NetworkEgressBytes,
NetworkIngressBytes,
ApiRequests,
ProviderOperations,
ExternalScannerSeconds,
DatabaseComputeSeconds,
Custom(UsageDimensionId),
}
}11. Usage Quantity
Strongly typed.
12. No Raw Floating Point for Money
Critical.
13. Decimal Money
Use decimal/fixed precision.
14. Currency
#![allow(unused)]
fn main() {
pub struct Money {
pub amount: Decimal,
pub currency: CurrencyCode,
}
}15. PricingSnapshotId
#![allow(unused)]
fn main() {
pub struct PricingSnapshotId(Digest);
}16. Pricing Snapshot
Immutable versioned pricing data.
17. Pricing Source
#![allow(unused)]
fn main() {
pub enum PricingSource {
ProviderPublished,
ContractedRate,
InternalRateCard,
ManualAdministrative,
}
}18. Provider Published Price
May differ from actual invoice.
19. Contracted Rate
Organization-specific.
20. Internal Rate Card
For transfer/showback.
21. Cost Interpretation
#![allow(unused)]
fn main() {
pub struct CostInterpretation {
pub usage: UsageRecordId,
pub pricing: PricingSnapshotId,
pub amount: Money,
pub model: CostModelId,
}
}22. Historical Stability
If provider pricing changes tomorrow, yesterday’s historical cost interpretation stays tied to old snapshot.
23. Repricing
Can create new interpretation, never rewrite raw usage.
24. Cost Model
#![allow(unused)]
fn main() {
pub enum CostModel {
DirectProvider,
InternalFullyLoaded,
TransferPrice,
Custom(CostModelId),
}
}25. DirectProvider
Estimated/raw provider cost.
26. FullyLoaded
Can include:
compute
storage
network
reserved capacity
shared control plane allocation
27. Transfer Price
Internal organizational accounting.
28. Customer Price
Not here.
Part 30 billing/entitlement domain.
29. Usage Attribution
Every metered activity should map to:
tenant
project
run/job if applicable
resource class
30. Runner Compute Attribution
Use actual attempt occupancy.
31. Example
If job runs 60 seconds on 4 vCPU capacity:
record based on chosen accounting semantics:
reserved vCPU-seconds
or
measured CPU-seconds
32. Reserved vs Actual
Keep separate dimensions.
33. Why
Reserved resources reflect capacity cost.
Actual CPU reflects workload efficiency.
34. Runner Usage Class
#![allow(unused)]
fn main() {
pub enum ComputeUsageClass {
Reserved,
Measured,
}
}35. Job Queue Time
Not compute cost.
36. Idle Runner
Fleet/system cost.
37. Idle Cost Attribution
Options:
fleet overhead
tenant dedicated pool
organization shared cost
38. Allocation Policy
Versioned.
39. SharedCostAllocationId
#![allow(unused)]
fn main() {
pub struct SharedCostAllocationId(Digest);
}40. Shared Cost Examples
idle warm pool
control plane
shared DB
shared cache
41. Allocation Methods
#![allow(unused)]
fn main() {
pub enum SharedCostAllocationMethod {
Direct,
Equal,
ProportionalUsage,
Weighted,
Unallocated,
}
}42. Unallocated
Valid and honest.
43. Do Not Force False Precision
Critical.
44. CAS Storage Cost
Raw facts:
logical referenced bytes
physical stored bytes
retention duration
45. Tenant Accounting
Use logical referenced bytes for fair attribution when physical CAS dedup exists.
46. Provider Cost
Physical storage bytes.
47. Distinction
Important.
48. Cross-Tenant Dedup
Can reduce provider cost without reducing tenant logical usage.
49. Cache Storage
Separate from durable artifact storage.
50. Cache Eviction Savings
Derived estimate.
51. Logs
Meter retained log bytes/time.
52. Network
Attribute egress to:
artifact download
runner CAS transfer
release download
provider traffic
where measurable.
53. Ingress
Often free provider-side, but still raw usage.
54. Device Cost
Physical device lab:
device minutes
host runner minutes
external lab fees
55. GPU
GPU seconds/capacity hours.
56. macOS Capacity
Often high fixed cost.
Track dedicated host idle/used separately.
57. External Services
Examples:
security scanner
email provider
SMS/push
artifact signing/KMS
SCM premium API
device farm
58. ExternalServiceUsage
#![allow(unused)]
fn main() {
pub struct ExternalServiceUsage {
pub provider: ExternalServiceId,
pub operation: ExternalOperationKind,
pub quantity: UsageQuantity,
}
}59. Provider API Request Cost
Only if financially material.
60. Database Cost
Neon/Postgres provider usage can be allocated.
61. Database Shared Cost
Usually not precisely attributable per query.
62. Allocation
Use:
tenant storage
transaction count
active usage
or unallocated shared
with explicit method.
63. Cost Attribution Confidence
#![allow(unused)]
fn main() {
pub enum AttributionConfidence {
Exact,
Measured,
Estimated,
Allocated,
Unknown,
}
}64. Every Cost Fact
Carries confidence.
65. Exact
Provider line item or exact direct rate.
66. Measured
Usage measured, price known.
67. Estimated
Approximation.
68. Allocated
Shared cost apportioned.
69. Unknown
Do not fabricate.
70. CostFact
#![allow(unused)]
fn main() {
pub struct CostFact {
pub id: CostFactId,
pub subject: CostSubject,
pub period: TimeRange,
pub amount: Money,
pub confidence: AttributionConfidence,
pub pricing: PricingSnapshotId,
}
}71. CostFactId
Content-derived or stable immutable.
72. Period
Hour/day/month etc.
73. Rollups
Derived:
hourly
daily
monthly
74. Raw Usage Retained
So rollups can rebuild.
75. Cost Corrections
Provider bills may differ.
76. Correction
Append adjustment.
77. Never Rewrite Historical Usage
Critical.
78. CostAdjustment
#![allow(unused)]
fn main() {
pub struct CostAdjustment {
pub original: CostFactId,
pub delta: Money,
pub reason: CostAdjustmentReason,
}
}79. Provider Invoice Reconciliation
Optional.
80. Import Provider Invoice
Can compare expected vs billed.
81. Billing Provider Connector
Separate adapter.
82. Provider Invoice Is External Source
Not execution authority.
83. Showback
Displays cost without internal financial transfer.
84. Chargeback
Exports allocated cost for internal accounting.
85. ChargebackExportId
#![allow(unused)]
fn main() {
pub struct ChargebackExportId(Digest);
}86. Export Formats
CSV
JSON
RON
87. Accounting Integration
Future plugin/export adapter.
88. No General Ledger Built Into Core
Critical.
89. Budget
#![allow(unused)]
fn main() {
pub struct CostBudget {
pub id: CostBudgetId,
pub scope: ResourceScope,
pub period: BudgetPeriod,
pub amount: Money,
pub action: BudgetAction,
}
}90. Budget Period
daily
monthly
quarterly
custom
91. Budget Action
#![allow(unused)]
fn main() {
pub enum BudgetAction {
Notify,
RequireApproval,
LimitOptionalCapacity,
HardBlockNewOptionalWork,
}
}92. Security-Critical Work
Should not be silently disabled by budget.
93. Hard Budget
Policy-defined.
94. Example
Block new non-production benchmark jobs after budget.
95. Existing Running Jobs
Normally continue.
96. Budget vs Quota
Quota:
resource usage limit
Budget:
financial limit
97. No Duplicate Quota Engine
Budget can feed governance/policy.
98. Cost Guardrail
Part 43 fleet cost guardrail.
99. Integration
Part 45 produces cost estimate/pricing inputs.
100. Budget Utilization
#![allow(unused)]
fn main() {
pub struct BudgetUtilization {
pub budget: CostBudgetId,
pub spent: Money,
pub forecast: Option<Money>,
}
}101. Forecast
Derived.
102. Forecast Model
Baseline simple:
run rate
historical seasonality
known reservations
103. ForecastModelVersion
Versioned.
104. Forecast Confidence
Explicit.
105. No Guaranteed Forecast
Critical.
106. Cost Anomaly
Detect sudden deviations.
107. CostAnomalyId
#![allow(unused)]
fn main() {
pub struct CostAnomalyId(Ulid);
}108. Anomaly Inputs
historical baseline
current usage
pricing changes
resource class
109. Baseline
Deterministic/statistical.
110. No ML Required
111. Anomaly Confidence
Explicit.
112. Common Anomalies
runaway runner fleet
unexpected egress
log explosion
cache storage spike
GPU overuse
device farm surge
113. Notification
Part 29.
114. Kill/Scale Response
Never automatic baseline for expensive but valid work.
115. Policy
Can automate safe responses, e.g.:
freeze optional fleet scale-up
116. Unit Economics
Examples:
cost per successful Run
cost per build minute
cost per release
cost per deployment
cost per active project
cost per tenant
117. UnitMetricId
#![allow(unused)]
fn main() {
pub struct UnitMetricId(BoundedString);
}118. Unit Metric Formula
Versioned.
119. Denominator
Explicit.
120. Example
monthly CI cost / successful Runs
121. Failed Runs
Can be separate.
122. Retry Waste
Cost attributed to actual usage.
123. Infrastructure Waste
Existing Part 27 InfrastructureWaste.
124. Cost Classification
#![allow(unused)]
fn main() {
pub enum CostUsageClass {
UserWork,
Retry,
InfrastructureWaste,
SystemMaintenance,
IdleCapacity,
}
}125. Useful for Optimization
126. Cache Savings
Estimate:
counterfactual execution cost
127. Counterfactual
Must be labeled estimated.
128. No Claim Exact Savings
Critical.
129. Monorepo Incremental Savings
Likewise estimated.
130. Fleet Optimization
Cost facts can inform:
warm pool size
spot mix
region choice
131. Hard Constraint
Only among eligible equivalent options.
132. Scheduler Cost Signal
#![allow(unused)]
fn main() {
pub struct CostPreference {
pub relative_cost: Decimal,
pub snapshot: PricingSnapshotId,
}
}133. Scheduler
Soft score only.
134. Trust/Security First
Hard filter before cost.
135. Autoscaler
Can compare eligible fleets by cost.
136. Cost Staleness
Pricing snapshot age.
137. Stale Price
Can use last-known for estimates, marked stale.
138. Never Block Correctness Because Price API Down
Critical.
139. Provider Pricing Fetch
External asynchronous process.
140. Web Search Not Runtime Requirement
Provider APIs/files/config preferred.
141. Pricing Reconciler
Refresh snapshots.
142. Manual Contract Pricing
Admin input.
143. Sensitive Contract Rates
Restricted access.
144. Cost Permissions
cost.read
cost.admin
budget.manage
pricing.manage
chargeback.export
145. Tenant View
Own cost only.
146. System Admin
Cross-tenant aggregated.
147. Confidentiality
Cost data may reveal infrastructure/use patterns.
148. API
Potential:
GET /v1/cost/summary
GET /v1/cost/by-project
GET /v1/cost/by-run
GET /v1/cost/budgets
POST /v1/cost/budgets
GET /v1/cost/forecast
GET /v1/cost/anomalies
149. Query Scope
Tenant-scoped/authz.
150. Dioxus UI
Pages:
Cost Overview
Projects
Runners
Storage
Network
Budgets
Forecast
Anomalies
Unit Economics
151. Run Detail
Can show estimated/actual resource cost.
152. Job Detail
Compute cost.
153. Release Detail
Aggregate:
build
test
package
sign
distribution
154. Deployment Detail
Deployment-control cost may be small; target infrastructure cost may come from external provider integration.
155. Confidence Badge
Always visible.
156. Currency
Display selected/local reporting currency.
157. Multi-Currency
Store source currency + conversion snapshot.
158. FxRateSnapshotId
#![allow(unused)]
fn main() {
pub struct FxRateSnapshotId(Digest);
}159. FX
Derived reporting only.
160. Historical FX
Immutable snapshot.
161. No Live FX for historical rewrite
Critical.
162. Base Reporting Currency
Configurable.
163. Cost Export
Include:
raw usage refs
pricing snapshot
allocation method
confidence
for auditability.
164. Search/Analytics
Part 31 may power query UX, but canonical cost facts remain Part 45.
165. Cost Analytics
Materialized rollups.
166. Observability Metrics
cost_usage_records_total
cost_attribution_failures_total
cost_pricing_snapshot_age_seconds
cost_budget_exceeded_total
cost_anomalies_open
167. Avoid Monetary Values as high-cardinality metrics.
168. Tracing
cost.meter
cost.attribute
cost.price
cost.rollup
cost.forecast
cost.reconcile
169. Health
Checks:
metering lag
pricing freshness
allocation backlog
provider reconciliation
170. Doctor
forgeyard cost doctor
171. Doctor Checks
missing pricing
unattributed usage
currency mismatch
budget config
provider pricing auth
172. Unattributed Usage
First-class.
173. CostAttributionState
#![allow(unused)]
fn main() {
pub enum CostAttributionState {
Attributed,
PartiallyAttributed,
Unattributed,
Unknown,
}
}174. Never Silently Drop Unattributed Cost
Critical.
175. Shared System Cost
Can remain unallocated.
176. Reconciliation
Metering events are at-least-once.
177. Usage Dedup Key
Source resource + time bucket + dimension + sequence where applicable.
178. Idempotent Ingestion
Critical.
179. Runner Metering
Attempt lifecycle is authoritative for reserved time.
180. Measured Host Metrics
Observability source can supplement actual CPU/memory.
181. Metrics Are Not Authority for Job identity
Use Run/Job/Attempt IDs.
182. CAS Storage Metering
Periodic snapshot/reconciliation.
183. Storage Byte-Hours
Integrate over time.
184. Deletion
Stops future accumulation.
185. Release-Retained Artifacts
Cost attributed according to retention policy.
186. Network Metering
Provider/object-store reports can reconcile.
187. Provider Bill Reconciliation
Compare internal estimate.
188. Variance
#![allow(unused)]
fn main() {
pub struct ProviderCostVariance {
pub expected: Money,
pub billed: Money,
pub difference: Money,
}
}189. Large Variance
Anomaly.
190. Entitlement/Billing Integration
Part 30 raw billable usage may reuse/consume usage records.
191. Important Separation
provider cost
internal cost
billable usage
customer price
invoice amount
all distinct.
192. No Customer Invoice From Provider Cost Automatically
Critical.
193. Standalone Mode
Can estimate local machine resource usage.
194. Local Hardware Cost
Optional internal configured rate.
195. Default
Usage-only if no cost model configured.
196. Distributed Mode
Full cost attribution.
197. Air-Gap
No provider pricing fetch required.
Use manual/internal rate cards.
198. Cost Snapshot Export
Can move into air-gap.
199. DR
Raw usage + budgets + pricing snapshots backed up.
200. Derived rollups can rebuild.
201. Audit
Audit:
pricing model change
budget change
allocation rule change
manual cost adjustment
chargeback export
202. Routine usage records
Not audit every one.
203. Notification
Examples:
budget 80%
budget exceeded
forecast exceeds budget
cost anomaly
provider pricing stale
204. Budget Thresholds
50%
80%
100%
120%
configurable.
205. Quiet Hours
Critical budget alerts may bypass depending policy.
206. Cost Policy
Can constrain:
optional benchmark
preview environment
fleet max
retention
207. Security Baseline
Never remove:
authz
TLS
audit
secret protection
tenant isolation
for cost.
208. Release Gates
Do not fail security release because budget unless explicit business policy.
209. Emergency Security Release
Can bypass budget with audited exception.
210. Budget Exception
Use central PolicyException/break-glass semantics.
211. Cost Forecast Inputs
historical usage
scheduled reservations
known releases
fleet min/warm
retention trends
212. Forecast Output
#![allow(unused)]
fn main() {
pub struct CostForecast {
pub scope: ResourceScope,
pub period: TimeRange,
pub expected: Money,
pub lower: Option<Money>,
pub upper: Option<Money>,
pub confidence: ForecastConfidence,
}
}213. Forecast Confidence
#![allow(unused)]
fn main() {
pub enum ForecastConfidence {
Low,
Medium,
High,
}
}214. No False Exactness
Critical.
215. Budget Forecast Gate
Can warn before actual exceed.
216. Cost Anomaly Model
Simple baseline:
rolling median/mean
seasonality bands
absolute threshold
217. Provider Price Change
Should not be misclassified as usage anomaly if explainable.
218. Decompose
usage change
price change
allocation change
219. Cost Explainability
forgeyard cost explain.
220. Example
Project A cost increased 28%
- GPU seconds +15%
- price +5%
- log retention +8%
221. No Opaque Score
Critical.
222. CLI
forgeyard cost summary
forgeyard cost project <id>
forgeyard cost run <id>
forgeyard cost budget list
forgeyard cost forecast
forgeyard cost anomalies
forgeyard cost explain
forgeyard cost export
223. Machine Output
JSON/RON.
224. Cost Data Retention
Raw usage long enough for audit/repricing.
225. Provider Invoice Data
Sensitive.
226. Access Control
Restricted.
227. Cost Data Classification
#![allow(unused)]
fn main() {
pub enum CostDataClass {
Internal,
Sensitive,
Restricted,
}
}228. Multi-Tenant Export
Never cross-tenant by default.
229. Cost Model Version
#![allow(unused)]
fn main() {
pub struct CostModelVersion(u16);
}230. Allocation Version
#![allow(unused)]
fn main() {
pub struct AllocationModelVersion(u16);
}231. Reprocessing
Old usage can be repriced/reallocated under a new model.
232. Original Reports
Preserved.
233. Restatement
New view, not historical mutation.
234. Financial Period Close
Optional.
235. Closed Period
Freeze official internal chargeback view.
236. Correction
Append adjustment.
237. Not Accounting Ledger
Still keep boundary clear.
238. Testkit
forgeyard-cost-testkit/src/
├── lib.rs
├── usage.rs
├── attribution.rs
├── pricing.rs
├── allocation.rs
├── budget.rs
├── forecast.rs
└── assertions.rs
239. Unit Tests
Money/currency precision.
240. Usage Dedup Test
Duplicate events do not double-charge.
241. Runner Attribution Test
Attempt duration attributed correctly.
242. Idle Cost Test
Shared allocation explicit.
243. CAS Dedup Test
Logical tenant bytes != physical provider bytes.
244. Pricing Snapshot Test
Historical cost remains tied to exact rate.
245. Repricing Test
Creates new interpretation.
246. Currency Test
Historical FX snapshot.
247. Budget Test
Threshold/forecast.
248. Quota Separation Test
Budget does not alter quota logic directly.
249. Cost-Aware Scheduler Test
Only soft score among equivalent candidates.
250. Security Constraint Test
Cheaper untrusted runner never selected over required trust.
251. Region Residency Test
Cheaper disallowed region rejected.
252. Unattributed Usage Test
Visible, not dropped.
253. Provider Invoice Variance Test
Reconciled.
254. Cost Correction Test
Append adjustment.
255. Tenant Isolation Test
No cross-tenant cost visibility.
256. DR Test
Raw usage/pricing/budgets restored.
257. Forecast Test
Confidence explicit.
258. Anomaly Decomposition Test
Price vs usage change.
259. Fuzzing
Fuzz cost/pricing import parsers.
260. Property Tests
Sum of allocated portions <= or == source shared cost according to method.
261. Scale Test
Billions of usage records via rollup/partition strategy.
262. Implementation Phase 1 — Raw Usage Model
Compute/storage/network.
263. Phase 2 — Cost Attribution
Run/job/project/tenant.
264. Phase 3 — Pricing Snapshots
Manual/provider.
265. Phase 4 — Showback
UI/API.
266. Phase 5 — Budgets/Notifications
Governance.
267. Phase 6 — Fleet/Scheduler Cost Signals
Optimization.
268. Phase 7 — Shared Cost Allocation
Fully loaded views.
269. Phase 8 — Forecast/Anomaly
Operations.
270. Phase 9 — Provider Invoice Reconciliation
Accuracy.
271. Phase 10 — Chargeback Export
Enterprise.
272. Phase 11 — Multi-Currency/Air-Gap
Global deployments.
273. Phase 12 — Scale/Fuzz/DR Hardening
Production readiness.
274. Acceptance Tests
- Raw usage is stored independently from price.
- Usage records are immutable/idempotent.
- Every usage record is tenant scoped.
- Cost interpretation references exact pricing snapshot.
- Historical pricing is never silently rewritten.
- Repricing creates a new interpretation.
- Provider cost, internal cost, transfer price, and customer price remain distinct.
- Reserved and measured compute usage remain distinct.
- Idle capacity cost is explicitly allocated or left unallocated.
- CAS logical tenant usage is separate from physical provider storage.
- Attribution confidence is explicit.
- Unattributed usage is visible.
- Provider invoice variance is recorded rather than hidden.
- Budget and quota remain separate concepts.
- Budgets cannot silently remove security controls.
- Cost-aware scheduling only ranks already-eligible candidates.
- Cheaper capacity cannot bypass trust/residency/platform requirements.
- Cost API outage cannot stop correct execution.
- Pricing staleness is visible.
- Forecast confidence is explicit.
- Cost anomalies distinguish price, usage, and allocation changes.
- Cache/incremental “savings” are labeled estimates.
- Chargeback exports include attribution/pricing provenance.
- Cost corrections append adjustments.
- Tenant A cannot read Tenant B costs.
- Sensitive contract pricing is restricted.
- Standalone can work in usage-only mode.
- Air-gapped deployments can use manual rate cards.
- Raw usage/pricing/budget state survives DR.
- Derived rollups can rebuild.
- Entitlement billing can consume usage without conflating internal cost.
- Audit covers pricing/budget/allocation admin changes.
- Standalone/distributed share cost semantics.
- Cost views are explainable down to usage facts.
- Forgeyard dogfoods cost accounting to understand its own CI resource economics.
275. Production Readiness Gates
Do not call FinOps architecture production-ready until:
usage dedup/attribution is stable
money/currency precision is tested
pricing snapshots are immutable
tenant isolation passes
unattributed usage is surfaced
budget/quota separation is enforced
cost-aware scheduler/fleet integrations remain soft-only
provider invoice variance path works
DR/repricing tests pass
large-scale rollups perform acceptably
276. Architectural Invariants
- raw usage precedes pricing;
- usage is immutable/idempotent;
- pricing is versioned;
- historical costs bind exact pricing snapshots;
- repricing does not rewrite raw usage;
- provider/internal/transfer/customer pricing are separate domains;
- reserved and measured resource usage are separate;
- shared cost allocation is explicit/versioned;
- unknown/unallocated cost is permitted;
- false precision is avoided;
- cost confidence is explicit;
- tenant cost data is isolated;
- budget is not quota;
- budget does not weaken security baseline;
- cost influences only equivalent safe execution choices;
- cost cannot bypass scheduler hard filters;
- cost cannot bypass residency/trust/policy;
- pricing API outage does not block correctness;
- stale pricing is visible;
- forecast is advisory;
- anomalies are explainable;
- cache savings are estimated/counterfactual;
- billing/customer invoices remain Part 30/external accounting;
- corrections append adjustments;
- raw usage supports rebuilding rollups;
- provider invoice data is external evidence;
- air-gap can operate with manual rate cards;
- standalone/distributed share semantics;
- admin cost model changes are audited;
- Forgeyard dogfoods its own cost system.
277. Final Target Architecture
Resource Consumption
│
▼
Usage Records
│
▼
Attribution
│
┌────────────┼────────────┐
▼ ▼ ▼
Pricing Snapshot Allocation Confidence
│ │ │
└────────────┼────────────┘
▼
Cost Fact
│
┌────────────┼────────────┐
▼ ▼ ▼
Showback Budget Forecast
│ │ │
└────────────┼────────────┘
▼
Optional Optimization
278. Final Architectural Position
Cost derivation:
immutable UsageRecord
+
immutable PricingSnapshot
+
versioned AllocationModel
↓
CostFact
Budget:
CostFacts
+
Budget
+
Forecast
↓
notify / approval / optional-work guardrail
Scheduler/autoscaler:
hard eligibility
↓
equivalent safe candidates
↓
cost preference
↓
soft ranking only
The key guarantee is:
Forgeyard can explain where infrastructure money goes without letting financial optimization corrupt CI/CD semantics. Costs are derived from immutable usage and pricing evidence, shared allocations are explicit, uncertainty is visible, and cheaper infrastructure is considered only after security, trust, platform, policy, tenant, and correctness requirements have already been satisfied.
279. Extended Architecture Sequence
01 Core Domain & Foundation
02 Storage & Metadata
03 CAS & Artifact Data Plane
04 Pipeline IR / Parsing / Planning
05 Run / Job State Machine
06 Scheduler
07 Runner / Agent
08 Sandbox & Executor
09 Transport / QUIC / Protocol
10 Events / Reconciliation
11 Policy / Authorization / Identity
12 Secrets & Trust
13 Supply Chain / SBOM / Provenance / Signing
14 Packaging
15 Release
16 Deployment
17 Observability / Health / Doctor
18 API / Axum
19 Dioxus UI
20 Device Lab
21 SCM Provider Integrations
22 HA / Coordination / Raft
23 RBE Interop
24 Plugin / Extension Architecture
25 Operations / Backup / Upgrade / DR
26 Self-Hosting / Bootstrap / Release of Forgeyard
27 Multi-Tenancy / Quotas / Resource Governance
28 Audit / Compliance / Evidence Retention / Security Governance
29 Notifications / Alerting / Human Workflow
30 Entitlements / Licensing / Subscription / Commercial Access Control
31 Search / Indexing / Query / Operational Analytics
32 Test Results / Quality Gates / Coverage / Flaky-Test Intelligence
33 Benchmarking / Performance Regression / Load-Test / Capacity Intelligence
34 Monorepo Intelligence / Dependency Graph / Affected-Change / Incremental Execution
35 Developer Experience / Local Dev Environment / CLI Workflows / Reproducible Workstation
36 Dependency / Package Registry / Artifact Mirror / Software-Source Governance
37 Static Analysis / Code Quality / Security Scanning / Findings Management
38 Cache / Build Acceleration / Remote Cache / Cache Correctness
39 Configuration / Feature Flags / Runtime Settings / Dynamic Configuration Governance
40 Security Architecture / Threat Model / Hardening / Incident Response
41 Release Distribution / Update Delivery / Installer / Channel / Client Update
42 Workflow Templates / Reusable Pipelines / Organization Standards / Golden Paths
43 Runner Fleet Autoscaling / Capacity Provisioning / Infrastructure Providers
44 Pipeline Triggers / Schedules / Manual Dispatch / Event-Driven Execution
45 Cost Accounting / FinOps / Chargeback / Showback / Resource Economics