@izumisy-tailor/omakase-modules 0.2.0 → 0.4.0

package/docs/examples/data-models/core/order-module.md

@@ -1,132 +0,0 @@
-# Order Module Core Contract
-
-## Goal
-Maintain the order module as a clean, channel-neutral core that accepts standardised intents, persists canonical orders, and exposes status history for downstream consumers without leaking external system concerns.
-
-## Module Boundary
-- Own canonical order identifiers, customer references, and pricing snapshots required by internal workflows.
-- Publish contracts that upstream systems write to (`order.orderIntent`) and downstream systems read (`order.order`, `orderStatusHistory`).
-- Avoid dependencies on channel integrations, inventory logic, billing specifics, or storefront payload schemas.
-- Surface read models through TailorDB views or projections instead of embedding module-specific fields in `order.order`.
-
-## Published Contracts
-
-All tables implicitly include an auto-generated `id` primary key; only domain-specific columns are listed below.
-
-### `order.orderIntent`
-| Field | Description |
-| --- | --- |
-| `orderIntentId` | Stable identifier generated by the caller; dedupe key combined with `sourceSystem`.
-| `sourceSystem` | Logical system identifier (e.g., `channel.shopify`, `crm.salesforce`).
-| `externalOrderId` | Optional reference for tracing back to the originating system.
-| `customerRef` | Customer identity reference understood by commerce core/CRM.
-| `lineItems` | Array of SKU identifiers, quantities, and pricing snapshots already mapped to internal product IDs.
-| `totals` | Order-level monetary snapshot (currency, subtotal, tax, shipping, discounts).
-| `submittedAt` | Timestamp from the originating system; used for sequencing when backfilling.
-| `payloadHash` | Optional trace hash to support replay verification.
-
-**Responsibilities**
-- Callers (channel integration, CRM, manual tools) must write intents via the published contract and handle idempotency using `orderIntentId` + `sourceSystem`.
-- Intents remain mutable only until acknowledged by the order module; mutations must create new intents.
-
-### `order.order`
-| Field | Description |
-| --- | --- |
-| `customerRef` | Carried over from the intent; never rewritten by downstream modules.
-| `lineItems` | Snapshot derived from the accepted intent; includes SKU, quantity, unit price, totals.
-| `currency` | ISO currency code resolved via commerce core metadata.
-| `createdAt` / `updatedAt` | Managed by the order module; reflect canonical lifecycle timestamps.
-| `intentRef` | Foreign key back to `order.orderIntent` for traceability.
-**Responsibilities**
-- Remains immutable for line items and monetary values once created; adjustments require follow-up intents or dedicated adjustment commands.
-- Exposes only generic fields; module-specific state must live in projections or status history.
-
-### `orderStatusHistory`
-| Field | Description |
-| --- | --- |
-| `orderId` | Order identifier referencing `order.order`.
-| `module` | Namespace-qualified module writing the status (e.g., `channel`, `inventory`, `billing`).
-| `statusCode` | Module-defined status code (e.g., `channel:captured`, `procurement:po_confirmed`).
-| `category` | Optional grouping such as `fulfillment`, `payment`, `support`.
-| `severity` | Optional flag (`info`, `warning`, `blocking`) signalling operational impact.
-| `payload` | JSON payload for contextual metadata (tracking number, reason codes, ETA).
-| `recordedAt` | Timestamp supplied by the writer; used for chronological rendering.
-| `writtenBy` | Executor/actor responsible for the entry.
-| `closedAt` | Optional timestamp when the status is superseded/resolved.
-
-**Responsibilities**
-- Writers append-only; updates occur by inserting new entries instead of mutating existing ones.
-- Downstream projections (latest status, blocking status, timeline views) are derived from this table.
-- Status vocabularies are documented per module to avoid collisions; the order module provides write APIs but does not interpret module-specific semantics.
-
-## Status Model Principles
-- Clean core: `order.order` keeps only canonical attributes; module-specific lifecycle stays in history/projections.
-- History over flags: statuses are append-only rows, not columns on `order.order`.
-- Module ownership: each module writes its own statuses; order core supplies infrastructure only.
-- Read-only projections: UIs read history + module projections; modules never mutate others' tables.
-- Optional composition: modules can be added/removed without schema migrations to `order.order`.
-
-### Order Status Vocabulary
-
-| Label | Writer | Trigger timing | Notes |
-| --- | --- | --- | --- |
-| `order:submitted` | Order module | Immediately after an `orderIntent` is accepted and converted into `order.order`. | Establishes the baseline timeline entry for all downstream consumers. |
-| `order:manually_adjusted` | Order module / Operator | Whenever an operator edits the order after creation (e.g., address correction, line adjustment). | Signals other modules to reconcile manual updates or rerun validation. |
-| `order:cancelled` | Order module / Operator | When the order is cancelled or voided. | Downstream modules should unwind reservations, authorizations, and tasks. |
-
-Modules must introduce additional statuses using their own namespace prefix (e.g., `inventory:*`, `billing:*`). Shared dashboards consume this vocabulary to build customer-facing timelines.
-
-## Projections & Queries
-- Latest status per module: windowed view picking the newest entry per `(orderId, module)`.
-- Blocking status detection: filter where `severity = 'blocking'` and `closedAt IS NULL` to pause fulfilment/billing.
-- Timelines: list all history entries ordered by `recordedAt` for customer communications.
-- Aggregations: dashboards (e.g., counts of `procurement:delayed`) without touching `order.order` schema.
-
-## Integration Patterns
-- Inventory/Procurement: executors write `procurement:po_*`, `inventory:reservation_*`; projections decide release timing.
-- Billing/Payments: append `billing:invoice_posted`, `billing:payment_failed`; UIs read history for payment lifecycle.
-- Multi-entity: log `entity:*` milestones (policy snapshots, settlements) without adding entity fields to orders.
-- CRM/Customer success: `crm:*` entries (case opened, loyalty awarded) live in history, not in `order.order`.
-- Manual operations: operators insert `manual:*` notes for auditability.
-
-## Design Guidelines
-1. Naming discipline: use `module:status` to avoid collisions and simplify filtering.
-2. Idempotent writes: guard against duplicates (check last status per module where needed).
-3. Retention: define history retention/partitioning; plan for high-volume modules.
-4. Access control: modules insert/update only their own statuses; apply RBAC for manual tools.
-5. Testing: integration tests should assert history entries for key flows and respect blocking statuses.
-6. Documentation: each module documents its vocabulary and payload expectations.
-
-## Migration Strategy
-1. Create `orderStatusHistory` and backfill from legacy order columns if present.
-2. Update executors/modules to append history instead of mutating `order.order` columns.
-3. Deprecate legacy status columns once consumers pivot to history-driven projections.
-4. Provide transitional views so downstream systems can adopt the model gradually.
-
-## Ingestion Pattern
-1. External systems transform their payloads into the `order.orderIntent` schema.
-2. The order module validates intents (schema, dedupe, referenced entities), persists them, and emits a CDC event.
-3. `orderIntentIngestor` consumes the CDC stream, creates the canonical `order.order`, and records the originating mapping.
-4. Success results in a `channel:captured` (or equivalent) entry appended to `orderStatusHistory`.
-5. Failure scenarios raise rejection events so the caller can diagnose issues without introducing direct dependencies on order internals.
-
-## Downstream Consumption
-- Inventory, procurement, billing, and CRM modules listen to `order.order` CDC events to start their workflows.
-- Status dashboards query projections derived from `orderStatusHistory` to display customer timelines and operational alerts.
-- Channel-specific projections (e.g., `channel.statusProjection`) remain within the owning module and reference `orderId` and `orderStatusHistory` data as needed.
-
-## Dependency Guidelines
-- Order depends only on shared infrastructure modules (e.g., commerce core for product metadata).
-- Upstream modules must depend on the order contract to write intents; downstream modules may depend on the order module for CDC schemas and read models.
-- Bidirectional dependencies are avoided by using shared tables (`order.orderIntent`, `orderStatusHistory`) as integration boundaries.
-
-## Versioning & Change Management
-- Introduce new fields in `order.orderIntent` as optional with defaults; communicate schema revisions through versioned documentation.
-- Provide a deprecation window before enforcing mandatory fields so channel connectors can adopt changes.
-- For breaking changes, publish a new contract version (e.g., `order.orderIntent.v2`) and run both in parallel until migration completes.
-
-## Operational Considerations
-- Implement replay tooling to rebuild orders from intents for audit scenarios.
-- Monitor dedupe metrics to detect misconfigured source systems.
-- Enforce payload size limits and validation rules to prevent unbounded data ingestion.
-- Retain intents for the retention period required by compliance/audit and purge only after downstream reconciliation.

