billingstore

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProviderJournalOrderMigrationName            = "20260830000000"
	ProviderJournalSequenceContractMigrationName = "20260830010000"
)
View Source 
const (

	// ReconciliationRecordSchemaLegacy is the original single-basis
	// reconciliation envelope.
	ReconciliationRecordSchemaLegacy uint32 = 1
	// ReconciliationRecordSchemaRetention is the full-result retention
	// envelope; its result payload is billing.ReconciliationRetentionResult.
	ReconciliationRecordSchemaRetention uint32 = 2
)
View Source 
const ALegReportScopeMigrationName = "20260925000000"
View Source 
const AuthorizationHoldsDropMigrationName = "20260825000000"

AuthorizationHoldsDropMigrationName is the guarded schema retirement for authorization_holds after open-hold inventory is empty.

View Source 
const BaselineMigrationName = "20260812000000"
View Source 
const BillingAccountingCutoverMigrationName = "20261002000000"

BillingAccountingCutoverMigrationName identifies the durable per-store accounting cutover marker (Task 17.3A, Migration Strategy step 6 foundation). One row per configured deployment/store boundary records the explicit accounting generation, monotonic version/epoch, active posting owner (V1/V2 writer lineage), and compatibility floor needed for later claim fencing (17.3B) and rollback checks (17.4). No terminal claim, worker, or admission wiring lives in this migration.

View Source 
const BillingAllocationMigrationName = "20260918000000"

BillingAllocationMigrationName identifies the additive immutable allocation history. Allocation rows are source-preserving derived economics, not money journal entries or provider request debits.

View Source 
const BillingAllocationTargetScopeMigrationName = "20260919000000"

BillingAllocationTargetScopeMigrationName identifies the forward repair for target-scope search projections. The canonical allocation and target JSON remain immutable authority; these columns only accelerate scoped queries and provide a consistency check for the canonical target subject.

View Source 
const BillingEconomicHeadOrderingMigrationName = "20261001000000"

BillingEconomicHeadOrderingMigrationName persists the durable current winning ordering tuple for allocation-aware selected heads.

Defect repaired: same observation plane compared incoming CreatedAt against the head's initial created_at_unix, while head UPDATE advanced only updated_at_unix. Sequence t1 -> t3 -> delayed t2 therefore regressed the authoritative pointer. Equal timestamps kept first arrival without a canonical tie-break.

Contract: the winning tuple is (winning CreatedAt nanos carried by updated_at_unix, derivation_hash, dependencies_hash, work_id). Larger CreatedAt wins; equal time uses total deterministic lexical tie-break (derivation, dependencies, work key), larger wins, consistent SQLite/PG and never arrival order. updated_at_unix already carries the winning work's CreatedAt; this migration adds the missing derivation identity columns and backfills them from durable valuations/work so every compared field is persisted and updated atomically on every transition.

View Source 
const BillingEconomicJobQueueMigrationName = "20260930000000"

BillingEconomicJobQueueMigrationName identifies the additive queue-state extension for revision-aware separated economic jobs: job kind, dependency count, bounded retry reason, terminal failure timestamp and the failed status.

View Source 
const BillingEconomicPostingIntentMigrationName = "20261004000000"

BillingEconomicPostingIntentMigrationName records explicit monetary posting intent for economic revision queue delivery state (Task 17.3 F2B).

Only provider-queue provider-rating work with valid B-leg lineage can create provider payable/cost/exclusion through the production EconomicRevisionWorker with a provider-cost adapter. The new columns record that narrow intent per delivery row so drain classification, counts, and claim gates never guess from queue name alone and never block evidence-only customer rating, reconciliation jobs, shadow observations/valuations, or queues without a posting adapter:

  • provider_posting INTEGER 0/1: 1 = monetary (drain counts/pins/gates), 0 = evidence-only (always operable).
  • posting_owner TEXT: "v1"/"v2" for monetary (stable owner, renewable epoch via pins), "" for evidence-only or legacy-inferred V1.

Legacy rows backfill provider_posting=1 where queue='provider' and work_kind='provider_rating' (the pre-F2B monetary inference); all other rows remain evidence-only. New enqueues set both columns explicitly at ensure time; the immutable work payload is unchanged for compatibility.

View Source 
const BillingEconomicRevisionHeadsMigrationName = "20260920000000"

BillingEconomicRevisionHeadsMigrationName identifies the additive durable current-head projection and mutable queue state for revision-keyed pure economics.

View Source 
const BillingEconomicsProjectionVersion = 1
View Source 
const BillingOperatorCursorKeyMigrationName = "20260930000002"

BillingOperatorCursorKeyMigrationName adds the server-owned secret that authenticates durable operator-reader cursors. The key is generated once per store identity, persisted with the owned billing data, and used only as an HMAC key: it is never embedded in a cursor, response, log or error.

View Source 
const BillingPostingOwnershipMigrationName = "20261003000000"

BillingPostingOwnershipMigrationName identifies the durable per-operation posting ownership pins (Task 17.3B1, Migration Strategy step 6). One row per (store, operation kind, canonical operation key) pins exactly one posting owner (v1/v2) with the marker epoch/generation/version snapshot observed at acquisition, plus durable completion state so waking workers distinguish unposted pinned work from already completed effects. B2b4 direct-adjustment pins carry empty call_id (no call lineage); call_id therefore allows empty while account remains required. No terminal claim/worker/admission wiring lives in this migration.

View Source 
const BillingProviderCostCorrectionLinksMigrationName = "20260924000000"

BillingProviderCostCorrectionLinksMigrationName identifies the additive provider-cost identity repair. Heads and posting fences retain both the original and latest journal transaction IDs so correction links can be reconstructed after restart or legacy adoption.

View Source 
const BillingProviderCostExecutionFenceMigrationName = "20260923000000"

BillingProviderCostExecutionFenceMigrationName identifies the execution level provider-cost writer gate. Per-head posting fences remain responsible for selected amounts; this row only decides whether legacy aggregate work or V2 revision work owns the B-leg execution.

View Source 
const BillingProviderCostHeadsMigrationName = "20260921000000"

BillingProviderCostHeadsMigrationName identifies the additive current-head projection used by incremental operator/provider-cost accrual.

View Source 
const BillingProviderCostPostingFenceMigrationName = "20260922000000"

BillingProviderCostPostingFenceMigrationName identifies the durable cross-path provider-cost posting identity. Legacy LUR work and V2 economic revisions both claim this row before they can write provider COGS.

View Source 
const BillingReconciliationRetentionMigrationName = "20260926000000"

BillingReconciliationRetentionMigrationName identifies the additive durable full-result reconciliation retention envelope version marker and the scope-ordered read index for Task 12.3B.

View Source 
const BillingReconciliationRetentionTenantIndexMigrationName = "20260927000000"

BillingReconciliationRetentionTenantIndexMigrationName adds the tenant-bearing retention index used by the tenant-refined latest read.

View Source 
const BillingSelectedCostAdjustmentsMigrationName = "20260929000000"

BillingSelectedCostAdjustmentsMigrationName identifies the additive Task 13.3B selected-cost adjustment schema. The existing provider-cost head gains the exact selected valuation identity (valuation revision, selection plane, exact posted/native amounts, frozen FX basis and posting state), and the new immutable adjustment table retains the operation plus valuation-link identity.

View Source 
const BillingStatementImportMigrationName = "20260928000000"

BillingStatementImportMigrationName identifies the additive durable normalized statement import ledger for Task 13.1B: one immutable statement revision envelope plus its independent immutable line claims.

View Source 
const BillingV2EconomicsMigrationName = "20260912010000"

BillingV2EconomicsMigrationName identifies the additive durable V2 valuation/reconciliation projections.

View Source 
const BillingV2LineBooleanRepairMigrationName = "20260912020000"

BillingV2LineBooleanRepairMigrationName identifies the forward repair for valuation-line boolean projections created by the original V2 migration.

View Source 
const BillingV2ValuationIdentityMigrationName = "20260914000000"

BillingV2ValuationIdentityMigrationName identifies the additive repair that persists the trusted economic context used by valuation identity. Existing rows retain an empty context hash and remain readable.

View Source 
const CompleteCallClaimLeaseMigrationName = "20260827000000"
View Source 
const CostPassThroughAdjustmentOperationKind = billing.CostPassThroughAdjustmentOperationKind
View Source 
const CostPassThroughHeadMigrationName = "20260916000000"

CostPassThroughHeadMigrationName identifies the mutable CAS-protected customer cost-pass-through head. The head is a rebuildable pointer to the immutable settlement/journal history, never a replacement for that history.

View Source 
const CustomerUnitLedgerMigrationName = "20260915000000"

CustomerUnitLedgerMigrationName identifies the durable customer-owned unit balance, operation, and reservation tables. The operation rows are immutable idempotency records; balance and reservation rows are the mutable authority.

View Source 
const EconomicsV2MigrationName = BillingV2EconomicsMigrationName

EconomicsV2MigrationName is a descriptive alias used by composition code.

View Source 
const ExposureMigrationName = "20260820000000"
View Source 
const HoldRetirementMigrationName = "20260821000000"

HoldRetirementMigrationName is the cutover marker for legacy authorization holds. The table is retained during rollout for evidence-preserving recovery; any account with an open legacy hold is blocked until an operator reconciles it.

View Source 
const LegacyAuthorizationSchemaMigrationName = "20260813000000"

LegacyAuthorizationSchemaMigrationName identifies the forward migration that adds authorization identity and account-snapshot evidence to existing billing installations. The filename is part of Bun's migration identity convention.

View Source 
const LegacyUsageRetirementMigrationName = "20260901000000"

LegacyUsageRetirementMigrationName is a forward-only destructive migration. The baseline TUR/LUR/processing DDL remains immutable historical input.

View Source 
const Phase4MigrationName = "20260814000000"
View Source 
const Phase6MigrationName = "20260815000000"
View Source 
const Phase7MigrationName = "20260816000000"
View Source 
const ProviderCostWorkMigrationName = "20260822000000"
View Source 
const ProviderCostWorkRetryMigrationName = "20260823000000"
View Source 
const ProviderMaintenanceIntegrityMigrationName = "20260903000000"
View Source 
const ProviderMaintenanceMigrationName = "20260902000000"
View Source 
const ReservedColumnRemovalMigrationName = "20260831000000"

