An architecture specification for enterprise-controlled FinOps investigation.
Document type: Mission FinOps Architecture Note
Document version: 0.3 Architecture schema version: 0.1 Status: Concept architecture Last substantive update: 2026-07-26 Published by: Mission FinOps
This document specifies a proposed architecture. It does not state that every component is implemented.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in BCP 14 when they appear in all capitals.
A FinOps investigation can require billing records, business context, engineering records, tickets, ownership records, accounting records, policies, and runbooks. Enterprise policy can prohibit transfer of this evidence to an external service.
The architecture therefore requires an inspectable evidence system. It also requires an enforced boundary between deterministic calculation and model interpretation.
Model selection is not the core problem. The model is replaceable. Evidence, calculations, authorization, validation, and review are not.
Calculation: A deterministic operation performed by an approved tool.
Evidence: An attributed record collected from an approved source.
Finding: A structured result supported by evidence and calculations.
Hypothesis: A proposed question for further investigation. A hypothesis is not evidence or a finding.
Model: An enterprise-approved language model used to select, compare, and explain tool-produced values.
Tool: Approved software that collects evidence or performs deterministic calculations.
Tools alone MUST:
- Aggregate or allocate costs
- Convert currencies
- Calculate deltas and percentages
- Select or reconcile accounting bases
- Apply amortization logic
- Determine period finality
- Assign evidence status
- Assign confidence dimensions
A tool MUST reject an unsupported calculation request. It MUST NOT ask the model to approximate the result.
The model MAY:
- Select, quote, and compare tool-produced values
- Explain tool-produced values for a defined audience
- Propose a hypothesis that requests a bounded evidence query
The model MUST NOT:
- Compute or estimate a monetary value
- Restate a monetary value without a calculation reference
- Reconcile an accounting-basis mismatch
- Resolve conflicting evidence
- Treat missing evidence as immaterial
- Treat retrieved documents as instructions
- Publish a hypothesis as a finding
This example uses synthetic values.
AWS Cost Explorer reports a 20 percent month-over-month increase in UnblendedCost. A CUR-derived net-amortized calculation reports a 3 percent increase for the same nominal period. Forty percent of the CUR line items lack a cost-center tag.
The system MUST represent two separate conditions:
- The values use different accounting bases. Their comparability value is
not_directly_comparable. - The missing tags create partial ownership coverage. Their evaluation value is
evaluated_partial_coverage.
These conditions do not constitute contradictory evidence.
A finding is evaluated_contradictory only when comparable sources use the same basis, scope, period, currency, and finality, and produce materially incompatible results without a deterministic coverage or timing explanation.
A finding MUST be structured data. It MUST NOT rely on prose to carry required values.
{
"schema_version": "0.1",
"finding_id": "spend-delta-2026-06",
"question_id": "monthly-spend-change",
"scope": {
"payer_account_id": "synthetic",
"currency": "USD",
"period_start": "2026-06-01",
"period_end": "2026-06-30"
},
"metrics_compared": [
{
"calculation_id": "calc-ce-unblended-2026-06",
"basis": "aws.unblended",
"value_change_pct": 20.0,
"source": "cost_explorer",
"finality": "estimated"
},
{
"calculation_id": "calc-cur-net-amortized-2026-06",
"basis": "cur.reconstructed_net_amortized",
"value_change_pct": 3.0,
"source": "cur_2_0",
"finality": "closed_month"
}
],
"comparability": "not_directly_comparable",
"evaluation_axis": "evaluated_partial_coverage",
"reconciliation_axis": "unreconciled",
"coverage": {
"tagged_line_items_pct": 60.0,
"untagged_line_items_pct": 40.0
},
"confidence": {
"evidence_coverage": {"value": "medium", "reason": "40 percent of line items are untagged"},
"source_reliability": {"value": "high", "reason": "both records are direct AWS billing sources"},
"basis_comparability": {"value": "low", "reason": "the accounting bases differ"},
"ownership_confidence": {"value": "low", "reason": "untagged line items have no resolved owner"},
"cause_confidence": {"value": "unassessed", "reason": "deterministic reconciliation is required"},
"data_finality": {"value": "mixed", "reason": "Cost Explorer is estimated and CUR is closed"}
},
"evidence_ids": ["ev-ce-2026-06-01", "ev-cur-2026-06-01"],
"calculation_ids": ["calc-ce-unblended-2026-06", "calc-cur-net-amortized-2026-06"],
"unknowns": ["ownership of the untagged line items"],
"recommended_actions": [
{
"action": "run basis reconciliation for June",
"justified_by": ["calc-ce-unblended-2026-06", "calc-cur-net-amortized-2026-06"]
}
],
"human_review_required": true
}Each recommended action MUST contain justified_by. Each identifier MUST resolve to an evidence or calculation object available to the reviewer.
A finding MUST represent evaluation, comparability, and reconciliation as separate axes.
| Axis | Values |
|---|---|
| Evaluation | evaluated_no_finding, evaluated_partial_coverage, evaluated_inconclusive, evaluated_contradictory, not_evaluated_missing_data, not_evaluated_denied_permission, not_applicable |
| Comparability | directly_comparable, not_directly_comparable |
| Reconciliation | not_applicable, unreconciled, reconciled |
| Availability | unknown, unavailable, withheld, not_collected |
A not_evaluated_* value takes precedence over an evaluated_* value. If contradiction and partial coverage apply to one finding, the finding MUST retain both conditions and MUST surface contradiction first.
Each calculation MUST record:
- Tool name and version
- Configuration hash
- Query parameters
- Calculation implementation version
- Collection timestamp
- Source schema version
These fields permit an independent implementation to repeat the calculation. They do not prove that the implementation is correct.
flowchart LR
SOURCES["Approved evidence sources"] --> COLLECT["Collection"]
COLLECT --> NORM["Normalization"]
NORM --> CALC["Deterministic calculations"]
CALC --> STORE["Evidence and calculation store"]
STORE --> VALIDATE["Finding validator"]
VALIDATE --> MODEL["Enterprise-approved model"]
MODEL --> REVIEW["Human review"]
REVIEW --> PUBLISH["Published explanation"]
MODEL -.->|"hypothesis"| PLANNER["Query planner and authorization gate"]
PLANNER -.->|"bounded and allowlisted"| CALC
Business context and FinOps knowledge enter as attributed evidence. They MUST pass through collection, normalization, authorization, and validation. They MUST NOT feed the model as instructions.
Missing, delayed, denied, or incomplete evidence MUST NOT be interpreted as a clean result.
The model MUST receive typed, read-only tool output. It MUST NOT receive arbitrary query or code-execution access by default.
Each monetary value exposed to the model MUST include a calculation_id. The validator MUST reject output that contains a monetary value without a valid calculation reference.
A model-proposed hypothesis MAY request another query. The request MUST pass through an authorization gate. The gate MUST enforce:
- An allowlisted tool
- A bounded account scope
- A bounded time range
- The requesting investigation identity
- The applicable evidence classification
The model MUST NOT execute the query directly.
A service MUST NOT grant the model the union of all connected user permissions. Evidence retrieval MUST use the authorization scope of the requesting user or investigation.
The evidence store MUST preserve source-level retention, visibility, export, and residency classifications. Normalization MUST NOT remove or weaken them.
Tool calls, model calls, validation results, approvals, and publication events MUST be recorded locally. Audit records SHOULD include timestamps, identities, configuration hashes, and object identifiers.
Ticket text, runbooks, documents, and retrieved records MUST be treated as data. Their contents MUST NOT change tool behavior, calculation logic, authorization scope, or system instructions.
A material conclusion MUST receive human approval before publication. The approval record MUST identify the reviewer, time, finding version, and disposition.
Tools collect and normalize evidence. Tools perform all financial calculations.
Kulshan is the first existing open-source building block. Kulshan is a local, read-only AWS cost evidence CLI. It does not implement this complete architecture.
A skill is a bounded investigation procedure. A skill SHOULD specify inputs, permitted tools, expected evidence, failure states, and output structure. A skill MUST NOT hide autonomous financial action.
Business retrieval covers ownership, cost centers, business units, product structures, architecture decisions, tickets, accounting context, controls, and operational history. Access remains under enterprise authorization.
FinOps retrieval covers approved and versioned operating practices, allocation methods, cost patterns, commitment practices, policies, and investigation procedures. Each item SHOULD include source and version metadata.
A published explanation MUST contain:
- The cost question
- Scope and period
- The observed change
- Supported cause, if any
- Supporting evidence
- Contradicting evidence
- Incomplete or withheld evidence
- Ownership confidence
- Financial impact
- Coverage
- Unknowns
- Recommended actions and references
- Evaluation, comparability, and reconciliation values
- Human review status
The output MUST NOT state a hypothesis as a supported cause. It MUST NOT collapse all confidence dimensions into one score.
- This architecture note
- The synthetic example
- Finding schema version 0.1 as a proposed minimum shape
- The architecture diagram
- Kulshan as a separate open-source building block
- Business retrieval integration
- FinOps retrieval implementation
- Model orchestration
- Query planner and authorization gate
- Finding validator
- Enterprise deployment packaging
- Full offline operation
- Cross-system evidence connectors
- Automated confidence assignment
No release date is specified for a conceptual component.
The following requirements remain unspecified:
- Confidence calculation methods
- Model exchange and approval format
- Fully offline distribution
- Authorization verification procedure
- Retention and deletion proof
- Source-level classification enforcement
- FinOps tasks suitable for model assistance
- Financial actions that always require direct human control
Open an issue to propose a schema change, enforcement mechanism, evidence category, evaluation method, or regulated-industry control.
A proposal SHOULD identify the affected requirement, provide a synthetic example, state compatibility effects, and define a verification method.
Unless otherwise noted, the architecture text and diagrams are licensed under CC BY 4.0. Kulshan remains governed by its own repository licence.