package/docs/examples/data-models/scenarios/inventory-reservation-scenario.md

@@ -1,73 +0,0 @@
-# Inventory Reservation Scenario
-
-## Overview
-This document captures a flow where the order module remains independent while an optional inventory module automates stock reservations. Back-office teams can maintain inventory manually (for example via spreadsheets or direct TailorDB edits), and when the inventory module is enabled it reacts to order events, applies reservation logic, and publishes stock projections without imposing reverse dependencies on the order module. The order contract referenced here is defined in [Order Module Core Contract](../order-module-core-contract.md).
-
-## Module Dependencies
-
-| Module (package path) | Declared dependencies | Purpose |
-| --- | --- | --- |
-| Commerce core (`packages/commerce-core-module`) | — | Owns product and customer master data; exposes immutable definitions consumed by downstream modules. |
-| Order (`packages/order-module`) | — | Publishes the `order.orderIntent` contract, stores canonical orders, and exposes status history for downstream projections. |
-| Inventory (`packages/inventory-module`) | Order, Commerce core | Listens to order events to automate reservations and uses commerce metadata to resolve SKU attributes. |
-
-## TailorDB Tables and Views
-- Uses core tables `inventory.reservation` and `inventory.stockLedger` as defined in `core/inventory-module.md`; not redefined here.
-- `inventory.remainingStock`: Derived view exposing per-SKU on-hand quantities for read-only consumers (scenario-local read model).
-
-## Order Status
-
-Baseline `order:*` statuses are defined in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). This scenario appends the following inventory-originated statuses into `orderStatusHistory` so order consumers can see reservation outcomes without querying inventory tables directly:
-
-| Label | Writer | Trigger timing | Notes |
-| --- | --- | --- | --- |
-| `inventory:reservation_created` | Inventory module | When `inventoryReservationIntake` begins reserving stock for an order. | Optional; useful for long-running reservation processes. |
-| `inventory:reservation_confirmed` | Inventory module | After stock is successfully reserved. | Indicates inventory has secured the requested quantities. |
-| `inventory:reservation_backordered` | Inventory module | When inventory cannot fully reserve quantities. | Marks the order as waiting on replenishment. |
-| `inventory:reservation_cancelled` | Inventory module | When a reservation is released due to order change or cancellation. | Ensures support teams understand why stock was freed. |
-
-## Inventory Status (scenario-specific)
-
-This scenario does not introduce additional inventory status codes beyond the core vocabulary. It emits the core `inventory:reservation_*` statuses above; other core statuses (for example `inventory:stock_adjusted`, `inventory:fulfillment_task_created`) remain available but are not invoked in this flow.
-
-## Executor Triggers
-
-| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
-| --- | --- | --- | --- | --- |
-| `order.order` (order) | Order (owner), operators | Record creation or update (CDC) | `inventoryReservationIntake` (inventory) | Decide whether to create/update `inventory.reservation` entries based on order status; can be disabled for manual-only workflows. |
-| `inventory.reservation` (inventory) | Inventory (owner), operators | Record creation or update (CDC) | `inventoryReservationProjector` (inventory) | Maintain `inventory.remainingStock` snapshots and ensure reservations propagate to the ledger when required. |
-| `inventory.stockLedger` (inventory) | Inventory (owner), operators | Record creation (CDC) | `inventoryStockMetricsUpdater` (inventory) | Update analytical projections and audit views after any stock movement (manual or automated). |
-
-## Flow
-1. An operator or integration submits `order.orderIntent`; the order module validates and ingests it into `order.order`, emitting a CDC event. Manual edits can still be applied directly to `order.order` when policy permits.
-2. If the inventory module is enabled, `inventoryReservationIntake` reacts to the order CDC event and records reservation rows in `inventory.reservation` (and, when relevant, appends movements to `inventory.stockLedger`). If automation is disabled, operators can insert reservations or ledger entries manually without involving the executor.
-3. Inventory appends reservation outcomes (`inventory:reservation_confirmed`, `inventory:reservation_backordered`) to `orderStatusHistory` so order consumers can see automation progress without depending directly on inventory tables.
-4. CDC events on `inventory.reservation` and `inventory.stockLedger` trigger inventory-side projectors that refresh `inventory.remainingStock` and other read models.
-5. Order-facing UIs or reports can query `inventory.remainingStock` for availability and combine it with `orderStatusHistory` to display reservation timelines, while the order module itself remains oblivious to how the data originated.
-6. Commerce core continues to publish product metadata; inventory consumes this data but does not introduce reverse dependencies on order.
-
-```mermaid
-sequenceDiagram
-    actor Operator
-    participant Order
-    participant Inventory
-    participant Commerce
-
-    Operator->>Order: submit orderIntent (manual or automated)
-    Order->>Order: orderIntentIngestor creates order.order
-    Order-->>Inventory: order.order CDC event (optional automation)
-    Inventory->>Inventory: inventoryReservationIntake evaluates reservation logic
-    Inventory->>Inventory: write inventory.reservation / inventory.stockLedger
-    Inventory->>Order: append inventory:* status history entries
-    Inventory-->>Inventory: reservation/ledger CDC refreshes remainingStock
-    Operator->>Inventory: manual adjustments as needed
-    Inventory-->>Order: remainingStock exposed via read-only view
-    Inventory-->>Commerce: read product metadata
-```
-
-## Design Considerations
-- Keep order independent so manual-only workflows remain viable even without the inventory module; follow the contract in `../order-module-core-contract.md` when extending ingestion.
-- Inventory automation should be idempotent and tolerant of manual edits, reconciling rather than overwriting operator input in reservation and ledger tables.
-- Append reservation outcomes to `orderStatusHistory` with a documented status vocabulary (`inventory:reservation_*`) so order consumers do not query inventory tables directly.
-- Downstream consumers read `inventory.remainingStock` (or similar projections) without mutating inventory-owned tables.
-- Commerce core continues to act as the canonical source for SKU definitions; inventory depends on it, not the other way around.