ReservedColumnRemovalMigrationName is the forward schema contract for the current billing model. Historical migration sources retain their original reserved column definitions; only this migration removes the materialized account and reconciliation-event columns. Journal and operation-snapshot reserved columns remain immutable audit storage so old authorization rows and snapshots retain exact evidence; current DTOs omit them and current writers write proven zero values.

View Source 
const ReservedNanoZeroMigrationName = "20260826000000"

ReservedNanoZeroMigrationName clears residual reserved_nano after hold retirement.

View Source 
const RouteTariffBindingMigrationName = "20260930000001"

RouteTariffBindingMigrationName adds the frozen per-route customer tariff bindings to call_exposures. A rich quote freezes every evaluated route tariff (route key plus tariff version and content hash); terminal settlement compares the rated routes against this binding before posting.

View Source 
const SessionIDMigrationName = "20260817000000"
View Source 
const SubmissionFeeClaimMigrationName = "20260917000000"

SubmissionFeeClaimMigrationName identifies the durable once-per-submission commercial-fee claim. The claim is immutable history keyed by store, account, and trusted SubmissionID.

View Source 
const UsageAppendOutboxMigrationName = "20260824000000"
View Source 
const UsageAppendOutboxRetirementMigrationName = "20260829000000"

UsageAppendOutboxRetirementMigrationName is the forward cutover marker. The 20260824000000 source remains immutable historical input; it is deliberately not registered for fresh installs.

View Source 
const UsageCallRecordsMigrationName = "20260819000000"
View Source 
const UsageLegRecordsMigrationName = "20260818000000"
View Source 
const UsageLegSequenceMigrationName = "20260828000000"

Variables

View Source 
var (
	// ErrEconomicRevisionHeadNotFound identifies a head that has not yet been
	// produced by the pure worker.
	ErrEconomicRevisionHeadNotFound = errors.New("billingstore: economic revision head not found")
	// ErrEconomicRevisionWorkConflict identifies a durable work replay whose
	// immutable payload differs from the original identity.
	ErrEconomicRevisionWorkConflict = errors.New("billingstore: economic revision work conflict")
)
View Source 
var (
	ErrIdentityConflict           = errors.New("billingstore: idempotency identity conflict")
	ErrCorrectionInvalid          = errors.New("billingstore: invalid correction link")
	ErrAccountNotFound            = errors.New("billingstore: account not found")
	ErrUsageRecordNotFound        = errors.New("billingstore: usage record not found")
	ErrSequenceConflict           = errors.New("billingstore: account sequence conflict")
	ErrEvidenceIncomplete         = errors.New("billingstore: operation evidence incomplete")
	ErrProviderJournalGenericPath = errors.New("billingstore: provider COGS requires provider journal writer")
)
View Source 
var (
	// ErrShadowV2Incomplete identifies missing shadow configuration or ports.
	ErrShadowV2Incomplete = errors.New("billingstore: shadow V2 capture is incomplete")
	// ErrShadowV2Scope identifies a store-scope mismatch.
	ErrShadowV2Scope = errors.New("billingstore: shadow V2 capture store scope mismatch")
)
View Source 
var (
	// ErrInvalidEconomicsCursor identifies a malformed or filter-bound cursor.
	ErrInvalidEconomicsCursor = errors.New("billingstore: invalid economics cursor")
	// ErrEconomicsPageSizeExceeded identifies a request above the hard bounded
	// pagination limit.
	ErrEconomicsPageSizeExceeded = errors.New("billingstore: economics page size exceeds hard maximum")
	// ErrEconomicsOutOfScope identifies a query or record from another store.
	ErrEconomicsOutOfScope = errors.New("billingstore: economics record out of scope")
	// ErrCrossDatabaseTransaction prevents composition from pretending two Bun
	// handles are one atomic local transaction.
	ErrCrossDatabaseTransaction = errors.New("billingstore: composition requires one local database handle")
	ErrInvalidReconciliation    = errors.New("billingstore: invalid reconciliation")
	ErrInvalidEconomicWork      = errors.New("billingstore: invalid economic work marker")
	ErrQueryTooBroad            = metering.ErrQueryTooBroad
)
View Source 
var ErrLegAttemptSequenceConflict = errors.New("billingstore: call-leg attempt sequence conflict")

ErrLegAttemptSequenceConflict identifies duplicate positive sequences within one BillingCallID; legacy NULL values remain outside it.

View Source 
var ErrLegacyUsageRetirementBlocked = errors.New("billingstore: legacy usage retirement blocked")
View Source 
var ErrOperationConflict = errors.New("billingstore: trusted operation replay conflict")
View Source 
var ErrReconciliationFailed = errors.New("billingstore: reconciliation failed")
View Source 
var ErrReconciliationRetentionMismatch = errors.New("billingstore: reconciliation retention record mismatch")

ErrReconciliationRetentionMismatch identifies a durable reconciliation that is not a full-result retention record, or whose stored bytes are not the canonical result.

View Source 
var ErrReconciliationRetentionQuery = errors.New("billingstore: invalid reconciliation retention query")

ErrReconciliationRetentionQuery identifies a malformed latest-retention query identity. Query identities are validated before any SQL runs.

View Source 
var ErrSelectedCostAdjustmentMismatch = errors.New("billingstore: selected cost adjustment record mismatch")

ErrSelectedCostAdjustmentMismatch identifies a retained selected-cost head or adjustment row that is not the canonical self-validating record it claims to be.

View Source 
var ErrShadowV2ComparisonInvalid = errors.New("billingstore: invalid shadow V2 comparison")

ErrShadowV2ComparisonInvalid identifies a malformed comparison input.

View Source 
var ErrStatementImportMismatch = errors.New("billingstore: statement import record mismatch")

ErrStatementImportMismatch identifies a retained statement import row that is not the canonical self-validating record it claims to be.

View Source 
var ErrUsageAppendCutoverBlocked = errors.New("billingstore: usage append outbox cutover blocked")

ErrUsageAppendCutoverBlocked is returned when destructive retirement cannot prove that every legacy append has been delivered and reconciled.

View Source 
var ErrUsageAppendDrainBlocked = errors.New("billingstore: usage append outbox drain blocked")

Historical preserve-or-block adapter; runtime composition never calls this code. ErrUsageAppendDrainBlocked means historical central transport work could not be proven delivered. Callers must reconcile it before any destructive schema migration; rows are intentionally preserved.

View Source 
var RequiredMigrationNames = []string{BaselineMigrationName, LegacyAuthorizationSchemaMigrationName, Phase4MigrationName, Phase6MigrationName, Phase7MigrationName, SessionIDMigrationName, UsageLegRecordsMigrationName, UsageCallRecordsMigrationName, ProviderCostWorkMigrationName, ProviderCostWorkRetryMigrationName, ExposureMigrationName, HoldRetirementMigrationName, UsageAppendOutboxRetirementMigrationName, AuthorizationHoldsDropMigrationName, legacyReservedZeroMigrationName, CompleteCallClaimLeaseMigrationName, UsageLegSequenceMigrationName, ProviderJournalOrderMigrationName, ProviderJournalSequenceContractMigrationName, ReservedColumnRemovalMigrationName, LegacyUsageRetirementMigrationName, ProviderMaintenanceMigrationName, ProviderMaintenanceIntegrityMigrationName, BillingV2EconomicsMigrationName, BillingV2LineBooleanRepairMigrationName, BillingV2ValuationIdentityMigrationName, CustomerUnitLedgerMigrationName, CostPassThroughHeadMigrationName, SubmissionFeeClaimMigrationName, BillingAllocationMigrationName, BillingAllocationTargetScopeMigrationName, BillingEconomicRevisionHeadsMigrationName, BillingProviderCostHeadsMigrationName, BillingProviderCostPostingFenceMigrationName, BillingProviderCostExecutionFenceMigrationName, BillingProviderCostCorrectionLinksMigrationName, BillingReconciliationRetentionMigrationName, BillingReconciliationRetentionTenantIndexMigrationName, BillingStatementImportMigrationName, BillingSelectedCostAdjustmentsMigrationName, BillingEconomicJobQueueMigrationName, RouteTariffBindingMigrationName, BillingOperatorCursorKeyMigrationName, BillingEconomicHeadOrderingMigrationName, BillingAccountingCutoverMigrationName, BillingPostingOwnershipMigrationName, BillingEconomicPostingIntentMigrationName}

Functions

func Migrate 

func Migrate(ctx context.Context, database *bun.DB) error

func ShadowV2ExpectedFixReasonCodes 

func ShadowV2ExpectedFixReasonCodes() []string

ShadowV2ExpectedFixReasonCodes is the closed allowlist of intended V1 defect fixes. Each code maps to a design acceptance vector; a code alone never certifies a delta without exact expected agreement.

func VerifySchema 

func VerifySchema(ctx context.Context, database *bun.DB) error

Types

type AccountWindowSource 

type AccountWindowSource interface {
	ListAccountWindowObservations(context.Context, coremetering.AccountWindowQuery) (coremetering.AccountWindowObservationPage, error)
}

AccountWindowSource is the narrow gauge-history port implemented by the metering journal. The billingstore allowance adapter owns scope validation and public DTO mapping; SQL stays in the journal.

type AllowanceReader 

type AllowanceReader struct {
	Source AccountWindowSource
	// Authority is the durable operator-cursor authenticator. It must be the
	// same key authority that protects every other operator cursor; a reader
	// without it fails closed on any continuation.
	Authority OperatorCursorAuthority
}

AllowanceReader projects provider allowance gauge history through the public operator DTOs. Gauges pass through verbatim: no summation, no inferred per-request debit.

func (AllowanceReader) QueryAllowances 

func (r AllowanceReader) QueryAllowances(ctx context.Context, query economics.AllowanceQuery) (economics.AllowancePage, error)

QueryAllowances returns one bounded gauge-history page. The operator continuation is authenticated before the inner journal position is trusted or parsed, binds kind, full authorized scope, filters and journal order, and is re-sealed as an operator cursor; scope is re-checked after projection.

type Config 

type Config struct {
	StoreID string
}

type DurableStore 

type DurableStore struct {
	// contains filtered or unexported fields
}

func NewDurableStore 

func NewDurableStore(ctx context.Context, database *bun.DB, cfg Config) (*DurableStore, error)

