Cost Governance

API reference for cost governance types defined by RFC-0004 — Cost Governance and Attribution. These types extend Pipeline.spec, AgentRole.spec, QualityGate.spec.gates[].rule, and provenance metadata to support declarative cost budgets, cost-based gating, cost-aware model selection, and per-artifact cost receipts.

All fields documented here are optional. RFC-0004 is a non-breaking extension — existing resources validate against updated schemas without modification, and implementations that don't support cost governance MAY ignore the new fields (though they SHOULD log a warning when present).

Import

import type {
  // Pipeline cost policy
  CostPolicy,
  ExecutionCostLimit,
  StageCostPolicy,
  StageCostLimit,
  CostThreshold,
  BudgetPolicy,
  BudgetAlert,
  AttributionPolicy,
  ModelPricingConfig,
  // Provenance cost receipt
  CostReceipt,
  CostBreakdown,
  ExecutionCostDetail,
} from '@ai-sdlc/reference';

CostPolicy

Per RFC-0004 §1, the optional costPolicy field on Pipeline.spec declares cost boundaries at three levels: per-execution, per-stage, and per-budget-period.

When a CostPolicy is present, the orchestrator MUST evaluate the limits in real time during agent execution per RFC-0004 §4 (Real-Time Cost Circuit Breaker), not only post-hoc. A missing costPolicy means no cost enforcement runs (current pre-RFC-0004 behavior).

Example

spec:
  costPolicy:
    perExecution:
      hardLimit: { amount: 100, currency: USD, action: abort }
    perStage:
      defaults:
        tokenLimit: 100000
        costLimit: { amount: 15, currency: USD, action: abort }
    budget:
      period: month
      amount: 5000
      currency: USD
      alerts:
        - threshold: 0.80
          action: require-approval
          approver: engineering-manager

ExecutionCostLimit

Per RFC-0004 §1, soft and hard ceilings for the entire pipeline execution.

When both are present, the soft limit MUST trigger first (i.e., softLimit.amount < hardLimit.amount). Implementations SHOULD reject configurations that violate this ordering.

CostThreshold

Per RFC-0004 §1, a single cost trigger with an action.

StageCostPolicy

Per RFC-0004 §1, per-stage cost ceilings with optional per-stage overrides.

When both are present, overrides[stageName] fields supersede defaults field-by-field (not whole-object replacement) so a stage can raise tokenLimit while inheriting the default costLimit.

StageCostLimit

Per RFC-0004 §1, the three independent ceilings any stage can carry.

Whichever ceiling trips first triggers the stage's onFailure policy. RFC-0004 §4 requires the orchestrator to monitor token consumption from each model API response and recompute running cost every 30 seconds (or every N API calls) so a runaway loop is interrupted before the bill arrives.

BudgetPolicy

Per RFC-0004 §1, a rolling budget window for a team or namespace, evaluated continuously by the CostReconciler.

The reconciler computes consumption = currentSpend / amount and walks alerts in declared order. Each alert fires at most once per budget period.

BudgetAlert

Per RFC-0004 §1, one threshold within a BudgetPolicy.

AttributionPolicy

Per RFC-0004 §1, how costs are tracked across dimensions and allocated for chargeback.

The orchestrator tags every cost data point with all configured dimensions so post-hoc analysis can group by any combination.

ModelPricingConfig

Per RFC-0004 §1, model price table used to convert token counts into monetary cost.

RFC-0004 deliberately does NOT bundle a pricing table in the spec — pricing changes frequently, and embedding it would force a spec revision every time a provider revised rates. Operators maintain models in their pipeline (or fetch it from the provider via an adapter).

Example

modelPricing:
  source: config
  models:
    claude-opus-4-6:
      inputPerMTok: 15.00
      outputPerMTok: 75.00
      cacheReadPerMTok: 1.50
    claude-sonnet-4-5:
      inputPerMTok: 3.00
      outputPerMTok: 15.00
      cacheReadPerMTok: 0.30
    claude-haiku-4-5:
      inputPerMTok: 0.80
      outputPerMTok: 4.00
      cacheReadPerMTok: 0.08

CostReceipt

Per RFC-0004 §5, the cost block appended to provenance metadata on every PR the orchestrator produces.

A CostReceipt is the auditable, per-artifact answer to "what did this PR cost?". Over time, the corpus of receipts is the dataset for answering "what does it cost to ship a feature at complexity tier N?" and "which model gives the best quality-per-dollar?".

CostBreakdown

Per RFC-0004 §5, itemized cost components within a CostReceipt.

humanReviewCost is the economically dominant term in most workflows — RFC-0004's motivation cites a $2 token cost vs $37.50 for 30 minutes of senior-engineer review time. Reporting it in the receipt makes that 95% of TCO visible instead of invisible.

ExecutionCostDetail

Per RFC-0004 §5, low-level execution metrics that feed cost calculation.

Implementations MUST populate inputTokens and outputTokens from the model API response metadata. The remaining fields are recommended for forensic analysis and cost-anomaly detection.

See also

• Tutorial: Cost Governance with CostPolicy — worked example walking a team through declaring costPolicy, budget, and modelSelection.
• Operator Runbook — Quota and cost events — operational response when a BudgetExceeded event fires.
• RFC-0004 — Cost Governance and Attribution — full normative spec, alternatives considered, open questions.