package/docs/examples/data-models/scenarios/multi-storefront-order-scenario.md

@@ -1,99 +0,0 @@
-# Multi-Storefront Order Scenario
-
-## Overview
-This scenario covers an organisation selling through multiple storefronts (e.g., Shopify, Amazon) while sharing a single stock pool. The order module stays channel-agnostic: dedicated channel integration modules capture storefront events, translate them into core orders, and coordinate inventory reservations. Channel-specific fulfilment states and acknowledgements live outside the order schema in status history and channel projections. The shared contract for the clean order core is documented in [Order Module Core Contract](../order-module-core-contract.md).
-
-## Module Dependencies
-
-| Module (package path) | Declared dependencies | Purpose |
-| --- | --- | --- |
-| Channel integration (`packages/channel-integration-module`) | Commerce core, Order | Pulls orders from external storefronts, maps product identifiers, and writes standardised order intents through the order module contract. |
-| Order (`packages/order-module`) | — | Publishes the `orderIntent` contract, stores canonical orders, and exposes status history for downstream modules. |
-| Inventory (`packages/inventory-module`) | Order, Commerce core | Manages shared stock, reservations, and warehouse operations. |
-| Commerce core (`packages/commerce-core-module`) | — | Owns product catalogue, channel SKU mappings, and pricing metadata. |
-| Channel sync (`packages/channel-sync-module`) | Inventory, Channel integration | Publishes stock levels and fulfilment confirmations back to the storefronts. |
-
-## TailorDB Tables and Views
-### Channel integration module
-- `channel.orderCapture`: Raw storefront payloads kept for traceability, enrichment, and replay (shop identifier, channel order id, customer info, line allocations).
-- `channel.orderMapping`: Links channel order ids to the generated `orderId` after the intent is processed; also records the originating `orderIntentId` for audits.
-- `channel.statusProjection`: Channel-facing projection of statuses (acknowledged, packed, shipped) derived from history entries.
-
-### Inventory module
-- Uses core inventory tables (`inventory.reservation`, `inventory.stock`, `inventory.fulfillmentTask`, `inventory.statusHistory`, etc.) as defined in `../core/inventory-module.md`; not redefined here.
-
-### Channel sync module
-- `channel.stockFeed`: Snapshot of stock availability per storefront (SKU, channel SKU, available quantity, last synced at).
-- `channel.fulfilmentFeed`: Outbound acknowledgements (tracking numbers, shipped quantity) queued for storefront APIs.
-
-## Order Status
-
-Baseline `order:*` statuses appear in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). Multi-storefront flows add the following channel and inventory signals:
-
-| Label | Writer | Trigger timing | Notes |
-| --- | --- | --- | --- |
-| `channel:captured` | Order module (on behalf of channel) | Immediately after `orderIntentIngestor` creates the core order and records the channel mapping. | Confirms that the storefront intent has been accepted into the core system. |
-| `inventory:reservation_confirmed` | Inventory module | When stock is successfully reserved. | Signals to channels that fulfilment can proceed. |
-| `inventory:reservation_backordered` | Inventory module | When stock is insufficient and a backorder is created. | Allows channel integration to notify storefronts about delays. |
-| `inventory:shipped` | Inventory module / Warehouse | After fulfilment tasks complete and goods leave the warehouse. | Provides shipment milestone prior to storefront acknowledgement. |
-| `channel:reservation_confirmed` | Channel integration | When `channelReservationProjector` reflects inventory confirmation back to the storefront. | Keeps channel dashboards consistent with internal state. |
-| `channel:acknowledged` | Channel integration | Once the storefront API confirms receipt of fulfilment or stock updates. | Closes the loop and highlights any outstanding acknowledgements. |
-
-## Executor Triggers
-
-| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
-| --- | --- | --- | --- | --- |
-| `order.orderIntent` (order) | Channel integration (via contract) | Record creation (CDC) | `orderIntentIngestor` (order) | Validate intent, ensure idempotency, create `order.order`, append `channel:captured` entry to `orderStatusHistory`, and register mapping in `channel.orderMapping`. |
-| `order.order` (order) | Order (owner) | Record creation (CDC) | `inventoryReservationIntake` (inventory) | Reserve shared stock for the order; write `inventory:reservation_*` statuses. |
-| `inventory.reservation` (inventory) | Inventory (owner) | Record creation or update (CDC) | `channelReservationProjector` (channel integration) | Evaluate reservation results; update `channel.statusProjection` and append statuses (`channel:reservation_confirmed`, etc.). |
-| `inventory.fulfilmentTask` (inventory) | Inventory (owner), warehouse systems | Record update (CDC) | `channelFulfilmentNotifier` (channel sync) | When tasks complete, enqueue shipping confirmations in `channel.fulfilmentFeed` and append `inventory:shipped` history entries. |
-| `channel.fulfilmentFeed` (channel sync) | Channel sync (owner) | Record update (CDC) | `channelAckTracker` (channel integration) | Confirm storefront receipt of fulfilment data; append `channel:acknowledged` history entry when storefront confirms. |
-| `inventory.stock` (inventory) | Inventory (owner) | Record update (CDC) | `channelStockPublisher` (channel sync) | Refresh `channel.stockFeed` to push near real-time stock availability to storefronts. |
-
-## Flow
-1. Shopify and Amazon orders are ingested by the channel integration module, stored in `channel.orderCapture` for traceability, deduped, and transformed into `order.orderIntent` records through the order contract.
-2. `orderIntentIngestor` validates each intent, creates the core `order.order`, writes the channel mapping, and inserts a `channel:captured` row in `orderStatusHistory`.
-3. The order creation triggers `inventoryReservationIntake`, which reserves stock. Depending on availability, it inserts statuses such as `inventory:reservation_confirmed` or `inventory:reservation_backordered`.
-4. Reservation outcomes trigger `channelReservationProjector`, which updates `channel.statusProjection` for each storefront and writes additional history entries so UIs can display per-channel progress.
-5. Warehouse operations progress via `inventory.fulfilmentTask`. When tasks complete, `channelFulfilmentNotifier` produces `channel.fulfilmentFeed` rows and appends `inventory:shipped` history entries.
-6. `channelStockPublisher` listens to `inventory.stock` updates and refreshes `channel.stockFeed`, ensuring storefronts receive the latest availability for overselling prevention.
-7. Storefronts acknowledge shipments and stock updates via APIs. `channelAckTracker` marks `channel.fulfilmentFeed` entries as confirmed and writes `channel:acknowledged` status history rows. Pending acknowledgements remain visible for support teams.
-8. Customer-facing applications query `orderStatusHistory` (or derived views) to render timelines, while channel dashboards rely on `channel.statusProjection` for storefront-specific messaging.
-
-```mermaid
-sequenceDiagram
-    actor Shopify
-    actor Amazon
-    participant Channel as ChannelIntegration
-    participant Order
-    participant Inventory
-    participant Sync as ChannelSync
-    actor Warehouse
-
-    Shopify->>Channel: push order payload
-    Amazon->>Channel: push order payload
-    Channel->>Channel: store channel.orderCapture & dedupe
-    Channel->>Order: write order.orderIntent via contract
-    Order->>Order: orderIntentIngestor creates order + status history
-    Order-->>Inventory: order.order CDC event
-    Inventory->>Inventory: inventoryReservationIntake reserves stock
-    Inventory-->>Channel: reservation CDC updates status projection
-    Inventory->>Warehouse: emit fulfilmentTask
-    Warehouse-->>Inventory: complete fulfilmentTask
-    Inventory->>Sync: channelFulfilmentNotifier enqueues fulfilmentFeed
-    Sync->>Shopify: send shipment & stock update
-    Sync->>Amazon: send shipment & stock update
-    Shopify-->>Channel: ack shipment
-    Amazon-->>Channel: ack shipment
-    Channel->>Order: channelAckTracker appends status history
-```
-
-## Design Considerations
-- Keep the order module channel-neutral; storefront-specific payloads stay in channel integration tables, while `order.orderIntent` only contains the normalised fields required by the core order schema.
-- Maintain idempotent ingestion: dedupe channel payloads (channel order id + storefront id) before writing to `order.orderIntent` so order ingestion remains idempotent.
-- Version the `orderIntent` contract and publish compatibility guidelines so new fields roll out without breaking existing channel connectors.
-- Use `orderStatusHistory` to represent storefront and inventory milestones; avoid proliferating channel fields on the order record.
-- Provide per-channel projections (`channel.statusProjection`) to avoid overloading shared history queries when storefront portals need dedicated filters.
-- Stock publishing should throttle or batch updates per storefront to honour API limits while still preventing overselling.
-- Errors in storefront communication should create `severity = 'blocking'` history entries so billing/fulfilment can pause until acknowledgements arrive.
-- Document the vocabulary of channel statuses (e.g., `channel:captured`, `channel:acknowledged`) so downstream consumers interpret them consistently.