func (*DurableStore) AccountReport 

func (s *DurableStore) AccountReport(ctx context.Context, accountID string, page billing.PageRequest) (billing.AccountReport, error)

func (*DurableStore) AccountStatus 

func (s *DurableStore) AccountStatus(ctx context.Context, accountID string) (billing.Account, error)

func (*DurableStore) AcquirePostingPin 

func (s *DurableStore) AcquirePostingPin(ctx context.Context, req billing.AcquirePostingPinRequest) (billing.PostingPin, error)

AcquirePostingPin pins exactly one owner to one logical financial operation. Exact replay (same kind/key/owner) is idempotent; owner mismatch is conflict; stale expected marker or state-forbidden owner is fence.

func (*DurableStore) ActivateCutoverV2 

func (s *DurableStore) ActivateCutoverV2(ctx context.Context, transitionID string) (billing.AccountingCutoverMarker, error)

ActivateCutoverV2 CAS transitions v1_draining->v2_active only when durable queries prove no pending/leased/uncompleted V1 pins/work across all three namespaces. Exact replay with the same transition identity is idempotent (race-safe restart/resume).

F1: the marker row is locked (SELECT FOR UPDATE on PostgreSQL, write upgrade on SQLite), drain counts and unclassifiable probes run inside the SAME transaction, and the version/epoch CAS UPDATE commits before release. Concurrent monetary transactions hold the same per-store marker lock, so activation either waits for in-flight work to commit (then observes it) or the stale poster fences after activation. Drain is never checked outside the transition tx.

func (*DurableStore) AdmitExposure 

func (s *DurableStore) AdmitExposure(ctx context.Context, input billing.AdmitExposureInput) (billing.CallExposure, error)

func (*DurableStore) AdmitExposureWithOwner 

func (s *DurableStore) AdmitExposureWithOwner(ctx context.Context, input billing.AdmitExposureInput, owner string) (billing.CallExposure, error)

AdmitExposureWithOwner is the explicit version-aware production admission path. Empty owner preserves the legacy V1 default (compatible pre-cutover). V1 is fenced in draining/active via the ordinary V1 gate. V2 requires v2_active authorization and pins V2 ownership at start in the same tx.

func (*DurableStore) AppendAllocation 

func (s *DurableStore) AppendAllocation(ctx context.Context, record economics.AllocationRecord) error

AppendAllocation appends one canonical immutable allocation and all of its target projections atomically. Replaying the same identity is idempotent; changing its canonical payload is an identity conflict.

func (*DurableStore) AppendAllocationInTx 

func (s *DurableStore) AppendAllocationInTx(ctx context.Context, tx bun.Tx, record economics.AllocationRecord) error

func (*DurableStore) AppendCall 

func (s *DurableStore) AppendCall(ctx context.Context, record billing.CallUsageRecord) error

Production terminal sink: AppendCall/AppendLeg implement billing.TerminalUsageSink for the composed runtime (including spool delivery). They route through the owner-aware usage append below: pre-active V1 and draining classified handoff keep their behavior, while a freshly admitted V2 exposure+pin selects the V2 owner durably (never a fresh global reclassification). Bound to DurableStore so a local spool cannot be supplied as proof of central delivery.

func (*DurableStore) AppendCallLegUsage 

func (s *DurableStore) AppendCallLegUsage(ctx context.Context, record billing.CallLegUsageRecord) error

AppendCallLegUsage is the DurableStore's current-record persistence API. It backs billing.TerminalUsageSink (AppendLeg) for the composed runtime as well as historical outbox drain/storage. Pre-active V1 and draining classified handoff keep their behavior; a freshly admitted V2 exposure+pin routes to the V2 owner with atomic provider work/pin in the same tx (R1).

func (*DurableStore) AppendCallLegUsageWithOwner 

func (s *DurableStore) AppendCallLegUsageWithOwner(ctx context.Context, record billing.CallLegUsageRecord, owner string) error

AppendCallLegUsageWithOwner is the explicit version-aware terminal leg path. Empty owner preserves the legacy V1 default. V2 validates against the admitted V2 call record and acquires the V2 provider pin atomically with work enqueue in the same tx.

func (*DurableStore) AppendCallUsage 

func (s *DurableStore) AppendCallUsage(ctx context.Context, record billing.CallUsageRecord) error

AppendCallUsage is the DurableStore's current-record persistence API. It backs billing.TerminalUsageSink (AppendCall) for the composed runtime as well as historical outbox drain/storage. Pre-active V1 and draining classified handoff keep their behavior; a freshly admitted V2 exposure+pin routes to the V2 owner in the same tx (R1), never reclassifying from a fresh global marker read.

func (*DurableStore) AppendCallUsageWithOwner 

func (s *DurableStore) AppendCallUsageWithOwner(ctx context.Context, record billing.CallUsageRecord, owner string) error

AppendCallUsageWithOwner is the explicit version-aware terminal closure path. Empty owner preserves the legacy V1 default. V2 validates against the admitted V2 exposure+pin record (not a fresh global read) and requires v2_active authorization.

func (*DurableStore) AppendEconomicRevisionReconciliation 

func (s *DurableStore) AppendEconomicRevisionReconciliation(ctx context.Context, work billing.EconomicRevisionWork, reconciliation billing.EconomicReconciliation) error

AppendEconomicRevisionReconciliation persists the immutable reconciliation output of dependency-anchored provider-queue work. The operation is idempotent for an exact replay and fails closed with ErrEconomicRevisionConflict for a changed payload under the same identity. No account, journal, exposure or financial head row is touched.

func (*DurableStore) AppendEconomicRevisionResult 

func (s *DurableStore) AppendEconomicRevisionResult(ctx context.Context, work billing.EconomicRevisionWork, result billing.EconomicRevisionResult) error

AppendEconomicRevisionResult atomically persists pure valuation, reconciliation and the rebuildable current head. No account, exposure, journal or customer-unit table is read or written by this transaction.

func (*DurableStore) AppendEconomicRevisionWork 

func (s *DurableStore) AppendEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork) error

AppendEconomicRevisionWork appends an immutable revision marker. The marker ID is derived from queue/head/revision/input hash; a duplicate is a no-op, while a changed payload under the same identity is rejected by the existing economic-work identity fence.

F2B: monetary provider work (provider queue + provider_rating + valid B-leg lineage) is fenced as new V1 work in draining/active (F1 marker lock held in the same tx). Evidence-only customer rating, reconciliation, shadow, and queues without a posting adapter remain operable in all states.

func (*DurableStore) AppendEconomicWork 

func (s *DurableStore) AppendEconomicWork(ctx context.Context, marker EconomicWorkMarker) error

func (*DurableStore) AppendEconomicWorkInTx 

func (s *DurableStore) AppendEconomicWorkInTx(ctx context.Context, tx bun.Tx, marker EconomicWorkMarker) error

func (*DurableStore) AppendEvidenceEconomicRevisionWork 

func (s *DurableStore) AppendEvidenceEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork) error

AppendEvidenceEconomicRevisionWork appends an explicitly evidence-only marker that never creates monetary intent, pins, or fences. Shadow observations/valuations and pure workers without a posting adapter use this path so drain never inventories them as payable work.

func (*DurableStore) AppendLeg 

func (s *DurableStore) AppendLeg(ctx context.Context, record billing.CallLegUsageRecord) error

func (*DurableStore) AppendObservationBundle 

func (s *DurableStore) AppendObservationBundle(ctx context.Context, writer journalstore.ObservationTxWriter, observation metering.Observation, valuation economics.Valuation, reconciliation ReconciliationRecord, marker EconomicWorkMarker) error

AppendObservationBundle is a value-oriented composition spelling for callers that always provide all four records.

func (*DurableStore) AppendObservationEconomics 

func (s *DurableStore) AppendObservationEconomics(ctx context.Context, writer journalstore.ObservationTxWriter, observation metering.Observation, valuation *economics.Valuation, reconciliation *ReconciliationRecord, marker *EconomicWorkMarker) error

AppendObservationEconomics composes one observation, valuation, reconciliation and optional work marker on one local transaction. The journal writer is intentionally a narrow infra interface.

func (*DurableStore) AppendObservationWithEconomics 

func (s *DurableStore) AppendObservationWithEconomics(ctx context.Context, writer journalstore.ObservationTxWriter, observation metering.Observation, valuation *economics.Valuation, reconciliation *ReconciliationRecord, marker *EconomicWorkMarker) error

AppendObservationWithEconomics is an optional-record composition spelling.

func (*DurableStore) AppendProviderMaintenance 

func (s *DurableStore) AppendProviderMaintenance(ctx context.Context, usage billing.ProviderMaintenanceUsage) error

func (*DurableStore) AppendProviderPostingEconomicRevisionWork 

func (s *DurableStore) AppendProviderPostingEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, owner string) error

AppendProviderPostingEconomicRevisionWork appends monetary provider work with an explicit posting owner (production enqueue). Empty owner preserves the legacy V1 default; "v2" requires v2_active authorization and is the only permitted new monetary owner after activation. Evidence-only envelopes fail closed here; use AppendEconomicRevisionWork for evidence-only work.

func (*DurableStore) AppendReconciliation 

func (s *DurableStore) AppendReconciliation(ctx context.Context, reconciliation ReconciliationRecord) error

func (*DurableStore) AppendReconciliationInTx 

func (s *DurableStore) AppendReconciliationInTx(ctx context.Context, tx bun.Tx, reconciliation ReconciliationRecord) error

func (*DurableStore) AppendReconciliationRetention 

func (s *DurableStore) AppendReconciliationRetention(ctx context.Context, result billing.ReconciliationRetentionResult) error

AppendReconciliationRetention durably appends one immutable full-result reconciliation in its own local transaction.

func (*DurableStore) AppendReconciliationRetentionInTx 

func (s *DurableStore) AppendReconciliationRetentionInTx(ctx context.Context, tx bun.Tx, result billing.ReconciliationRetentionResult) error

AppendReconciliationRetentionInTx appends the full result through an existing local transaction so callers can compose it atomically.

func (*DurableStore) AppendStatementRevision 

func (s *DurableStore) AppendStatementRevision(ctx context.Context, statement billing.NormalizedStatement) error

