Contract Artifacts (Status)

This page lists the contract artifacts tracked during implementation. Status values reflect current implementation maturity. For published OpenAPI and schema files, see /common/schemas.html.

Required artifact types

• OpenAPI: public API Gateway surfaces.
• JSON Schema: shared envelopes and domain objects.
• Event schemas: event names, versions, payload shape, and redaction rules.
• Request-context schema: canonical org/facility/channel/roles/cost-centre context.

Planned artifacts by module (approved baseline)

Module	OpenAPI	JSON Schema	Event Schemas	Notes
ICS	Published	Shared	Published	Inventory and warehouse workflows.
SCM	Published	Shared	Published	Orders, returns, tenders, and fulfillment.
PCM	Published	Shared	Published	POs, receipts, invoices, RTV.
PPM	Published	Shared	Published	Pricing, promotions, price snapshots.
CRM/Loyalty	Published	Shared	Published	Customer, loyalty, stored value.
Influencer	Published	Shared	Published	Attribution, earnings, payouts.
Accounting	Published	Shared	Published	Exportable financial events.
IPM	Published	Shared	Published	Integration plane surfaces (catalog/webhooks/CDC/bulk).
RBS	Published	Shared	Published	Owner-only event delivery to customer SQS queues.
External Master Data	No API Gateway	Planned	Planned	Direct Lambda + CLI only.

Note: Shared means common envelope/request-context/error schemas are published; domain-specific JSON schemas are still evolving.

Minimum coverage expectations

• Each module defines its core entities, lifecycle status model, and required policy surfaces.
• Events include org/facility/channel scope, actor, reason, source references, and policy snapshot references.
• Event schemas embed request_context snapshots (org/facility/channel/roles/cost-centre) for auditability.
• Error taxonomy and retry guidance follow the common contract.
• Request-context mapping is defined for every surface (headers vs body vs query).
• Error codes follow the canonical <svc>.<code> format (see /common/error-tags.html).

Conformance and CI gates (required)

Contract artifacts must pass build-time checks:

• Every OpenAPI operation includes x-route-class, x-qps-target, x-concurrency-target, and x-latency-p95-ms (plus x-latency-p99-ms where required).
• Every idempotent write route declares key scope, retention window, and replay behavior.
• Event schemas are additive-only within a version; breaking changes require schema version bumps and deprecation windows.
• Request-context validation rejects header/body mismatches (orgcode, logical_guid, channel_code, cccode, context_source, roles) where enforced.
• Error envelopes conform to the common error schema (stable error_code, retryable, http_status).

Policy snapshot checklist

• Use canonical *_policy_version keys consistently (pricing, promotion, discount, stacking, tax, approval, returns, tender, fraud, loyalty, stored value, earning, transfer, count, adjustment, PO, matching, tolerance, receiving, QC, RTV, credit, shipping, export, backorder, special order).
• Policy objects use policy_version in their own schema; references to those policies use canonical *_policy_version keys.
• Include stacking_policy_version when discount stacking can affect outcomes.
• Procurement events include receiving/QC/tolerance policy versions when applicable.
• Sales refunds use returns_policy_version (not a separate refund policy key).
• Loyalty and stored value events include their respective policy versions.

Data flow readiness checklist

• System-of-record boundaries are explicit (which service owns which truth).
• Channel-owned inputs (carts, worksheets) are referenced, not duplicated, and do not become system of record.
• Cross-service references are defined and versioned (price snapshot, publish revision, stock card source refs).
• Temporal truth is preserved for price, cost, and inventory (as-of snapshots on transactions).
• Event emission covers state changes, approvals, reversals, and exceptions with traceable source refs.
• Fast-path vs analytics-path expectations are documented (operational queries vs rollups).

Approved artifact scope by module

ICS (Inventory Control)

• Core schemas: stock_position, location, stock_card_event, reservation, allocation, commitment, transfer_request, transfer_shipment, count_adjustment.
• Event families: stock_adjusted, stock_moved, reservation_created/released/expired, allocation_created/released/expired, transfer_requested/shipped/received, count_completed.

SCM (Sales Cycle Management)

• Core schemas: order, order_line, fulfillment_plan, shipment, return_rma, tender_record, discount_application.
• Event families: order_created/placed, allocation_committed, shipment_created/delivered, return_requested/received, refund_issued.

PCM (Procurement Cycle Management)

• Core schemas: purchase_order, po_line, receipt, invoice, match_result, rtv, vendor_credit.
• Event families: po_created/approved/issued, receipt_recorded, invoice_matched, rtv_created/received, credit_applied.

PPM (Pricing and Promotions)

• Core schemas: price_policy, price_entry, promotion_rule, coupon, discount_tier, price_snapshot.
• Event families: price_rule_created/activated/ended, promotion_applied, price_snapshot_created.

CRM/Loyalty

• Core schemas: customer, consent, loyalty_account, points_ledger, gift_card, store_credit.
• Event families: customer_created/merged, consent_updated, points_earned/redeemed/expired, stored_value_issued/redeemed.

Influencer/Affiliate

• Core schemas: influencer_profile, attribution_rule, earnings_ledger, payout_statement.
• Event families: attribution_recorded, earnings_accrued/held/payable/paid, clawback_applied.

Accounting/ERP Readiness

• Core schemas: financial_event, export_batch, settlement_reference.
• Event families: financial_event_created, export_batch_ready/sent.