adaptive-pricing/docs/StripePublication.md

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:

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

Apply to the local shadow state:

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

Rollback:

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.