AppendStatementRevision atomically retains one normalized statement revision and its line claims. Exact replay is an idempotent no-op; a retained statement or line identity with different content fails closed with billing.ErrStatementImportConflict and leaves no partial insert.

func (*DurableStore) AppendValuation 

func (s *DurableStore) AppendValuation(ctx context.Context, valuation economics.Valuation) error

AppendValuation stores the canonical immutable V2 valuation and its derived line projections atomically.

func (*DurableStore) AppendValuationInTx 

func (s *DurableStore) AppendValuationInTx(ctx context.Context, tx bun.Tx, valuation economics.Valuation) error

func (*DurableStore) ApplyCallBillingResult 

func (s *DurableStore) ApplyCallBillingResult(ctx context.Context, input billing.ApplyCallBillingInput) (billing.CallSettlement, error)

func (*DurableStore) ApplyCostPassThroughAdjustment 

func (s *DurableStore) ApplyCostPassThroughAdjustment(ctx context.Context, input billing.CostPassThroughRevisionInput) (billing.CostPassThroughRevisionResult, error)

ApplyCostPassThroughAdjustment is a descriptive compatibility spelling for callers that treat each accepted revision as an adjustment operation.

func (*DurableStore) ApplyCostPassThroughRevision 

func (s *DurableStore) ApplyCostPassThroughRevision(ctx context.Context, input billing.CostPassThroughRevisionInput) (billing.CostPassThroughRevisionResult, error)

ApplyCostPassThroughRevision atomically advances one explicit customer pass-through head and posts only the signed difference from its current posted amount. Validation of the provider payload occurs before the account transaction, so supplier waits never hold customer admission locks. B2b4 binds the per-head financial_adjustment pin in the same transaction.

func (*DurableStore) ApplyCustomerUnitOperation 

func (s *DurableStore) ApplyCustomerUnitOperation(ctx context.Context, op billing.CustomerUnitOperation) (billing.CustomerUnitOperationResult, error)

ApplyCustomerUnitOperation executes one customer-owned unit mutation. The operation row, balance transition, and reservation binding all share one retryable local transaction. No balance read is exposed to callers.

func (*DurableStore) ApplyOperatorCostRevision 

func (s *DurableStore) ApplyOperatorCostRevision(ctx context.Context, input billing.OperatorCostRevisionInput) (billing.OperatorCostRevisionResult, error)

ApplyOperatorCostRevision is the descriptive operator-side alias.

func (*DurableStore) ApplyProviderCost 

func (s *DurableStore) ApplyProviderCost(ctx context.Context, input billing.ApplyProviderCostInput) (billing.Posting, error)

func (*DurableStore) ApplyProviderCostRevision 

func (s *DurableStore) ApplyProviderCostRevision(ctx context.Context, input billing.ProviderCostRevisionInput) (billing.ProviderCostRevisionResult, error)

ApplyProviderCostRevision atomically advances one provider-cost head and posts only the signed delta from its prior selected amount. Pure provider COGS does not lock or update the customer account balance/version.

func (*DurableStore) ApplySelectedCostAdjustment 

func (s *DurableStore) ApplySelectedCostAdjustment(ctx context.Context, input billing.SelectedCostAdjustmentInput) (billing.SelectedCostAdjustmentResult, error)

ApplySelectedCostAdjustment atomically applies one selected-cost head compare-and-swap. Pure provider COGS never locks or updates the customer account balance/version.

func (*DurableStore) BeginCutoverDraining 

func (s *DurableStore) BeginCutoverDraining(ctx context.Context, transitionID string) (billing.AccountingCutoverMarker, billing.CutoverDrainStatus, error)

BeginCutoverDraining closes the gate before classification: it CAS transitions v2_shadow->v1_draining first, then classifies in bounded batches. Already-draining markers resume classification (restart-safe). Any other state fails with ErrAccountingCutoverInvalid.

func (*DurableStore) CallExplanation 

func (s *DurableStore) CallExplanation(ctx context.Context, callIDRaw string) (billing.CallExplanation, error)

func (*DurableStore) ChangeCreditPolicy 

func (s *DurableStore) ChangeCreditPolicy(ctx context.Context, input billing.CreditPolicyInput) (billing.PolicyChange, error)

func (*DurableStore) CheckHistoricalV1WriterClaim 

func (s *DurableStore) CheckHistoricalV1WriterClaim(ctx context.Context, callID billing.BillingCallID, claimant string) error

CheckHistoricalV1WriterClaim is a read-only ownership preflight for old in-flight V1 work at the storage seam. It validates the requested CallID against actual row key/fingerprint/payload identity: each row's key must match the requested call, its columns must match its sealed payload, and its payload CallID must match the request. Mixed-call, drifted, or malformed rows fail closed. A claimant other than the resolved owner fails with billing.ErrHistoricalV1WriterConflict. Durable epoch/posting enforcement belongs to Phase 17.3; this check performs no writes.

func (*DurableStore) CheckReadiness 

func (s *DurableStore) CheckReadiness(ctx context.Context) error

func (*DurableStore) CheckV2NewWorkAuthorized 

func (s *DurableStore) CheckV2NewWorkAuthorized(ctx context.Context) error

checkV2NewWorkAuthorized fails closed unless the durable marker is v2_active. Shadow capture remains no-post and does not consult this gate.

func (*DurableStore) ClaimCompleteCall 

func (s *DurableStore) ClaimCompleteCall(ctx context.Context, callID billing.BillingCallID) (billing.CompleteCall, error)

func (*DurableStore) ClaimCompleteCalls 

func (s *DurableStore) ClaimCompleteCalls(ctx context.Context, limit int) ([]billing.CompleteCall, error)

func (*DurableStore) ClaimCompleteCallsWithCutover 

func (s *DurableStore) ClaimCompleteCallsWithCutover(ctx context.Context, limit int) ([]billing.ClaimedCompleteCall, error)

ClaimCompleteCallsWithCutover atomically claims complete calls and issues current-marker tokens as part of each claimed item. Claim status transition, pin acquisition/validation (including first-acquisition pin creation), and current-marker authority issuance occur in one transaction holding the per-store marker lock, so a marker transition between claim attempt and return cannot yield a token authorized for the wrong epoch/state. It never swallows operational, cancellation or malformed errors into nil/default tokens. Ineligible work (unpinned in draining, V1 in active) is withheld without error and without committing a claim; first-acquisition work with no pin yet acquires its pin atomically and returns a nonempty fully validated token. Draining pinned V1 and shadow V1 receive current-epoch renewal without rewriting owner.

func (*DurableStore) ClaimEconomicRevisionWork 

func (s *DurableStore) ClaimEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, owner string, lease time.Duration) (billing.EconomicRevisionWorkClaim, bool, error)

ClaimEconomicRevisionWork leases one immutable revision marker. The state row is mutable delivery metadata; its monotonically increasing fence makes reclaiming an expired lease safe across multiple workers.

func (*DurableStore) ClaimEconomicRevisionWorkBatch 

func (s *DurableStore) ClaimEconomicRevisionWorkBatch(ctx context.Context, queue billing.EconomicQueue, owner string, lease time.Duration, limit int) ([]billing.EconomicRevisionClaimedWork, error)

ClaimEconomicRevisionWorkBatch leases up to limit due jobs of one queue in a single bounded transaction. Jobs whose immutable dependency outputs are not yet durable are skipped without consuming an attempt or mutating their state. Each claimed job carries a fresh fence; a stale owner can never complete, heartbeat, retry or fail it afterwards.

func (*DurableStore) ClaimEconomicRevisionWorkWithCutover 

func (s *DurableStore) ClaimEconomicRevisionWorkWithCutover(ctx context.Context, work billing.EconomicRevisionWork, owner string, lease time.Duration) (billing.EconomicRevisionWorkClaim, *billing.CutoverClaimMetadata, bool, error)

ClaimEconomicRevisionWorkWithCutover atomically leases one revision and issues a current-marker cutover token for monetary provider work in a single transaction holding the per-store marker lock. Lease fence, pin acquisition/validation (including first-acquisition), and current-marker authority issuance commit together, so a marker transition between lease and return cannot yield a token authorized for the wrong epoch/state and the lease fence is bound to the token. Evidence-only work returns a nil cutover (no monetary authority) with its lease. It never swallows operational, cancellation or malformed errors; ineligible monetary work is withheld (claimed=false) without consuming a lease attempt. First-acquisition monetary work acquires its pin atomically and returns a nonempty fully validated token bound to the new lease fence.

R2 authoritative: monetary intent comes from mutable delivery state plus shape, never payload EvidenceOnly/owner alone, so upgraded shadow is monetary here even when the stored payload remains evidence-only.

func (*DurableStore) ClaimProviderCostWorkForRevision 

func (s *DurableStore) ClaimProviderCostWorkForRevision(ctx context.Context, work billing.ProviderCostWork) (bool, error)

ClaimProviderCostWorkForRevision atomically retires one legacy queue item when a durable revision fence already owns the same B-leg lineage. The resolver is intentionally bypassed in this case: its result is stale by construction and must not create a competing diagnostic or journal path.

func (*DurableStore) ClaimProviderCostWorkWithCutover 

func (s *DurableStore) ClaimProviderCostWorkWithCutover(ctx context.Context, limit int) ([]billing.ClaimedProviderCostWork, error)

ClaimProviderCostWorkWithCutover atomically lists eligible pending B-legs and issues current-marker tokens as part of each claimed item. Pin validation/acquisition (including first-acquisition) and current-marker authority issuance occur in one transaction holding the per-store marker lock, so a marker transition between list and return cannot yield a token authorized for the wrong epoch/state. It never swallows operational, cancellation or malformed errors. Ineligible work (unpinned in draining, V1 in active) is withheld without error; first-acquisition work acquires its pin atomically and returns a nonempty fully validated token.

func (*DurableStore) ClassifyCutoverDraining 

func (s *DurableStore) ClassifyCutoverDraining(ctx context.Context, batchSize int) (billing.CutoverDrainStatus, error)

ClassifyCutoverDraining enumerates pending/leased customer calls and provider-cost work in bounded deterministic batches and pins V1 using canonical keys/marker epoch. Adjustment inventory is explicitly empty (F4): synchronous adjustments have no durable pending queue, so no head scan occurs. Unclassifiable items remain draining with explicit status; completion is never invented.

func (*DurableStore) Close 

func (s *DurableStore) Close() error

