# Stripe Publication

Status: MVP for `ADAPTIVE-WP-0007`.

## Purpose

This milestone adds the first outbound execution layer for pricing models.

The implementation keeps `adaptive-pricing` as the source of truth and treats
Stripe as an execution backend. In this repository, publication targets a
file-backed Stripe shadow state rather than the live Stripe API.

## Core Modules

- `adaptive_pricing_core/provider_publication.py`
- `adaptive_pricing_core/stripe_provider.py`

The provider-publication core defines:

- provider-neutral publishable artifacts
- publication plans and operations
- drift findings
- revisioned shadow state
- rollback mechanics

The Stripe mapper translates publishable artifacts into Stripe-oriented objects
and marks each mapping as:

- `exact`
- `approximate`
- `unsupported`

## Publishable Artifact Model

Current provider-neutral artifacts:

- product
- meter
- price
- commitment
- configuration

Current Stripe-oriented object types:

- `product`
- `billing_meter`
- `price`
- `coupon`
- `metadata_binding`

`metadata_binding` is used for execution-adjacent information that Stripe can
store as metadata but does not treat as a first-class pricing object.

## Mapping Semantics

Current exact mappings:

- catalog product identity and metadata
- fixed recurring and one-time prices
- metered usage prices without bundled allowance semantics
- Stripe meter definitions

Current approximate mappings:

- metered prices that also imply included usage
- discount components mapped as coupon-like artifacts
- contract-duration commitments carried as metadata or schedule-adjacent data
- configuration artifacts carried as metadata

Current unsupported mappings:

- included-usage-only components without a billable per-unit overage price
- commitment semantics such as prepayment or minimum turnover when Stripe alone
  cannot enforce them

## Coulomb Adapter

Project adapter:

- `projects/coulomb-pricing/observatory/publication.py`
- `projects/coulomb-pricing/observatory/publish.py`

Default local shadow-state path:

- `projects/coulomb-pricing/data/provider_state/stripe-publication.json`

Preview:

```bash
cd projects/coulomb-pricing
python3 -m observatory.publish --model-id flat-899-eur-monthly
```

Apply to the local shadow state:

```bash
cd projects/coulomb-pricing
python3 -m observatory.publish --model-id flat-899-eur-monthly --apply
```

Rollback:

```bash
cd projects/coulomb-pricing
python3 -m observatory.publish --rollback stripe-rev-0001
```

## Current Scope Limit

This milestone does not call the live Stripe API.

It establishes the internal publication model, Stripe object mapping,
idempotent shadow-state synchronization, drift detection, and rollback path so
live API execution can be layered on without making Stripe the source of truth.