Read-only observational seam over the optional Stripe-native
entitlement-summary cache (accrue_entitlement_summaries, ENT-10).
This module exposes the advisory cache row for a customer so operators and dashboards can observe what Stripe last reported — it is NOT a gate API and answers no grant/deny question.
Observational-only (D-01 / D-11)
The advisory cache is recorded, ledgered, telemetered, and surfaced here,
but it is never consulted to decide a grant. Local plan→feature
mapping stays canonical. The gate path — Accrue.entitled?/2,
Accrue.has_active_plan?/2, Accrue.Entitlements.Resolver, and
Accrue.Entitlements.Resolver.LocalMap — MUST NOT reference this module
or the Accrue.Billing.EntitlementSummary schema. The static gate
scripts/ci/verify_entitlement_sync_isolation.sh (Plan 03) enforces this
at merge time; this module deliberately keeps the dependency one-way.
One-way dependency
seam → billing, never gate → seam. When a host enables
stripe_native_sync: :advisory, webhook handling and client-backed pull refresh write the same advisory Accrue.Billing.EntitlementSummary row through Accrue.Entitlements.Reconcile. The feature is off by default and diagnostic only; neither path can influence grants. Local plan→feature mapping remains the sole Accrue grant authority.
Summary
Functions
Refreshes the observational entitlement-summary cache for one customer.
Functions
@spec refresh( Accrue.Billing.Customer.t(), keyword() ) :: {:ok, Accrue.Billing.EntitlementSummary.t() | :disabled | :unchanged | :stale} | {:error, term()}
Refreshes the observational entitlement-summary cache for one customer.
The refresh is disabled by default and returns {:ok, :disabled} before
any processor or repository I/O unless stripe_native_sync: :advisory is
enabled. The resulting cache row is diagnostic only and is never consulted
by grant decisions.