func (*DurableStore) CompleteEconomicRevisionWork 

func (s *DurableStore) CompleteEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, claim billing.EconomicRevisionWorkClaim) error

CompleteEconomicRevisionWork durably retires a successful attempt without mutating the immutable evidence marker or any derived result/head.

func (*DurableStore) CompletePostingPin 

func (s *DurableStore) CompletePostingPin(ctx context.Context, req billing.CompletePostingPinRequest) (billing.PostingPin, error)

CompletePostingPin records the posting outcome for a pinned operation. Exact replay with the identical outcome is idempotent; a different outcome under the same pin is a conflict. Completing an unpinned operation reports NotFound. State-forbidden completions (for example V1 after v2_active) are fenced; exact completed-history replays bypass the allowance check.

func (*DurableStore) CreateAccount 

func (s *DurableStore) CreateAccount(ctx context.Context, account billing.Account) error

func (*DurableStore) CurrentEconomicValuationHead 

func (s *DurableStore) CurrentEconomicValuationHead(ctx context.Context, queue billing.EconomicQueue, headKey string) (billing.EconomicValuationHead, error)

CurrentEconomicValuationHead is an alias for read-side query composition.

func (*DurableStore) CustomerUnitBalance 

func (s *DurableStore) CustomerUnitBalance(ctx context.Context, key billing.CustomerUnitKey) (billing.CustomerUnitBalance, error)

CustomerUnitBalance reads the current authoritative unit balance for one customer-owned entitlement key. It validates store, context, and key scope and propagates every storage error: callers must fail closed rather than treat an outage or a missing balance as zero. Like the former internal diagnostic helper, it is intentionally not part of CustomerUnitLedger, so runtime callers cannot turn it into read-then-spend.

func (*DurableStore) CutoverDrainStatus 

func (s *DurableStore) CutoverDrainStatus(ctx context.Context) (billing.CutoverDrainStatus, error)

CutoverDrainStatus returns the durable precondition snapshot without writing pins. Unclassifiable samples come from a bounded dry-run that derives (but never acquires) canonical keys.

func (*DurableStore) CutoverUsageAppendOutbox 

func (s *DurableStore) CutoverUsageAppendOutbox(ctx context.Context) error

CutoverUsageAppendOutbox drains legacy pending work and then retires the schema in one dialect-specific migration critical section. The historical migration which introduced the table remains immutable; this operation is the explicit, operator-invoked destructive cutover.

func (*DurableStore) DB 

func (s *DurableStore) DB() *bun.DB

DB exposes the owned Bun handle to infrastructure composition code only. Public host/SDK contracts intentionally do not depend on Bun.

func (*DurableStore) Database 

func (s *DurableStore) Database() *bun.DB

Database is an explicit infra spelling used by composition checks.

func (*DurableStore) DecodeAllowanceCursor 

func (s *DurableStore) DecodeAllowanceCursor(raw, storeID, filter string) (string, error)

DecodeAllowanceCursor implements OperatorCursorAuthority for the durable billing store that owns the cursor key.

func (*DurableStore) DeferProviderCostWork 

func (s *DurableStore) DeferProviderCostWork(ctx context.Context, work billing.ProviderCostWork, reason string) error

func (*DurableStore) DeferUsageAppend 

func (s *DurableStore) DeferUsageAppend(ctx context.Context, key, reason string) error

func (*DurableStore) DrainUsageAppendOutbox 

func (s *DurableStore) DrainUsageAppendOutbox(ctx context.Context) error

DrainUsageAppendOutbox performs the preserve-or-block part of Phase 2 cutover. It validates and replays every pending row into the current central call/leg records, treats an identical central replay as success, and refuses to claim completion for malformed, conflicting, or unresolved rows. Schema deletion is deliberately separate and must run its own dialect-locked migration critical section after this proof.

func (*DurableStore) EconomicHealthSnapshot 

func (s *DurableStore) EconomicHealthSnapshot(ctx context.Context) (billing.EconomicHealthSnapshot, error)

EconomicHealthSnapshot aggregates the store's economics worker, statement and reconciliation state into one bounded point-in-time rollup.

func (*DurableStore) EconomicRevisionDependencyChecks 

func (s *DurableStore) EconomicRevisionDependencyChecks(ctx context.Context, work billing.EconomicRevisionWork) ([]billing.EconomicJobDependencyCheck, error)

EconomicRevisionDependencyChecks probes the immutable rating outputs a dependency-anchored job references. Missing outputs make the job incomplete evidence; it remains pending until they are durably appended.

func (*DurableStore) EconomicRevisionQueueBacklog 

func (s *DurableStore) EconomicRevisionQueueBacklog(ctx context.Context, queue billing.EconomicQueue) (billing.EconomicRevisionBacklog, error)

EconomicRevisionQueueBacklog returns a bounded operational snapshot for one queue: status counts, oldest pending age, next future attempt and the number of dependency-gated jobs whose immutable outputs are not yet durable. The dependency scan is bounded by economicBacklogDependencyScanLimit.

func (*DurableStore) EncodeAllowanceCursor 

func (s *DurableStore) EncodeAllowanceCursor(storeID, filter, source string) string

EncodeAllowanceCursor implements OperatorCursorAuthority for the durable billing store that owns the cursor key.

func (*DurableStore) EncodeEconomicDetailSnapshotContinuation 

func (s *DurableStore) EncodeEconomicDetailSnapshotContinuation(query billing.EconomicDetailQuery, position billing.EconomicObservationPosition, baseFingerprint, outerFingerprint string) string

EncodeEconomicDetailSnapshotContinuation re-encodes an economic-detail continuation preserving the durable base snapshot fingerprint and binding an outer fingerprint computed by a reader composed above this adapter. It authenticates nothing new: the caller has already authenticated the incoming cursor through QueryEconomicDetail, and this only produces the next opaque token. An invalid position or foreign store yields an empty token so the caller keeps its existing (already authenticated) cursor rather than emitting a token that cannot verify.

func (*DurableStore) EnqueueCallLegUsageAppend 

func (s *DurableStore) EnqueueCallLegUsageAppend(ctx context.Context, record billing.CallLegUsageRecord, cause string) error

func (*DurableStore) EnqueueCallUsageAppend 

func (s *DurableStore) EnqueueCallUsageAppend(ctx context.Context, record billing.CallUsageRecord, cause string) error

func (*DurableStore) EnqueueEconomicRevision 

func (s *DurableStore) EnqueueEconomicRevision(ctx context.Context, work billing.EconomicRevisionWork) error

EnqueueEconomicRevision is a concise composition spelling retained for callers that treat the durable marker as a queue operation.

func (*DurableStore) EnsureAccountingCutover 

func (s *DurableStore) EnsureAccountingCutover(ctx context.Context) (billing.AccountingCutoverMarker, error)

EnsureAccountingCutover returns the durable marker, creating the safe legacy default (V1 active, generation 1, version/epoch 1, V1 posting owner) when no row exists. Concurrent initializers converge via an idempotent insert-or-ignore followed by a single authoritative read.

func (*DurableStore) FailEconomicRevisionWork 

func (s *DurableStore) FailEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, claim billing.EconomicRevisionWorkClaim, reason billing.EconomicWorkReason) error

FailEconomicRevisionWork terminally retires one claimed job with a bounded, closed failure reason. A failed job is no longer claimable or listed as pending; the immutable work marker remains durable history.

func (*DurableStore) FailUsageAppend 

func (s *DurableStore) FailUsageAppend(ctx context.Context, key, reason string) error

func (*DurableStore) GetAccount 

func (s *DurableStore) GetAccount(ctx context.Context, accountID string) (billing.Account, error)

func (*DurableStore) GetAccountingCutover 

func (s *DurableStore) GetAccountingCutover(ctx context.Context) (billing.AccountingCutoverMarker, error)

GetAccountingCutover reads the durable marker for this store boundary without creating it. Fresh legacy stores report billing.ErrAccountingCutoverNotFound so callers can Ensure the explicit V1 default.

func (*DurableStore) GetAccountingRecoverySnapshot 

func (s *DurableStore) GetAccountingRecoverySnapshot(ctx context.Context) (billing.AccountingRecoverySnapshot, error)

GetAccountingRecoverySnapshot loads the durable per-store recovery snapshot: the cutover marker when present plus V2 posting presence.

func (*DurableStore) GetAllocation 

func (s *DurableStore) GetAllocation(ctx context.Context, allocationID string, version uint64) (economics.AllocationRecord, error)

GetAllocation loads the authoritative canonical envelope. Projection rows are intentionally not reassembled, so a stale projection cannot alter the source lineage or exact shares returned to callers.

func (*DurableStore) GetCallExposure 

func (s *DurableStore) GetCallExposure(ctx context.Context, callID billing.BillingCallID) (billing.CallExposure, error)

func (*DurableStore) GetCallLegUsage 

func (s *DurableStore) GetCallLegUsage(ctx context.Context, key string) (billing.CallLegUsageRecord, error)

func (*DurableStore) GetCallUsage 

func (s *DurableStore) GetCallUsage(ctx context.Context, callID billing.BillingCallID) (billing.CallUsageRecord, error)

func (*DurableStore) GetCutoverClaimMetadata 

func (s *DurableStore) GetCutoverClaimMetadata(ctx context.Context, kind billing.PostingOperationKind, operationKey string) (billing.CutoverClaimMetadata, error)

GetCutoverClaimMetadata returns the renewable current-marker token B2b workers consume (including leases waking after an epoch change).

Pin owner/identity is stable historical ownership; the returned version/epoch/state is always the current marker (lease authority), never the pin's acquisition snapshot. In draining only classified V1 pins receive renewal; in active V1 receives none (fenced) and V2 eligible work receives V2. Pre-drain renews V1 only. Missing pins report NotFound (authorized first acquisition vs metadata failure is distinguished by the caller); operational, cancellation and malformed inputs fail closed and are never swallowed into nil/default tokens.

func (*DurableStore) GetEconomicValuationHead 

func (s *DurableStore) GetEconomicValuationHead(ctx context.Context, queue billing.EconomicQueue, headKey string) (billing.EconomicValuationHead, error)

GetEconomicValuationHead returns the deterministic current pointer for one queue/head. Immutable historical valuations remain queryable independently.

func (*DurableStore) GetOperatorCostHead 

