fix: reconcile hidden charge base intents (#4677)

Author: turip

.agents/skills/charges/SKILL.md

@@ -126,8 +126,9 @@ Patch target rules:
 - Charge patch payloads carry `billing.ChangeSource` source intent instead of an explicit target whenever the target can be derived. Do not rely on a zero/default source.
 - Subscription sync emits system-sourced patches because it reconciles subscription-owned source state, not user/API overrides.
 - State machines resolve the effective target layer from base intent ownership, override presence, and patch source. System period patches target base only and must reject API-sourced period changes. API manual edits/deletes target an existing override when present, target base for manually managed base intents without an override, and create/target an override for subscription/system-owned base intents.
-- State machines should mutate the resolved patch target, then reconcile customer-facing invoice artifacts from the effective intent. If a base-target patch hits a charge with an active override, updating the base layer should not rewrite effective invoice state.
-- Delete patches follow the same target rule: deleting the base layer while an override is active should mark the base intent deleted but leave the effective override-backed charge behavior intact.
+- Type-specific state machines own only active customer-facing charge lifecycle: status transitions, realization runs, credit corrections, and invoice patches. If a patch targets the base layer while an override exists, that base layer is hidden source state and the state machine must reject it instead of treating it as a lifecycle no-op.
+- Subscription-sync and repair paths may still need to reconcile hidden base/source intent fields, such as base period shrink/extend/delete under an active override. Apply those updates before state-machine dispatch in service-level reconciliation, persist only the source intent, and do not emit invoice patches or mutate realization/customer-facing state from that path.
+- Delete patches follow the same target rule: deleting the hidden base layer while an override is active should mark only the base intent deleted through the service-level source reconciliation path and leave the effective override-backed charge behavior intact.
 - Charge listing for subscription-sync persisted-state loading must filter on base-intent deletion state, not effective `DeletedAt`; otherwise an active override can hide a subscription-owned base charge that sync still needs to reconcile.
 - Gathering-line upsert patches are target-state patches. `PatchOpUpsertGatheringLineByChargeID` should carry the full rebuilt `billing.GatheringLine` target state, not just period deltas. The invoice updater queries the existing pending gathering line by charge ID and merges the patch target with `WithTargetState(...)` so DB identity and invoice membership stay intact; if no active pending line exists, it creates one through the regular pending-line provisioning path.
 - `PatchShrink` is system-only and always targets the base layer. API/customer-originated period shortening must use a distinct API patch such as `PatchShrinkToRealizedPeriod`, which resolves its target layer through API patch rules and creates or updates the override layer when the base intent is subscription-managed.

openmeter/billing/charges/flatfee/service/creditheninvoice.go

@@ -165,19 +165,16 @@ func (s *CreditThenInvoiceStateMachine) DeleteCharge(ctx context.Context, patch
 	if err != nil {
 		return fmt.Errorf("getting patch target layer: %w", err)
 	}
+	if err := s.rejectHiddenIntentTarget(target); err != nil {
+		return err
+	}
 
 	if err := s.mutateIntentLayer(ctx, target, func(fields *flatfee.IntentMutableFields) {
 		fields.IntentDeletedAt = deletedAt
 	}); err != nil {
 		return fmt.Errorf("deleting intent: %w", err)
 	}
 
-	if target == meta.ChangeTargetBase && s.Charge.Intent.HasOverrideLayer() {
-		// Subscription sync targets the base intent. When an override is active,
-		// the customer-facing charge and invoice history remain owned by the override.
-		return nil
-	}
-
 	s.Charge.Status = flatfee.StatusDeleted
 
 	patches := invoiceupdater.Patches{
@@ -220,10 +217,6 @@ func (s *CreditThenInvoiceStateMachine) ExtendCharge(ctx context.Context, patch
 		return err
 	}
 
-	if !invoicingStateInput.ShouldReconcile {
-		return nil
-	}
-
 	return s.reconcileInvoicingState(ctx, invoicingStateInput)
 }
 
@@ -233,10 +226,6 @@ func (s *CreditThenInvoiceStateMachine) ShrinkCharge(ctx context.Context, patch
 		return err
 	}
 
-	if !invoicingStateInput.ShouldReconcile {
-		return nil
-	}
-
 	return s.reconcileInvoicingState(ctx, invoicingStateInput)
 }
 
@@ -245,6 +234,9 @@ func (s *CreditThenInvoiceStateMachine) LineManualEdit(ctx context.Context, patc
 	if err != nil {
 		return fmt.Errorf("getting patch target layer: %w", err)
 	}
+	if err := s.rejectHiddenIntentTarget(target); err != nil {
+		return err
+	}
 
 	override := patch.GetOverride()
 	if err := meta.ValidateInvoiceLineOverrideDoesNotChangeImmutableChargeIntentFields(override); err != nil {
@@ -332,7 +324,6 @@ func (s *CreditThenInvoiceStateMachine) LineManualEdit(ctx context.Context, patc
 	}
 
 	return s.reconcileInvoicingState(ctx, reconcileInvoicingStateInput{
-		ShouldReconcile:         true,
 		Op:                      meta.PatchTypeLineManualEdit,
 		Period:                  s.Charge.Intent.GetEffectiveServicePeriod(),
 		Intent:                  s.Charge.Intent,
@@ -346,6 +337,9 @@ func (s *CreditThenInvoiceStateMachine) applyPeriodPatch(patch periodPatch) (rec
 	if err != nil {
 		return reconcileInvoicingStateInput{}, fmt.Errorf("getting patch target layer: %w", err)
 	}
+	if err := s.rejectHiddenIntentTarget(target); err != nil {
+		return reconcileInvoicingStateInput{}, err
+	}
 
 	targetIntent, err := s.Charge.Intent.GetIntentForTarget(target)
 	if err != nil {
@@ -367,19 +361,12 @@ func (s *CreditThenInvoiceStateMachine) applyPeriodPatch(patch periodPatch) (rec
 
 	s.Charge.Intent = intent
 
-	if target == meta.ChangeTargetBase && s.Charge.Intent.HasOverrideLayer() {
-		// Subscription sync targets the base intent. When an override is active,
-		// the customer-facing invoice remains owned by the override layer.
-		return reconcileInvoicingStateInput{}, nil
-	}
-
 	amountAfterProration, err := intent.CalculateAmountAfterProration()
 	if err != nil {
 		return reconcileInvoicingStateInput{}, fmt.Errorf("calculating amount after proration: %w", err)
 	}
 
 	return reconcileInvoicingStateInput{
-		ShouldReconcile:         true,
 		Op:                      patch.Op(),
 		Period:                  intent.GetEffectiveServicePeriod(),
 		Intent:                  intent,
@@ -520,7 +507,6 @@ func (s *CreditThenInvoiceStateMachine) AreAllPaymentsSettled() bool {
 }
 
 type reconcileInvoicingStateInput struct {
-	ShouldReconcile         bool
 	Op                      meta.PatchType
 	Period                  timeutil.ClosedPeriod
 	Intent                  flatfee.OverridableIntent

openmeter/billing/charges/flatfee/service/creditsonly.go

@@ -148,6 +148,10 @@ func (s *CreditsOnlyStateMachine) applyPeriodPatch(ctx context.Context, patch pe
 		return fmt.Errorf("getting patch target layer: %w", err)
 	}
 
+	if err := s.rejectHiddenIntentTarget(target); err != nil {
+		return err
+	}
+
 	targetIntent, err := s.Charge.Intent.GetIntentForTarget(target)
 	if err != nil {
 		return fmt.Errorf("getting %s intent: %w", target, err)
@@ -169,12 +173,6 @@ func (s *CreditsOnlyStateMachine) applyPeriodPatch(ctx context.Context, patch pe
 
 	s.Charge.Intent = intent
 
-	if target == meta.ChangeTargetBase && s.Charge.Intent.HasOverrideLayer() {
-		// Subscription sync targets the base intent. When an override is active,
-		// customer-facing credit allocations remain owned by the override.
-		return nil
-	}
-
 	amountAfterProration, err := intent.CalculateAmountAfterProration()
 	if err != nil {
 		return fmt.Errorf("calculating amount after proration: %w", err)
@@ -244,18 +242,16 @@ func (s *CreditsOnlyStateMachine) DeleteCharge(ctx context.Context, patch meta.P
 		return fmt.Errorf("getting patch target layer: %w", err)
 	}
 
+	if err := s.rejectHiddenIntentTarget(target); err != nil {
+		return err
+	}
+
 	if err := s.mutateIntentLayer(ctx, target, func(fields *flatfee.IntentMutableFields) {
 		fields.IntentDeletedAt = deletedAt
 	}); err != nil {
 		return fmt.Errorf("deleting intent: %w", err)
 	}
 
-	if target == meta.ChangeTargetBase && s.Charge.Intent.HasOverrideLayer() {
-		// Subscription sync targets the base intent. When an override is active,
-		// customer-facing credit allocations remain owned by the override.
-		return nil
-	}
-
 	s.Charge.Status = flatfee.StatusDeleted
 
 	if patch.GetPolicy().CreditRefundPolicy == meta.CreditRefundPolicyCorrect && s.Charge.Realizations.CurrentRun != nil {

openmeter/billing/charges/flatfee/service/statemachine.go

@@ -12,6 +12,7 @@ import (
 	"github.com/openmeterio/openmeter/openmeter/billing/charges/meta"
 	chargestatemachine "github.com/openmeterio/openmeter/openmeter/billing/charges/statemachine"
 	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/models"
 )
 
 type stateMachine struct {
@@ -131,6 +132,22 @@ func (s *stateMachine) mutateIntentLayer(ctx context.Context, target meta.Change
 	return nil
 }
 
+// rejectHiddenIntentTarget prevents lifecycle state machines from processing a
+// hidden source intent. When an override layer exists, the override is the
+// active customer-facing charge: it owns status transitions, realization runs,
+// credit corrections, and invoice patches. Subscription-owned base/source
+// changes must be applied before state-machine dispatch by service-level
+// reconciliation, not interpreted as lifecycle events.
+func (s *stateMachine) rejectHiddenIntentTarget(target meta.ChangeTarget) error {
+	if target == meta.ChangeTargetBase && s.Charge.Intent.HasOverrideLayer() {
+		return models.NewGenericPreConditionFailedError(
+			fmt.Errorf("cannot mutate hidden base intent while override intent is active"),
+		)
+	}
+
+	return nil
+}
+
 func (s *stateMachine) IsInsideServicePeriod() bool {
 	return !clock.Now().Before(s.Charge.Intent.GetEffectiveServicePeriod().From)
 }

openmeter/billing/charges/flatfee/service/triggers.go

@@ -8,6 +8,7 @@ import (
 	"github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee"
 	"github.com/openmeterio/openmeter/openmeter/billing/charges/meta"
 	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/clock"
 	"github.com/openmeterio/openmeter/pkg/framework/transaction"
 	"github.com/openmeterio/openmeter/pkg/models"
 )
@@ -45,6 +46,26 @@ func (s *service) TriggerPatch(ctx context.Context, chargeID meta.ChargeID, patc
 	var result meta.TriggerPatchResult[flatfee.Charge]
 
 	charge, err := s.withLockedCharge(ctx, chargeID, func(ctx context.Context, charge flatfee.Charge) (*flatfee.Charge, error) {
+		chargeWithUpdatedBase, err := applyBaseIntentPatchForOverriddenCharge(charge, patch)
+		if err != nil {
+			return nil, err
+		}
+
+		if chargeWithUpdatedBase != nil {
+			// Hidden base/source intent changes are subscription reconciliation,
+			// not customer-facing lifecycle events. Persist the source intent and
+			// skip the state machine because the active override owns lifecycle
+			// state and hidden targets are rejected there.
+			updatedChargeBase, err := s.adapter.UpdateCharge(ctx, chargeWithUpdatedBase.ChargeBase)
+			if err != nil {
+				return nil, fmt.Errorf("updating flat fee charge[%s] base intent: %w", chargeWithUpdatedBase.ID, err)
+			}
+
+			chargeWithUpdatedBase.ChargeBase = updatedChargeBase
+
+			return chargeWithUpdatedBase, nil
+		}
+
 		stateMachine, err := s.newStateMachine(StateMachineConfig{
 			Charge:               charge,
 			Adapter:              s.adapter,
@@ -75,6 +96,65 @@ func (s *service) TriggerPatch(ctx context.Context, chargeID meta.ChargeID, patc
 	return result, nil
 }
 
+func applyBaseIntentPatchForOverriddenCharge(charge flatfee.Charge, patch meta.Patch) (*flatfee.Charge, error) {
+	target, err := patch.GetTargetLayer(charge.Intent)
+	if err != nil {
+		return nil, fmt.Errorf("getting patch target layer: %w", err)
+	}
+
+	if target != meta.ChangeTargetBase || !charge.Intent.HasOverrideLayer() {
+		return nil, nil
+	}
+
+	switch patch := patch.(type) {
+	case meta.PatchDelete:
+		if err := charge.Intent.Mutate(meta.ChangeTargetBase, func(fields *flatfee.IntentMutableFields) {
+			deletedAt := clock.Now()
+			fields.IntentDeletedAt = &deletedAt
+		}); err != nil {
+			return nil, fmt.Errorf("mutating base intent for %s patch: %w", patch.Op(), err)
+		}
+
+		return &charge, nil
+	case meta.PatchShrink:
+		if err := mutateBaseIntentPeriodForOverriddenCharge(&charge, patch); err != nil {
+			return nil, err
+		}
+
+		return &charge, nil
+	case meta.PatchExtend:
+		if err := mutateBaseIntentPeriodForOverriddenCharge(&charge, patch); err != nil {
+			return nil, err
+		}
+
+		return &charge, nil
+	}
+
+	return nil, nil
+}
+
+func mutateBaseIntentPeriodForOverriddenCharge(charge *flatfee.Charge, patch periodPatch) error {
+	targetIntent, err := charge.Intent.GetIntentForTarget(meta.ChangeTargetBase)
+	if err != nil {
+		return fmt.Errorf("getting base intent: %w", err)
+	}
+
+	if err := patch.ValidateWith(targetIntent.IntentMutableFields.IntentMutableFields); err != nil {
+		return fmt.Errorf("validate %s patch: %w", patch.Op(), err)
+	}
+
+	if err := charge.Intent.Mutate(meta.ChangeTargetBase, func(fields *flatfee.IntentMutableFields) {
+		fields.ServicePeriod.To = patch.GetNewServicePeriodTo()
+		fields.FullServicePeriod.To = patch.GetNewFullServicePeriodTo()
+		fields.BillingPeriod.To = patch.GetNewBillingPeriodTo()
+		fields.InvoiceAt = patch.GetNewInvoiceAt()
+	}); err != nil {
+		return fmt.Errorf("mutating base intent for %s patch: %w", patch.Op(), err)
+	}
+
+	return nil
+}
+
 func (s *service) newStateMachine(config StateMachineConfig) (StateMachine, error) {
 	switch config.Charge.Intent.GetSettlementMode() {
 	case productcatalog.CreditOnlySettlementMode:

openmeter/billing/charges/meta/patch.go

@@ -67,6 +67,7 @@ type Patch interface {
 
 	Op() PatchType
 	Trigger() stateless.Trigger
+	GetTargetLayer(LayeredIntentReader) (ChangeTarget, error)
 }
 
 type TriggerPatchResult[T any] struct {