Implement Stripe publication layer and close WP-0007

docs/StripePublication.md

@@ -0,0 +1,114 @@
+# 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.