# `Accrue.Entitlements.StripeSync`
[🔗](https://github.com/szTheory/accrue/blob/accrue-v1.5.1/lib/accrue/entitlements/stripe_sync.ex#L1)

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.

# `refresh`
*since 1.5.0* 

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*