package/docs/examples/data-models/scenarios/order-payment-status-scenario.md

@@ -1,92 +0,0 @@
-# Order Payment Status Scenario
-
-## Overview
-This document captures a reference flow where the order module owns the canonical order status while collaborating with optional billing, authorization, and cash receipt modules. The order module remains usable as a standalone component—for example, back-office staff can record invoice or payment outcomes manually—while downstream modules add automation by reacting to order events and pushing their results back through status history entries. The shared contract that keeps order independent is defined in [Order Module Core Contract](../order-module-core-contract.md).
-
-## Module Dependencies
-
-| Module (package path) | Declared dependencies | Purpose |
-| --- | --- | --- |
-| Order (`packages/order-module`) | — | Publishes the `order.orderIntent` contract, stores canonical orders, and exposes status history consumed by downstream financial modules. |
-| Payment authorization (`packages/payment-authorization-module`) | Order | Manages authorization holds/captures against external PSPs and appends payment statuses to `orderStatusHistory`. |
-| Billing (`packages/billing-module`) | Order, Payment authorization | Generates invoices (manually or automatically), links them to authorizations, and writes billing milestones into `orderStatusHistory`. |
-| Cash receipt (`packages/cash-receipt-module`) | Order, Billing | Records cash inflows, allocates them to invoices, and publishes settlement statuses into `orderStatusHistory`. |
-
-## TailorDB Tables and Views
-### Payment authorization module
-- `authorization.request`: Outbound authorization attempts for a given order.
-- `authorization.result`: Holds/voids/captures returned from the PSP.
-- Appends `payment:*` entries (e.g., `payment:authorized`, `payment:capture_failed`) to `orderStatusHistory` via the order dependency.
-
-### Billing module
-- `billing.invoice`: Invoices generated for orders.
-- `billing.invoiceStatus`: Derived view summarizing invoice state (issued, posted, settled).
-- Appends `billing:*` milestones (e.g., `billing:invoice_issued`, `billing:settled`) to `orderStatusHistory` and maintains projections for finance dashboards.
-
-### Cash receipt module
-- `cash.receipt`: Records individual cash inflows.
-- `cash.receiptAllocation`: Maps receipts to invoices.
-- Appends `cash:*` history entries (`cash:payment_applied`, `cash:refund_requested`) to provide audit traces within `orderStatusHistory`.
-
-## Order Status
-
-Baseline `order:*` statuses are documented in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). Financial automation contributes the following additional entries:
-
-| Label | Writer | Trigger timing | Notes |
-| --- | --- | --- | --- |
-| `payment:authorization_pending` | Payment authorization | Immediately after `paymentAuthorizationIntake` enqueues an authorization attempt. | Communicates that an authorization request is in flight. |
-| `payment:authorized` | Payment authorization | When the PSP returns a successful authorization or capture. | Used to gate invoice issuance or fulfilment release. |
-| `payment:capture_failed` | Payment authorization | Upon PSP decline or technical failure. | Prompts support teams to investigate or retry. |
-| `billing:invoice_requested` | Billing | When `billingOrderIntake` decides to create an invoice. | Marks the start of the billing workflow even before the invoice record exists. |
-| `billing:invoice_issued` | Billing | After an invoice is generated. | Downstream consumers can inform customers or trigger collections. |
-| `billing:settled` | Billing | Once the invoice is fully settled in billing systems. | Often paired with cash entries for complete reconciliation. |
-| `cash:payment_applied` | Cash receipt | When cash is allocated to the invoice covering the order. | Confirms funds have been received and matched. |
-| `cash:refund_requested` | Cash receipt | If a refund or reversal is initiated. | Allows order timelines to reflect outstanding customer adjustments. |
-
-## Executor Triggers
-
-| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
-| --- | --- | --- | --- | --- |
-| `order.order` (order) | Order (owner), back-office operators | Record creation or update (CDC) | `billingOrderIntake` (billing) | React to new or updated orders, create invoices when automation is enabled, and append `billing:invoice_requested` statuses. |
-| `order.order` (order) | Order (owner), back-office operators | Record creation or update (CDC) | `paymentAuthorizationIntake` (payment authorization) | Initiate or refresh authorization attempts based on order state or manual triggers; append `payment:authorization_pending` status. |
-| `authorization.result` (payment authorization) | Payment authorization (owner) | Record creation or update (CDC) | `authorizationStatusWriter` (payment authorization) | Append authorization outcomes to `orderStatusHistory` (`payment:authorized`, `payment:capture_failed`) and refresh module projections. |
-| `billing.invoice` (billing) | Billing (owner), operators | Record creation or update (CDC) | `billingStatusWriter` (billing) | Append invoice lifecycle entries (`billing:invoice_issued`, `billing:invoice_posted`) to `orderStatusHistory`. |
-| `billing.invoiceStatus` (billing) | Billing (derived) | View refresh | `billingSettlementWriter` (billing) | Append settlement milestones (`billing:settled`) and update finance dashboards. |
-| `cash.receiptAllocation` (cash receipt) | Cash receipt (owner) | Record creation or update (CDC) | `cashReceiptOrderWriter` (cash receipt) | Append `cash:payment_applied` entries and emit reconciliation tasks when allocations differ from expectations. |
-
-## Flow
-1. A new order intent is submitted (automated integration or operator input). The order module validates it, persists `order.order`, and emits a CDC event.
-2. The billing and payment authorization modules listen to that CDC stream. If enabled, their executors (`billingOrderIntake`, `paymentAuthorizationIntake`) create invoices or authorization requests and append pending statuses (`billing:invoice_requested`, `payment:authorization_pending`). Otherwise they ignore the event, allowing manual workflows.
-3. Authorization results are written to `authorization.result`. The `authorizationStatusWriter` executor appends outcomes such as `payment:authorized` or `payment:capture_failed` to `orderStatusHistory`, enabling order consumers to track financial progress without exposing PSP details.
-4. Billing lifecycle changes (automation or manual invoice entry) update `billing.invoice` / `billing.invoiceStatus`. Billing executors append milestones (`billing:invoice_issued`, `billing:settled`) to `orderStatusHistory` and refresh their projections.
-5. Cash receipts allocate payments to invoices via `cash.receiptAllocation`. The cash receipt executor appends settlement statuses (`cash:payment_applied`) so customer service teams can view payment confirmations from the order timeline.
-6. Operators can always append manual entries to `orderStatusHistory` (e.g., `manual:write_off`) to reflect adjustments; downstream modules treat those entries as authoritative signals and reconcile their own records accordingly.
-
-```mermaid
-sequenceDiagram
-	actor Operator
-	participant Order
-	participant Billing
-	participant Auth as PaymentAuth
-	participant Cash
-
-	Operator->>Order: submit orderIntent (manual or automated)
-	Order->>Order: orderIntentIngestor creates order.order
-	Order-->>Billing: order.order CDC event
-	Billing->>Billing: billingOrderIntake decides on automation
-	Billing->>Order: append billing:* status history entries
-	Order-->>Auth: order.order CDC event
-	Auth->>Auth: paymentAuthorizationIntake initiates auth request
-	Auth->>Order: append payment:* status history entries
-	Billing->>Billing: invoice lifecycle progresses
-	Billing->>Order: append billing:settled when complete
-	Cash-->>Billing: cash.receiptAllocation links receipt to invoice
-	Cash->>Order: append cash:payment_applied status
-```
-
-## Design Considerations
-- Keep configuration dependencies directional: downstream financial modules depend on order, not the other way around, following the guidance in `../order-module-core-contract.md`.
-- Downstream modules append to `orderStatusHistory` using namespace-qualified status codes instead of mutating `order.order` fields, preserving the clean core.
-- CDC-driven automation should be idempotent and tolerant of manual changes, reconciling rather than overwriting operator inputs.
-- Maintain documented vocabularies for `payment:*`, `billing:*`, and `cash:*` statuses so shared dashboards interpret them consistently.
-- Leverage projections (e.g., `order.financialStatusProjection`) for read-heavy contexts while keeping `orderStatusHistory` as the authoritative audit trail.