func (s *DurableStore) GetOperatorCostHead(ctx context.Context, accountID string, callID billing.BillingCallID, headKey string) (billing.OperatorCostHead, error)

GetOperatorCostHead is the descriptive operator-side alias.

func (*DurableStore) GetPostingPin 

func (s *DurableStore) GetPostingPin(ctx context.Context, kind billing.PostingOperationKind, operationKey string) (billing.PostingPin, error)

GetPostingPin reads the durable pin for one canonical operation without creating it. Fresh operations report ErrPostingOwnershipNotFound so callers can Acquire the explicit pin. Completed pins remain readable as history.

func (*DurableStore) GetProviderCostHead 

func (s *DurableStore) GetProviderCostHead(ctx context.Context, accountID string, callID billing.BillingCallID, headKey string) (billing.ProviderCostHead, error)

GetProviderCostHead returns the current selected-cost pointer and never waits on or mutates the customer account balance.

func (*DurableStore) GetProviderCostWorkState 

func (s *DurableStore) GetProviderCostWorkState(ctx context.Context, legKey string) (ProviderCostWorkState, error)

GetProviderCostWorkState reads provider-cost work independently of whether its next retry is due. This is used by operators and tests to distinguish durable pending/unreconciled work from an empty due queue.

func (*DurableStore) GetReconciliation 

func (s *DurableStore) GetReconciliation(ctx context.Context, reconciliationID string, version uint64) (ReconciliationRecord, error)

func (*DurableStore) GetReconciliationRetention 

func (s *DurableStore) GetReconciliationRetention(ctx context.Context, reconciliationID string, revision uint64) (billing.ReconciliationRetentionResult, error)

GetReconciliationRetention reads one immutable retention result and verifies its canonical bytes. A legacy single-basis reconciliation id is rejected.

func (*DurableStore) GetSelectedCostHead 

func (s *DurableStore) GetSelectedCostHead(ctx context.Context, accountID string, callID billing.BillingCallID, headKey string) (billing.SelectedCostHead, error)

GetSelectedCostHead returns the current selected/posted valuation pointer, including the exact frozen valuation identity and correction chain, and never waits on or mutates the customer account balance.

func (*DurableStore) GetStatementRevision 

func (s *DurableStore) GetStatementRevision(ctx context.Context, identity economics.StatementIdentity) (billing.NormalizedStatement, error)

GetStatementRevision reads one retained statement revision and re-derives it through the domain normalizer before returning it. A row that is not the canonical self-validating record fails closed with ErrStatementImportMismatch instead of being returned as evidence.

func (*DurableStore) GetValuation 

func (s *DurableStore) GetValuation(ctx context.Context, valuationID string, version uint32) (economics.Valuation, error)

func (*DurableStore) GetValuationVersion 

func (s *DurableStore) GetValuationVersion(ctx context.Context, valuationID string, version uint64) (economics.Valuation, error)

func (*DurableStore) HasEconomicRevisionReconciliation 

func (s *DurableStore) HasEconomicRevisionReconciliation(ctx context.Context, identity billing.EconomicRevisionIdentity) (bool, error)

HasEconomicRevisionReconciliation probes whether the immutable reconciliation output for a dependency-anchored revision already exists. It lets an interrupted worker finish the claim without recomputing.

func (*DurableStore) HasEconomicRevisionResult 

func (s *DurableStore) HasEconomicRevisionResult(ctx context.Context, identity billing.EconomicRevisionIdentity) (bool, error)

HasEconomicRevisionResult probes the immutable valuation history using the deterministic revision valuation identity. It performs no head/balance mutation and lets a restarted worker avoid re-rating an already completed revision.

func (*DurableStore) HasV2MonetaryPostings 

func (s *DurableStore) HasV2MonetaryPostings(ctx context.Context) (bool, error)

HasV2MonetaryPostings reports durable V2 financial authority for this store boundary. It returns false (nil error) on fresh, V1-only, and capture/pending-evidence-only stores.

func (*DurableStore) HeartbeatEconomicRevisionWork 

func (s *DurableStore) HeartbeatEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, claim billing.EconomicRevisionWorkClaim, extend time.Duration) (billing.EconomicRevisionWorkClaim, error)

HeartbeatEconomicRevisionWork extends the lease of one live claim while keeping its fence. A stale or foreign owner is rejected so only the current worker can keep its work alive.

func (*DurableStore) HistoricalAuthorizationJournals 

func (s *DurableStore) HistoricalAuthorizationJournals(ctx context.Context, accountID string) ([]HistoricalAuthorizationJournal, error)

HistoricalAuthorizationJournals reads old authorization rows for audit and migration tooling only. No current report calls this reader.

func (*DurableStore) JournalTransactions 

func (s *DurableStore) JournalTransactions(ctx context.Context, accountID string) ([]billing.JournalTransaction, error)

func (*DurableStore) LatestReconciliationRetention 

func (s *DurableStore) LatestReconciliationRetention(ctx context.Context, query ReconciliationRetentionQuery) (billing.ReconciliationRetentionResult, bool, error)

LatestReconciliationRetention returns the newest retention revision for the required subject scope with a deterministic total order (created_at, id, revision, row id). The subject identity and optional tenant are validated against the domain subject bounds before SQL, and both supported query shapes are served by the retention index prefix, so LIMIT 1 performs bounded index work instead of scanning unrelated rows.

func (*DurableStore) ListAllocations 

func (s *DurableStore) ListAllocations(ctx context.Context, query economics.AllocationQuery) (economics.AllocationPage, error)

func (*DurableStore) ListCallLegUsage 

func (s *DurableStore) ListCallLegUsage(ctx context.Context, callID billing.BillingCallID) ([]billing.CallLegUsageRecord, error)

func (*DurableStore) ListCallUsage 

func (s *DurableStore) ListCallUsage(ctx context.Context, accountID string) ([]billing.CallUsageRecord, error)

func (*DurableStore) ListEconomicRevisionWork 

func (s *DurableStore) ListEconomicRevisionWork(ctx context.Context, queue billing.EconomicQueue, limit int) ([]billing.EconomicRevisionWork, error)

ListEconomicRevisionWork is an alias for the bounded pending queue reader.

func (*DurableStore) ListPendingEconomicRevisionWork 

func (s *DurableStore) ListPendingEconomicRevisionWork(ctx context.Context, queue billing.EconomicQueue, limit int) ([]billing.EconomicRevisionWork, error)

ListPendingEconomicRevisionWork returns only one queue's due revision markers. Immutable markers remain durable history; mutable state retires completed work and hides active/future-retry claims so a bounded page keeps making progress when late corrections arrive. Retry attempts are ordered after never-attempted work to keep a repeatedly failing item from occupying every page.

R2 authoritative intent: each returned work overlays mutable delivery state (provider_posting/posting_owner) onto the immutable payload, so explicit V2 with legacy-empty payload and upgraded shadow (payload evidence-only, state monetary) are consumed as monetary V2/V1. Evidence identity (work ID) is validated before overlay and never changes.

func (*DurableStore) ListPendingProviderCostWork 

func (s *DurableStore) ListPendingProviderCostWork(ctx context.Context, limit int) ([]billing.ProviderCostWork, error)

func (*DurableStore) ListPendingUsageAppendWork 

func (s *DurableStore) ListPendingUsageAppendWork(ctx context.Context, limit int) ([]billing.UsageAppendWork, error)

func (*DurableStore) ListReconciliations 

func (s *DurableStore) ListReconciliations(ctx context.Context, query ReconciliationQuery) (ReconciliationPage, error)

func (*DurableStore) ListValuations 

func (s *DurableStore) ListValuations(ctx context.Context, query ValuationQuery) (ValuationPage, error)

func (*DurableStore) LoadEconomicRevisionDependencyOutput 

func (s *DurableStore) LoadEconomicRevisionDependencyOutput(ctx context.Context, dependency billing.EconomicJobDependency) (economics.Valuation, error)

LoadEconomicRevisionDependencyOutput reads one immutable dependency rating output by its exact revision valuation identity. A missing output is the retryable dependency_pending condition, not a zero valuation.

func (*DurableStore) LoadEconomicRevisionValuation 

func (s *DurableStore) LoadEconomicRevisionValuation(ctx context.Context, identity billing.EconomicRevisionIdentity) (economics.Valuation, error)

LoadEconomicRevisionValuation returns the exact immutable valuation persisted for one revision identity. It is the durable reader for provider-posting recovery: the returned InputSetHash is the full allocation-aware identity used on the fresh path, including the lenient legacy work/output seam. A missing valuation is reported as sql.ErrNoRows wrapped for retry; callers must not guess the identity from work alone.

func (*DurableStore) LookupStatementLines 

func (s *DurableStore) LookupStatementLines(ctx context.Context, identities []economics.StatementLineIdentity) (map[string]string, error)

LookupStatementLines returns the retained fingerprint for each found line revision identity, keyed by StatementLineIdentity.Key. The query is an exact, index-backed key probe bounded to the supplied identity set.

func (*DurableStore) LookupStatementRevision 

func (s *DurableStore) LookupStatementRevision(ctx context.Context, identity economics.StatementIdentity) (string, bool, error)

LookupStatementRevision returns the retained fingerprint for one immutable statement revision identity. A missing identity is not an error.

func (*DurableStore) MarkAccountReconcileRequired 

func (s *DurableStore) MarkAccountReconcileRequired(ctx context.Context, accountID string) error

func (*DurableStore) MarkProviderCostUnreconciled 

func (s *DurableStore) MarkProviderCostUnreconciled(ctx context.Context, input billing.ApplyProviderCostInput, reason string) error

func (*DurableStore) MarkUsageAppendProcessed 

func (s *DurableStore) MarkUsageAppendProcessed(ctx context.Context, key string) error

func (*DurableStore) OperatorCostReport 

func (s *DurableStore) OperatorCostReport(ctx context.Context, filter billing.ReportFilter) (billing.OperatorCostReport, error)

func (*DurableStore) PersistEconomicRevision 

func (s *DurableStore) PersistEconomicRevision(ctx context.Context, work billing.EconomicRevisionWork, result billing.EconomicRevisionResult) error

PersistEconomicRevision is an alias used by process composition code.

func (*DurableStore) PostAdjustment 

