Design governed-runner budget settlement receipt

[mdheller]

Purpose

Define a governed-runner budget settlement receipt for future v0.2+ runtime flows.

This is a design issue only. Do not implement budget settlement here.

Context

Governed-runner v0.1 includes budget estimates in GovernedRunContract and AttemptAdmissionReceipt, but it does not settle actual costs or resource consumption.

Any future execution surface needs a separate settlement record so estimates and actuals do not collapse into one ambiguous state.

Proposed scope

Define BudgetSettlementReceipt v0.1 to record:

• run id
• attempt id
• admission receipt ref
• estimated budget fields
• actual measured resource fields
• token/cost/tool-call counters when available
• estimate provenance
• settlement provenance
• overrun status
• fail-closed reason when settlement data is missing

Acceptance criteria

• Define BudgetSettlementReceipt v0.1 schema.
• Add positive fixture for settled synthetic attempt.
• Add negative fixture for missing admission receipt ref.
• Add negative fixture for missing actuals.
• Add negative fixture for negative cost/token counts.
• Add negative fixture for overrun hidden as successful settlement.
• Add validator and Makefile target.
• Add docs separating budget estimate, budget admission, and budget settlement.

Non-goals

• no live billing integration
• no provider API calls
• no actual token metering implementation
• no execution implementation
• no authority update
• no rollback restore

Boundary

This issue completes when schema, fixtures, validator, and documentation are ready. Runtime settlement integration must be separate.

[mdheller]

Completed by #209.

Merged commit: c73a8fb670e90b5c0f0e13bce50ed5c17495d8d2

Delivered:

• schemas/receipts/budget-settlement-receipt.v0.1.schema.json
• valid settled and overrun fixtures
• invalid fixtures for missing admission ref, missing actuals, negative actuals, and hidden overrun
• tools/validate_budget_settlement_receipt.py
• tools/tests/test_budget_settlement_receipt.py
• docs/runtime-governance/budget-settlement-receipt-v0.md
• validate-budget-settlement-receipt Makefile target

Boundary preserved: no live billing integration, provider API calls, token metering implementation, runtime execution, verifier execution, authority update, rollback restore, workspace mutation, or admission authority.