Draft agent price pilot contracts

The offline pilot uses existing DataContract instances. See the pilot design and runtime qualification record for the approved public-offer meaning, first-trial gates and remaining implementation boundaries. No browser runtime or publication gate is supplied by these examples.

All contracts use namespace agent_price_pilot and envelope pycharter.io/v2. Import the desired version explicitly; example files are authoring material, not a runtime registry. Build validators from exact retained Store identities.

Name	Historical 0.1.0	Public-offer 0.2.0
watchlist_target	Requested ordinary-price category	Requested public_single_item_unconditional_v1 offer policy
raw_price_observation	Displayed money/package and observed identity/category	Adds explicit observed role and conditions; preserves unknown currency and excluded candidates
price_observation	Ordinary HKD integer cents	Ordinary/promotional offered HKD integer cents with empty conditions; unavailable price/classification fields all explicit null

Historical files remain under src/pycharter/data/seed/examples/agent_price_pilot/contracts/. Version 0.2.0 lives under src/pycharter/data/seed/examples/agent_price_pilot/v0_2_0/contracts/.

Opting into 0.2.0

This is an incompatible draft contract revision, supplied additively. Review the target, import version 0.2.0 and update its exact references. Do not overwrite a retained 0.1.0 identity or reinterpret its observations. Existing records need evidence review or re-observation before assigning a new role or unconditional status. There is no automatic migration of unknown facts.

For an accepted observed record, preserve a discounted offer as promotional. A reference/list/comparison amount cannot become an offer, and a member, coupon, multi-buy, exchange or checkout-dependent amount cannot become unconditional. Raw price_conditions: null means unknown; [] means no eligibility conditions identified and still requires independent evidence. Unknown currency stays null in raw output. Accepted observed rows require HKD and positive strict integer cents. Numeric strings, floats, booleans and zero fail that money boundary.

For an accepted unavailable record, the correct product must explicitly be unavailable. All price/classification fields are required and null, including currency. A missing page, uncertain navigation or unresolved eligible offer is not evidence of unavailability. Missing, null, unknown and zero remain distinct. Timezone-aware observed_at uses the existing declared datetime coercion; field-local string constraints retain the timezone requirement.

Validation boundary

The 27 synthetic version 0.2.0 fixture cases test record schemas and paired raw/final ambiguities. A schema can accept a wrongly labeled discount, a reference changed to an offer, dropped conditions or a fabricated identity. AGPIPE-3 must compare retained records and independently supported facts; valid rows alone do not establish factual accuracy, evidence availability, freshness or complete target coverage. No money/package parser is implemented.

Focused offline checks:

python -m pytest tests/unit/test_agent_price_pilot.py tests/unit/test_agent_public_offer_pilot.py
python -m pytest tests/integration/test_agent_price_pilot_lifecycle.py tests/integration/test_agent_public_offer_pilot_lifecycle.py -m ""

Use the isolated test-service configuration in CONTRIBUTING.md to exercise all supported backends. The version 0.2.0 lifecycle test imports both revisions, removes the authoring files, then builds and validates exact retained versions across in-memory, SQLite, PostgreSQL, MongoDB and Redis. Synthetic fixtures use example URLs and perform no browser/provider execution.