func (s *DurableStore) PostAdjustment(ctx context.Context, input billing.AdjustmentInput) (billing.Posting, error)

func (*DurableStore) PostFunding 

func (s *DurableStore) PostFunding(ctx context.Context, input billing.FundingInput) (billing.Posting, error)

func (*DurableStore) PostPayment 

func (s *DurableStore) PostPayment(ctx context.Context, input billing.PaymentInput) (billing.Posting, error)

func (*DurableStore) QueryALegReport 

func (s *DurableStore) QueryALegReport(ctx context.Context, query billing.ALegReportQuery) (billing.ALegReport, error)

func (*DurableStore) QueryAdjustments 

func (s *DurableStore) QueryAdjustments(ctx context.Context, query economics.AdjustmentQuery) (economics.AdjustmentPage, error)

QueryAdjustments returns bounded immutable corrections in (call, head, revision) order with one indexed join to the head for the latest frozen selection plane. Status, comparison, posting and selection come from their own durable columns and are never inferred from each other. Signed deltas (including downward corrections) pass through exactly; no-op transitions carry no delta.

func (*DurableStore) QueryDiscrepancies 

func (s *DurableStore) QueryDiscrepancies(ctx context.Context, query economics.DiscrepancyQuery) (economics.DiscrepancyPage, error)

QueryDiscrepancies returns bounded retained-reconciliation summaries in durable order. The requested account is enforced as an authoritative SQL predicate before ordering and LIMIT, so foreign or account-less retained evidence cannot leak into an account-only page, deny it, or shift its pagination. Rows parse through the canonical retention validator, so a corrupt payload fails closed instead of surfacing partial views.

func (*DurableStore) QueryEconomicDetail 

func (s *DurableStore) QueryEconomicDetail(ctx context.Context, query billing.EconomicDetailQuery) (billing.EconomicDetail, error)

QueryEconomicDetail returns the scoped economic detail for one billing call or one A-leg. Unknown calls/legs report billing.ErrReportNotFound; out-of-scope evidence reports billing.ErrEconomicDetailScopeMismatch; over-bound scopes report billing.ErrEconomicDetailBoundExceeded. A malformed, tampered, cross-scope/cross-kind or wrong-ordering cursor reports economics.ErrOperatorCursorInvalid before any trusted read. A continuation whose full-scope snapshot fingerprint changed (for example a resumed call inserted ahead of the position, or a late valuation/head/reconciliation/ allocation correction) reports economics.ErrOperatorCursorStale and requires restarting pagination. Storage failures carry no SQL text and no raw payload bytes.

func (*DurableStore) QueryOpenExposures 

func (s *DurableStore) QueryOpenExposures(ctx context.Context, accountID string, page billing.PageRequest) (billing.ExposurePage, error)

func (*DurableStore) QueryReconcileRequired 

func (s *DurableStore) QueryReconcileRequired(ctx context.Context, page billing.PageRequest) (billing.AccountStatePage, error)

func (*DurableStore) QueryStatementLines 

func (s *DurableStore) QueryStatementLines(ctx context.Context, query economics.StatementLineQuery) (economics.StatementLinePage, error)

QueryStatementLines returns bounded retained statement lines in line-key order over the existing scope index. Unmatched aggregate lines keep their statement/period scope and never gain a request linkage.

func (*DurableStore) ReadHistoricalV1CallBundle 

func (s *DurableStore) ReadHistoricalV1CallBundle(ctx context.Context, callID billing.BillingCallID) (billing.HistoricalV1CallBundle, error)

ReadHistoricalV1CallBundle returns one baseline V1 call with all of its V1 legs as legacy-opaque views. The bundle preserves old replay identity and already-posted balance semantics by performing read-only SELECTs only; it never writes journals, balances, or posting fences.

func (*DurableStore) ReadHistoricalV1Leg 

func (s *DurableStore) ReadHistoricalV1Leg(ctx context.Context, callID billing.BillingCallID, bLegID string) (billing.HistoricalV1LegView, error)

ReadHistoricalV1Leg returns the legacy-opaque view of one baseline V1 leg through the new storage/query path. Stored key, fingerprint and payload bytes must match the sealed replay identity exactly; any drift, V2 envelope, or ambiguous version fails closed.

func (*DurableStore) RebuildEconomicProjections 

func (s *DurableStore) RebuildEconomicProjections(ctx context.Context) error

func (*DurableStore) RebuildProjections 

func (s *DurableStore) RebuildProjections(ctx context.Context) error

func (*DurableStore) RebuildValuationProjections 

func (s *DurableStore) RebuildValuationProjections(ctx context.Context) error

RebuildValuationProjections recreates all line projections from immutable canonical valuation JSON and repairs projection-version drift.

func (*DurableStore) ReconcileAccount 

func (s *DurableStore) ReconcileAccount(ctx context.Context, accountID string) (billing.ReconciliationReport, error)

func (*DurableStore) ReconcileBillingAccount 

func (s *DurableStore) ReconcileBillingAccount(ctx context.Context, accountID string) (billing.BillingReconciliationReport, error)

func (*DurableStore) ReconcileOpenExposure 

func (s *DurableStore) ReconcileOpenExposure(ctx context.Context, accountID string) (billing.ExposureReconciliationReport, error)

func (*DurableStore) RepairExposureNoCharge 

func (s *DurableStore) RepairExposureNoCharge(ctx context.Context, callID billing.BillingCallID, sourceKey string) (billing.CallSettlement, error)

func (*DurableStore) RepairIncompleteCallNoCharge 

func (s *DurableStore) RepairIncompleteCallNoCharge(ctx context.Context, callID billing.BillingCallID, sourceKey string) (billing.CallSettlement, error)

func (*DurableStore) ResolveAllocationSupersession 

func (s *DurableStore) ResolveAllocationSupersession(ctx context.Context) (economics.AllocationSupersessionResult, error)

ResolveAllocationSupersession returns the typed fail-closed state for all durable allocation history. It reads canonical JSON only; projection rows cannot alter predecessor identity, source ownership, or pending status.

func (*DurableStore) ResolveEconomicRevisionPostingOwner 

func (s *DurableStore) ResolveEconomicRevisionPostingOwner(ctx context.Context, work billing.EconomicRevisionWork) (string, error)

ResolveEconomicRevisionPostingOwner returns the call-scoped durable posting owner admitted for one monetary work item, preferring the admitted customer pin for its account/call over any unbound global marker read. When no admitted pin exists it falls back to the current marker (V2 in v2_active, else V1); absent markers default to V1. Non-monetary shapes return "" (no posting owner). Operational failures fail closed.

func (*DurableStore) RetryCompleteCall 

func (s *DurableStore) RetryCompleteCall(ctx context.Context, callID billing.BillingCallID, code string) error

func (*DurableStore) RetryEconomicRevisionWork 

func (s *DurableStore) RetryEconomicRevisionWork(ctx context.Context, work billing.EconomicRevisionWork, claim billing.EconomicRevisionWorkClaim, reason string, nextAttemptAt time.Time) error

RetryEconomicRevisionWork makes a failed attempt due again and releases the lease. A caller may supply a future time for backoff; workers use the current time so the next bounded poll retries without starvation.

func (*DurableStore) RetryEconomicRevisionWorkWithReason 

func (s *DurableStore) RetryEconomicRevisionWorkWithReason(ctx context.Context, work billing.EconomicRevisionWork, claim billing.EconomicRevisionWorkClaim, reason billing.EconomicWorkReason, nextAttemptAt time.Time) error

RetryEconomicRevisionWorkWithReason makes a failed attempt due again with a bounded, closed retry reason and an explicit next-attempt time. The claim owner and fence must still match.

func (*DurableStore) SetAdjustmentFaultHook 

func (s *DurableStore) SetAdjustmentFaultHook(hook func(string) error)

SetAdjustmentFaultHook installs the B2b3 crash hook. Nil clears it.

func (*DurableStore) SetEconomicFaultHook 

func (s *DurableStore) SetEconomicFaultHook(hook func(string) error)

func (*DurableStore) StoreID 

func (s *DurableStore) StoreID() string

func (*DurableStore) TransitionAccountingCutover 

func (s *DurableStore) TransitionAccountingCutover(ctx context.Context, req billing.AccountingCutoverTransition) (billing.AccountingCutoverMarker, error)

TransitionAccountingCutover advances the marker by exactly one monotonic step using compare-and-swap on (version, epoch). Exact replay of the same expected version/epoch, target state, and transition identity returns the durable row without a second write. Stale CAS fails with billing.ErrAccountingCutoverFence; same-version advances with a different payload fail with billing.ErrAccountingCutoverConflict; malformed or non-monotonic targets fail with billing.ErrAccountingCutoverInvalid.

func (*DurableStore) TrialBalanceReport 

func (s *DurableStore) TrialBalanceReport(ctx context.Context, filter billing.ReportFilter) (billing.TrialBalanceReport, error)

func (*DurableStore) UsageAppendOutboxUnresolved 

func (s *DurableStore) UsageAppendOutboxUnresolved(ctx context.Context) (int, error)

UsageAppendOutboxUnresolved reports the destructive-migration proof input. It is intentionally a read-only query and does not silently classify failed or malformed work as obsolete.

func (*DurableStore) VerifyAccountingRecovery 

func (s *DurableStore) VerifyAccountingRecovery(ctx context.Context, capability billing.AccountingBinaryCapability) (billing.AccountingRecoverySnapshot, error)

VerifyAccountingRecovery enforces the serving-binary capability against the durable snapshot before the process admits or posts anything. Compatible binaries receive the snapshot; stale binaries receive ErrAccountingStaleBinary with zero writes, claims, postings, or drains.

type EconomicWorkMarker 

type EconomicWorkMarker struct {
	ID           string
	Version      uint64
	Kind         string
	SubjectKind  metering.SubjectKind
	SubjectID    string
	InputSetHash string
	PayloadJSON  json.RawMessage
	Status       string
	CreatedAt    time.Time
}

EconomicWorkMarker is a durable, immutable worker marker. It is not a financial journal and has no balance or money mutation fields.

type HistoricalAuthorizationJournal 

