feat: subs-sync credits support

[turip]

Overview

This refactor introduces a package-owned persisted-state abstraction for subscription sync, replacing direct billing.LineOrHierarchy usage with typed persistedstate.Item wrappers and moving referenced invoice loading into
the persisted snapshot itself. It also restructures reconciliation around per-persisted-shape invoice patch collections, so line-backed and split-line-hierarchy-backed states are patched through separate direct-billing
paths while preserving current behavior. Along the way, target filtering for direct billing was made explicit, unknown persisted invoices now surface errors instead of being silently assumed gathering, and the progressive
billing cancellation path was fixed so emptied hierarchy children are deleted rather than updated.

Detailed changes

The main differences introduced by this refactor in subscriptionsync are:

• Persisted-state boundary is now package-owned instead of exposing raw billing.LineOrHierarchy.
  See openmeter/billing/worker/subscriptionsync/service/persistedstate/item.go, openmeter/billing/worker/subscriptionsync/service/persistedstate/state.go, openmeter/billing/worker/subscriptionsync/service/persistedstate/
  loader.go.
• Persisted invoices are now part of persistedstate.State, and only invoices referenced by loaded persisted entities are fetched.
  This is a real behavior change versus main, which loaded broader customer invoice state.
  Missing referenced invoices now fail explicitly instead of being tolerated.
• Invoices.IsGatheringInvoice(...) now returns an error when an invoice is unknown instead of assuming “gathering”.
  That is a meaningful safety change.
• Reconciler planning no longer builds deferred concrete patch structs like CreatePatch, ShrinkUsageBasedPatch, ProratePatch.
  It now emits realized invoice patches through per-shape collections.
  See openmeter/billing/worker/subscriptionsync/service/reconciler/patch.go, openmeter/billing/worker/subscriptionsync/service/reconciler/patchinvoice.go, openmeter/billing/worker/subscriptionsync/service/reconciler/
  patchinvoiceline.go, openmeter/billing/worker/subscriptionsync/service/reconciler/patchinvoicelinehierarchy.go.
• Reconciler is now routed by persisted item type.
  Existing line-backed and hierarchy-backed states go through separate patching logic, which is the main architectural change for future charge support.
• semanticProrateDecision moved out into openmeter/billing/worker/subscriptionsync/service/reconciler/prorate.go and now owns expected-line rendering itself.
• diffItem(...) no longer depends on rendered line state for period comparison.
  It now uses target-state service period directly via openmeter/billing/worker/subscriptionsync/service/targetstate/targetstateitem.go.
• Direct billing sync now filters target items before diffing:
  non-billable items and items whose GetExpectedLine() is nil are removed from invoice-sync scope up front.
  See openmeter/billing/worker/subscriptionsync/service/reconciler/reconciler.go.
• Targetstate annotation handling no longer branches on raw billing types.
  The persisted-item abstraction now owns “subscription managed” and “last line annotation” semantics.
  See openmeter/billing/worker/subscriptionsync/service/targetstate/targetstate.go and openmeter/billing/worker/subscriptionsync/service/persistedstate/item.go.
• The hierarchy shrink path now deletes an emptied usage-based child instead of updating it.
  That was a real behavior fix validated by the progressive billing cancellation scenario.

Fixes #(issue)

Notes for reviewer

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 46a48f4a-2fdf-4f83-a58c-aa898375eb7d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/subs-sync-credits-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}