package/docs/examples/data-models/scenarios/procurement-order-scenario.md

@@ -1,95 +0,0 @@
-# Procurement Order Scenario
-
-## Overview
-This document illustrates how an order module cooperates with a procurement module when customer demand is fulfilled through supplier purchase orders rather than internal stock. The order module remains a clean, customer-facing source of truth, while procurement owns supplier relationships, purchase orders, and inbound logistics. The goal is to let organizations operate mixed models (stocked items vs. drop-ship) without embedding procurement concerns into the core order schema. The shared order contract that keeps the core independent is described in [Order Module Core Contract](../order-module-core-contract.md).
-
-## Module Dependencies
-
-| Module (package path) | Declared dependencies | Purpose |
-| --- | --- | --- |
-| Order (`packages/order-module`) | — | Publishes the `order.orderIntent` contract, stores canonical orders, and exposes status history for downstream modules. |
-| Procurement (`packages/procurement-module`) | Order, Commerce core | Generates and tracks supplier purchase orders, manages inbound shipments, and appends procurement milestones to `orderStatusHistory`. |
-| Commerce core (`packages/commerce-core-module`) | — | Provides product master data, supplier catalogs, and lead-time metadata consumed by procurement. |
-| Inventory (`packages/inventory-module`) | Procurement, Commerce core | Optionally tracks goods received into stock or cross-docking locations. |
-| Billing (`packages/billing-module`) | Order | Handles customer invoicing; may wait for procurement confirmation before finalizing revenue. |
-
-## TailorDB Tables and Views
-### Procurement module
-- `procurement.purchaseOrder`: Supplier-facing purchase orders referencing `orderId` and line allocations.
-- `procurement.supplier`: Master data for suppliers, including lead times, payment terms, and partner IDs.
-- `procurement.inboundShipment`: Tracks ASN (advance shipping notice), shipment status, and expected arrival.
-- `procurement.exceptions`: Captures issues such as supplier delays, quantity shortages, or quality holds.
-- `procurement.orderStatus`: Projection of procurement milestones per order (PO issued, supplier confirmed, shipment dispatched, received).
-- Appends `procurement:*` entries to `orderStatusHistory` for shared visibility while keeping detailed supplier data inside procurement-owned tables.
-
-### Inventory module (optional)
-- Uses core inventory tables (`inventory.stock`, `inventory.stockLedger`, etc.) as defined in `../core/inventory-module.md` to reflect inbound receipts and stock updates; not redefined here.
-- `inventory.receipt`: Scenario-specific record for booking inbound shipments into stock or cross-dock locations.
-
-## Order Status
-
-Baseline `order:*` statuses are defined in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). Procurement adds the following milestones:
-
-| Label | Writer | Trigger timing | Notes |
-| --- | --- | --- | --- |
-| `procurement:po_issued` | Procurement module | Immediately after `procurementOrderIntake` creates a purchase order. | Indicates supplier engagement has started. |
-| `procurement:po_confirmed` | Procurement module | When the supplier confirms the purchase order. | Confirms expected ship dates and quantities. |
-| `procurement:asn_received` | Procurement module | Upon receiving an ASN or shipment notice. | Signals inbound logistics to prepare for receipt. |
-| `procurement:received` | Procurement module / Inventory module | When goods are fully received and reconciled. | Allows billing or fulfilment to proceed confidently. |
-| `procurement:short_shipment` | Procurement module | If received quantity is less than ordered. | Highlights the need for back-order or customer communication. |
-| `procurement:blocking_exception` | Procurement module | When an exception (delay, quality hold) blocks fulfilment. | Downstream modules should pause until resolved. |
-
-## Executor Triggers
-
-| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
-| --- | --- | --- | --- | --- |
-| `order.order` (order) | Order (owner), operators | Record creation or update (CDC) | `procurementOrderIntake` (procurement) | Decide whether a purchase order is needed based on product supply policies and current stock; create or update `procurement.purchaseOrder` rows. |
-| `procurement.purchaseOrder` (procurement) | Procurement (owner) | Record creation or update (CDC) | `procurementPOStatusProjector` (procurement) | Update supplier confirmations, expected ship dates, and project milestones into `procurement.orderStatus`. |
-| `procurement.inboundShipment` (procurement) | Procurement (owner), suppliers via EDI | Record creation or update (CDC) | `procurementInboundCoordinator` (inventory) | Trigger inbound logistics tasks, e.g., allocate receiving docks or generate `inventory.receipt` placeholders. |
-| `inventory.receipt` (inventory) | Inventory (owner) | Record creation (CDC) | `procurementReceiptReconciler` (procurement) | Match receipts to purchase orders, update quantities received, and close out procurement exceptions. |
-| `procurement.exceptions` (procurement) | Procurement (owner), operators | Record creation or update (CDC) | `procurementExceptionProjector` (procurement) | Reflect exception state in `procurement.orderStatus` and expose signals (e.g., blocks) for downstream modules. |
-
-## Flow
-1. An order intent is submitted. After validation, the order module persists `order.order` and emits a CDC event that triggers `procurementOrderIntake`.
-2. Procurement evaluates supply policies, available stock, and supplier contracts. If a supplier order is required, it creates `procurement.purchaseOrder` entries linking each order line to a supplier and expected ship date, and appends `procurement:po_issued` to `orderStatusHistory`.
-3. Suppliers confirm the purchase order through EDI/API or operator input. `procurement.purchaseOrder` updates drive `procurementPOStatusProjector`, which writes milestones (confirmed, delayed, partial) into `procurement.orderStatus` and appends corresponding entries (e.g., `procurement:po_confirmed`) to `orderStatusHistory`.
-4. When suppliers send advance shipping notices, `procurement.inboundShipment` records are created. `procurementInboundCoordinator` may allocate receiving resources or pre-create `inventory.receipt` placeholders while recording `procurement:asn_received` in the shared history.
-5. Upon physical receipt, the inventory module records `inventory.receipt`, triggering `procurementReceiptReconciler` to update received quantities, close or escalate procurement exceptions, and append `procurement:received` or `procurement:short_shipment` statuses for order-facing consumers.
-6. Any exceptions (short shipments, quality holds, supplier delays) are logged in `procurement.exceptions`. `procurementExceptionProjector` updates `procurement.orderStatus` and surfaces blocking flags via `orderStatusHistory` so downstream modules can pause fulfilment or billing.
-7. Once procurement confirms completion, order and billing experiences reference `procurement.orderStatus` alongside the shared history to release fulfilment and issue invoices when appropriate.
-
-```mermaid
-sequenceDiagram
-    actor Customer
-    participant Order
-    participant Procurement
-    actor Supplier
-    participant Inventory
-    participant Billing
-
-    Customer->>Order: submit orderIntent
-    Order->>Order: orderIntentIngestor creates order.order
-    Order-->>Procurement: order.order CDC event
-    Procurement->>Procurement: procurementOrderIntake creates purchaseOrder
-    Procurement->>Order: append procurement:po_issued status
-    Procurement->>Supplier: send purchase order
-    Supplier-->>Procurement: confirmation updates purchaseOrder
-    Procurement->>Order: append procurement:po_confirmed status
-    Supplier-->>Procurement: send inboundShipment/ASN
-    Procurement->>Order: append procurement:asn_received status
-    Procurement->>Inventory: procurementInboundCoordinator prepares receipt
-    Inventory->>Inventory: record inventory.receipt
-    Inventory-->>Order: append procurement:received / procurement:short_shipment statuses
-    Procurement->>Procurement: procurementExceptionProjector updates orderStatus view
-    Procurement-->>Order: expose orderStatus for fulfillment/billing decisions
-    Order-->>Billing: release for invoicing once procurement complete
-```
-
-## Design Considerations
-- Keep procurement logic modular so order can operate without it (e.g., stocked items). The intake executor should be configuration-driven (per SKU, channel, or merchant) and must adhere to `../order-module-core-contract.md`.
-- Purchase orders may aggregate multiple customer orders; ensure `procurement.purchaseOrder` links to both supplier PO numbers and individual order line allocations.
-- Exceptions should be first-class records with lifecycle management, enabling reporting and SLA tracking.
-- Append procurement milestones to `orderStatusHistory` with namespace-qualified codes (`procurement:*`) so order-facing teams share a single timeline.
-- Inventory integration is optional: drop-ship flows might bypass inventory entirely, while cross-docking requires temporary receipts.
-- Billing should respect procurement status, especially when revenue recognition depends on supplier confirmation or goods receipt.
-- Expose `procurement.orderStatus` as a read-only interface for order, billing, or customer-facing channels rather than duplicating timelines inside the order schema.