type HistoricalAuthorizationJournal struct {
	ID                    string
	AccountID             string
	Currency              string
	SourceKey             string
	SemanticFingerprint   string
	TurnID                string
	ALegID                string
	BLegID                string
	AccountSequence       *int64
	ReversalOf            string
	CorrectsTransactionID string
	CorrectionGroupID     string
	OperationKind         string
	BalanceBeforeNano     int64
	BalanceAfterNano      int64
	ReservedBeforeNano    int64
	ReservedAfterNano     int64
	SpendableBeforeNano   int64
	SpendableAfterNano    int64
	CreditFloorNano       int64
	CreditLimitNano       int64
	Mode                  string
	SnapshotVersionBefore uint64
	SnapshotVersionAfter  uint64
	RecordedAt            time.Time
	Entries               []billing.JournalEntry
}

Historical authorization audit decoder; isolated from current runtime reports. HistoricalAuthorizationJournal is an audit-only decode of a retired authorization posting. It is deliberately not billing.JournalTransaction: current validation, writers, reconciliation, and reports cannot post or replay this historical book.

type OperatorCursorAuthority 

type OperatorCursorAuthority interface {
	// DecodeAllowanceCursor authenticates the complete operator-bound cursor
	// before parsing it and returns the opaque inner journal continuation. A
	// legacy, tampered, replayed or cross-scope cursor fails closed with the
	// bounded operator invalid-cursor classification.
	DecodeAllowanceCursor(raw, storeID, filter string) (string, error)
	// EncodeAllowanceCursor binds an opaque inner journal continuation under
	// the allowance kind, the authorized store/filter scope and the journal
	// history order.
	EncodeAllowanceCursor(storeID, filter, source string) string
}

OperatorCursorAuthority authenticates and seals operator-reader continuation cursors under one durable store's server-owned key. It exists so a journal-backed operator reader can bind its continuation to the same single key authority as billingstore-native readers without exposing key material or introducing a second secret.

type ProviderCostWorkState 

type ProviderCostWorkState struct {
	Status        string
	AttemptCount  int
	NextAttemptAt time.Time
	LastError     string
}

ProviderCostWorkState is the durable retry state for one provider-cost leg. It intentionally exposes scheduling metadata without making deferred work appear due to ListPendingProviderCostWork.

type Reconciliation 

type Reconciliation = ReconciliationRecord

Reconciliation is a short alias for ReconciliationRecord.

type ReconciliationPage 

type ReconciliationPage struct {
	Reconciliations []ReconciliationRecord
	NextCursor      string
}

type ReconciliationQuery 

type ReconciliationQuery struct {
	StoreID      string
	SubjectKind  metering.SubjectKind
	SubjectID    string
	Subject      *metering.SubjectRef
	TenantID     string
	Scope        string
	Basis        economics.ValuationBasis
	InputSetHash string
	Limit        int
	Cursor       string
}

type ReconciliationRecord 

type ReconciliationRecord struct {
	ID      string
	Version uint64
	Subject metering.SubjectRef
	Scope   string
	Basis   economics.ValuationBasis
	// ResultSchemaVersion distinguishes the original single-basis envelope
	// from the full-result retention envelope. Zero is normalized to the
	// legacy envelope version.
	ResultSchemaVersion uint32
	InputSetHash        string
	InputHash           string // compatibility alias for InputSetHash
	LocalInputHash      string
	ProviderInputHash   string
	PolicyID            string
	PolicyVersion       string
	ResultJSON          json.RawMessage
	Result              json.RawMessage // compatibility alias for ResultJSON
	CreatedAt           time.Time
}

ReconciliationRecord is the minimal immutable V2 reconciliation envelope. ResultJSON is canonical JSON and can contain a domain-specific result shape; the storage layer does not infer provider or customer semantics from it.

func ReconciliationRecordFromRetention 

func ReconciliationRecordFromRetention(result billing.ReconciliationRetentionResult) (ReconciliationRecord, error)

ReconciliationRecordFromRetention maps the canonical full result into the durable reconciliation envelope. It does not write anything.

func (ReconciliationRecord) CanonicalJSON 

func (r ReconciliationRecord) CanonicalJSON() ([]byte, error)

func (ReconciliationRecord) Fingerprint 

func (r ReconciliationRecord) Fingerprint() string

type ReconciliationRetentionQuery 

type ReconciliationRetentionQuery struct {
	SubjectKind metering.SubjectKind
	SubjectID   string
	TenantID    string
}

ReconciliationRetentionQuery selects the newest durable full-result reconciliation for one explicitly subject-scoped economic scope. The subject kind and id are required and bounded; the optional tenant refines the same subject partition. Scope- or input-set-hash-only predicates are deliberately unsupported because the retention index is subject-leading and those shapes could scan an unbounded number of rows for a single result.

type ShadowV2Capture 

type ShadowV2Capture struct {
	// contains filtered or unexported fields
}

ShadowV2Capture is the explicit no-post shadow orchestrator. Each field is a narrow pure port; no monetary writer type appears in this struct by design. Evidence capture uses the capture-only ShadowEvidenceSink, never the ordinary terminal handoff, so shadow legs/calls cannot become V1 posting or claim work.

func NewShadowV2Capture 

func NewShadowV2Capture(
	cfg ShadowV2CaptureConfig,
	evidence billing.ShadowEvidenceSink,
	work billing.EconomicRevisionWorkAppender,
	results billing.EconomicRevisionResultStore,
	reconciliations billing.EconomicRevisionReconciliationStore,
	rater billing.PostUsageRater,
) (*ShadowV2Capture, error)

NewShadowV2Capture constructs the shadow runner with explicit pure ports. A nil or typed-nil port fails closed. The V1 monetary writer is intentionally not a parameter: V1 ownership stays on its existing settlement path while this handle cannot address it.

func (*ShadowV2Capture) AppendReconciliation 

func (s *ShadowV2Capture) AppendReconciliation(ctx context.Context, work billing.EconomicRevisionWork, reconciliation billing.EconomicReconciliation) error

AppendReconciliation persists one immutable reconciliation envelope for dependency-anchored work. The envelope identity must match the work; no account, journal, exposure, or financial head row is touched. The effective observation bound applies before normalization.

func (*ShadowV2Capture) AppendWork 

func (s *ShadowV2Capture) AppendWork(ctx context.Context, work billing.EconomicRevisionWork) error

AppendWork persists one immutable economic revision marker idempotently. The work subject must belong to this shadow store scope. The effective observation bound applies to embedded, ref-only, and combined forms before normalization.

func (*ShadowV2Capture) CaptureObservations 

func (s *ShadowV2Capture) CaptureObservations(ctx context.Context, observations []metering.Observation) error

CaptureObservations durably captures immutable V2 source-separated observations through the capture-only evidence port. Every observation counts against the configured bound, and every observation's store scope must match the shadow scope. Observations reference existing executions by lineage; capturing them creates no usage call/leg rows, claim state, provider-cost work, or payable intent. There is deliberately no shadow call-closure method: closure has no independent V2 evidence beyond the observations, valuations, and reconciliation already persisted here.

func (*ShadowV2Capture) RateAndPersist 

func (s *ShadowV2Capture) RateAndPersist(ctx context.Context, work billing.EconomicRevisionWork) error

RateAndPersist computes the pure valuation for one revision through the single shared worker normalization contract and persists it idempotently. The contract preserves the full valid rater clone and anchors CreatedAt to immutable work metadata, so repeated or overlapping calls with a deterministic rater persist one stable row. The durable store provides idempotency; no probe-gated no-rerate promise is made here. No balance, journal, unit, or provider-payable mutation occurs on this path.

type ShadowV2CaptureConfig 

type ShadowV2CaptureConfig struct {
	StoreID         string
	MaxObservations int
}

ShadowV2CaptureConfig is the explicit typed shadow-mode configuration. It carries no monetary account, tariff, balance, or posting field; StoreID scopes every durable write and MaxObservations bounds one work envelope.

func (ShadowV2CaptureConfig) Validate 

func (c ShadowV2CaptureConfig) Validate() error

Validate fails closed on missing scope or unbounded work size.

type ShadowV2ComparisonInput 

type ShadowV2ComparisonInput struct {
	Label          string
	Currency       string
	V1Nano         int64
	V2Nano         int64
	ExpectedV2Nano int64
	ReasonCode     string
}

ShadowV2ComparisonInput is one comparison point. Label is a strict stable token (never raw content). V1Nano is the documented legacy amount, V2Nano is the actual persisted V2 amount, and ExpectedV2Nano is the independently derived expected V2 amount. ReasonCode is empty when no fix is claimed; otherwise it must name an allowlisted defect-fix rule.

type ShadowV2ComparisonResult 

type ShadowV2ComparisonResult struct {
	Verdict   ShadowV2ComparisonVerdict
	DeltaNano int64
	Detail    string
}

ShadowV2ComparisonResult carries the verdict, signed actual-minus-V1 delta, and a sanitized detail string over validated tokens only.

func CompareShadowV2Semantics 

func CompareShadowV2Semantics(in ShadowV2ComparisonInput) (ShadowV2ComparisonResult, error)

CompareShadowV2Semantics classifies one actual-V2 against its independent expectation. Error paths never echo unsafe input; detail strings quote only validated label and reason tokens.

type ShadowV2ComparisonVerdict 

type ShadowV2ComparisonVerdict string

ShadowV2ComparisonVerdict is the closed classification vocabulary. 

const (
	// ShadowV2Match means V1 and actual V2 agree exactly with no claimed fix.
	ShadowV2Match ShadowV2ComparisonVerdict = "match"
	// ShadowV2ExpectedFix means actual V2 exactly equals the independently
	// derived expected V2 under an allowlisted defect-fix reason.
	ShadowV2ExpectedFix ShadowV2ComparisonVerdict = "expected_fix"
	// ShadowV2UnexpectedDrift means actual V2 differs from expectation, or a
	// claimed fix is inconsistent with the observed amounts.
	ShadowV2UnexpectedDrift ShadowV2ComparisonVerdict = "unexpected_drift"
)

type ValuationPage 

type ValuationPage struct {
	Valuations []economics.Valuation
	NextCursor string
}

type ValuationQuery 

type ValuationQuery struct {
	StoreID      string
	SubjectKind  metering.SubjectKind
	SubjectID    string
	Subject      *metering.SubjectRef
	TenantID     string
	Scope        string
	Basis        economics.ValuationBasis
	InputSetHash string
	Limit        int
	Cursor       string
}

ValuationQuery scopes a bounded valuation listing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.