@izumisy-tailor/omakase-modules 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,59 @@
+# Omakase Modules
+
+A **configurable module system** for Tailor Platform. Define reusable modules with type-safe configurations and share them across applications.
+
+## Motivation
+
+When building applications on Tailor Platform, you often face these challenges:
+
+1. **Reusability**: You want to reuse common data models and business logic (e.g., e-commerce, inventory, orders) across multiple applications
+2. **Customizability**: While modules should be reusable, you need to customize them for application-specific requirements
+3. **Dependency Management**: Module dependencies should be explicitly defined and managed in a type-safe manner
+
+Omakase Modules is designed to solve these challenges by providing a flexible, type-safe module system.
+
+## Key Features
+
+- **Module Definition**: Define modules with `defineModule` and declare type-safe configuration schemas
+- **Module Configuration**: Configure modules at the application level, injecting custom attributes and prefixes
+- **Dependency Management**: Explicitly define inter-module dependencies with the `ModuleDependency` type
+- **Configuration Injection**: Inject configurations into TailorDB, Resolvers, and Executors using `withModuleConfiguration`
+
+## Installation
+
+```bash
+pnpm add @izumisy-tailor/omakase-modules
+```
+
+## Documentation
+
+- [Using Modules](./docs/tutorials/using-modules.md) - How to use pre-built modules in your application
+- [Creating Modules](./docs/tutorials/creating-modules.md) - How to create reusable modules
+
+## API Reference
+
+### `@izumisy-tailor/omakase-modules`
+
+- `loadModules(configurator)` - Load and configure modules in your application
+
+### `@izumisy-tailor/omakase-modules/builder`
+
+- `defineModule<Config, Tables>(options)` - Define a new module
+- `withModuleConfiguration(module, factory)` - Access module configuration in TailorDB, Resolvers, and Executors
+- `ModuleDependency<T>` - Type utility for declaring module dependencies
+
+### `@izumisy-tailor/omakase-modules/config/sdk`
+
+- `getModulesReference(loadedModules)` - Generate file path references for `tailor.config.ts`
+
+## Project Structure
+
+```
+examples/
+  commerce-core-module/     # E-commerce core module (Product, Customer, etc.)
+  order-module/             # Order management module
+  inventory-module/         # Inventory management module
+  basic-app/                # Application using the above modules
+packages/
+  core/                     # omakase-modules core package
+```

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

@@ -0,0 +1,230 @@
+# Inventory Core Contract
+
+## Goal
+Define the minimal shared layer of inventory management so industry-specific and automation modules can reuse a consistent contract. The aim is to standardise SKU- and location-level quantities, reservations, and fulfilment tasks, while coordinating downstream modules through status history.
+
+## Module Boundary
+- Persist core metadata for SKU, location, and inventory buckets (for example on-hand, reserved).
+- Publish "intent → confirmation" contracts for reservations, stock adjustments, and fulfilment tasks so callers write intents instead of mutating inventory directly.
+- Provide `inventory.statusHistory` (exposed as the `inventoryStatusHistory` view where needed) so business modules append their own statuses for auditing and visibility.
+- Delegate integrations with external systems (channel sync, procurement, warehouse automation, etc.) to extension modules; the core remains the source of truth for quantities and history.
+
+## Published Contracts
+
+All tables implicitly include an auto-generated `id` primary key; only domain-specific columns are listed below.
+
+### `inventory.stock`
+Represents the latest stock balance per location.
+
+| Field | Description |
+| --- | --- |
+| `skuId` | Identifier of the SKU. |
+| `locationId` | Identifier of the warehouse, store, or virtual location. |
+| `availableQuantity` | Sellable quantity after subtracting active reservations. |
+| `onHandQuantity` | Physical on-hand quantity. |
+| `reservedQuantity` | Quantity locked by reservations. |
+| `inboundQuantity` | Expected inbound quantity (optional). |
+| `outboundQuantity` | Planned outbound quantity (optional). |
+| `attributes` | JSON extension point for domain metadata (temperature band, storage condition, etc.). |
+| `updatedAt` | Timestamp of the latest update. |
+
+**Responsibilities**
+- Core maintains the balance calculation and consistency; external modules must request changes via intents.
+- Extension modules append industry-specific metadata (lot, serial, expiry, etc.) in `attributes`.
+
+### `inventory.reservationIntent`
+Intent table for requesting an inventory reservation.
+
+| Field | Description |
+| --- | --- |
+| `reservationIntentId` | Stable ID generated by the caller (per SKU or line item). |
+| `sourceSystem` | Origin of the request (for example `order`, `procurement`, `manual`). |
+| `orderId` / `sourceRef` | External reference identifier. |
+| `skuId` | SKU to reserve. |
+| `quantity` | Quantity requested for reservation. |
+| `locationPreference` | Preferred location when stock is distributed. |
+| `priority` | Reservation priority so urgent orders can be fulfilled first. |
+| `requestedAt` | Timestamp when the request was issued. |
+| `payload` | Arbitrary supplemental metadata. |
+
+**Responsibilities**
+- Callers insert intents to request reservation; enforce idempotency with `reservationIntentId` + `sourceSystem`.
+- Intent can be updated until confirmed; after confirmation, changes require a new intent.
+
+### `inventory.reservation`
+Confirmed record that stores the reservation outcome.
+
+| Field | Description |
+| --- | --- |
+| `reservationIntentId` | Reference back to the originating intent. |
+| `skuId` | SKU that was reserved. |
+| `locationId` | Location assigned to fulfil the reservation. |
+| `reservedQuantity` | Quantity secured; may differ from requested quantity if partially fulfilled. |
+| `status` | Core-defined status such as `confirmed`, `backordered`, `cancelled`. |
+| `expiresAt` | Reservation expiry timestamp (optional). |
+| `payload` | Supplemental metadata (batch number, operator notes, etc.). |
+| `createdAt` / `updatedAt` | Creation and update timestamps. |
+
+**Responsibilities**
+- Core finalises the intent, writes status updates to `inventory.statusHistory`, and emits CDC events.
+- Callers read the outcome and handle follow-up actions such as backorders when short allocations occur.
+
+### `inventory.adjustmentIntent`
+Intent that requests a stock increase or decrease, used for returns, cycle counts, manual corrections, etc.
+
+| Field | Description |
+| --- | --- |
+| `adjustmentIntentId` | Stable ID generated by the caller. |
+| `sourceSystem` | Origin of the adjustment request. |
+| `skuId` | SKU being adjusted. |
+| `locationId` | Location being adjusted. |
+| `quantityDelta` | Quantity delta (positive for increment, negative for decrement). |
+| `reasonCode` | Reason code (for example `cycle_count`, `return`, `damage`). |
+| `payload` | Additional metadata (document number, operator, etc.). |
+| `requestedAt` | Timestamp when the intent was created. |
+
+### `inventory.stockLedger`
+Authoritative event log for confirmed stock movements. Centralises adjustments, inbound receipts, outbound shipments, and any other inventory change.
+
+| Field | Description |
+| --- | --- |
+| `sourceType` | Origin of the event (for example `manual`, `procurement`, `fulfillment`). |
+| `sourceRef` | Reference `id` (reservation, purchase order, etc.). |
+| `skuId` | SKU affected. |
+| `locationId` | Location affected. |
+| `quantityDelta` | Quantity delta applied. |
+| `reasonCode` | Reason for the event (propagated from the intent or assigned by Core). |
+| `payload` | Optional extension metadata. |
+| `recordedAt` | Timestamp when the event was recorded. |
+
+`inventory.stockLedger` captures quantitative deltas only; downstream services should pair these entries with `inventory.statusHistory` to understand business context and progression.
+
+### `inventory.statusHistory`
+Timeline of status transitions emitted by Inventory Core and its extensions.
+
+| Field | Description |
+| --- | --- |
+| `entityType` | Scoped entity such as `reservation`, `fulfillmentTask`, `stock`. |
+| `entityId` | Auto-generated `id` of the entity whose status changed. |
+| `statusCode` | Vocabulary entry (see Inventory Status Vocabulary). |
+| `payload` | Optional metadata for UI or audit trails. |
+| `writtenBy` | Writer of the status (core executor, extension module, etc.). |
+| `writtenAt` | Timestamp when the status was appended. |
+
+While `inventory.stockLedger` answers "how much stock moved", `inventory.statusHistory` focuses on "what lifecycle state changed" so that UI, workflow, and auditing layers can present human-readable progress independent of quantitative adjustments.
+
+### `inventory.fulfillmentTask`
+Executable task for picking, packing, and shipping.
+
+| Field | Description |
+| --- | --- |
+| `sourceSystem` | System that generated the task (for example `order`, `channel`). |
+| `reservationId` | Linked reservation; use a join table when bundling multiple reservations. |
+| `skuId` / `quantity` | Item to pick and its quantity. |
+| `locationId` | Location from which the item should be picked. |
+| `status` | Lifecycle status such as `created`, `picking`, `packed`, `shipped`. |
+| `assignee` | Human or automated assignee. |
+| `payload` | Additional instructions (packing notes, carrier info, etc.). |
+| `updatedAt` | Timestamp of the latest update. |
+
+## Core Executors
+
+| Executor name | Trigger source | Key responsibilities | Current status |
+| --- | --- | --- | --- |
+| `inventory-bootstrap-product-variant` | `commerce-core.productVariant` created | Seed `inventory.stock` for the new SKU/variant with zeroed quantities and default thresholds. | Implemented (GraphQL mutation) |
+| `inventory-reserve-on-order-item-created` | `order.orderItem` created (CDC) | Listen to order-side CDC, enqueue reservation intent, and emit reservation confirmation/backorder statuses without the order module calling Inventory directly. | Stubbed in code; behaviour to be completed |
+
+> Fulfilment progression (picking → shipped) is typically handled by a warehouse extension executor such as `warehouse-fulfillment-task-progress`, which appends lifecycle statuses and ledger entries once physical operations occur.
+
+## Inventory Status Vocabulary
+
+Statuses below are persisted in `inventory.statusHistory` (or projected as `inventoryStatusHistory`) and streamed via CDC to downstream consumers.
+
+| Label | Writer | Trigger timing | Notes |
+| --- | --- | --- | --- |
+| `inventory:reservation_created` | Inventory core | Immediately after receiving a `reservationIntent`; signals reservation processing has started. |
+| `inventory:reservation_confirmed` | Inventory core | When stock is secured; use `payload` to surface short allocations. |
+| `inventory:reservation_backordered` | Inventory core | When the reservation is pending because available stock is insufficient. |
+| `inventory:reservation_cancelled` | Inventory core / caller | When the reservation is cancelled. |
+| `inventory:stock_adjusted` | Inventory core | When an `adjustmentIntent` is confirmed and the ledger records the delta. |
+| `inventory:fulfillment_task_created` | Inventory core | When a fulfilment task is generated. |
+| `inventory:picked` | Inventory core / warehouse module | When picking completes. |
+| `inventory:shipped` | Inventory core / warehouse module | When the shipment is handed off. |
+
+Industry modules follow the `inventory:*` namespace and may add codes such as `inventory:lotted_reserved` or `inventory:expiry_hold` for specialised flows.
+
+## Ingestion Pattern
+1. External modules (orders, procurement, manual operations, etc.) write intents to request inventory actions.
+2. Inventory Core executors validate the intents and apply them to the confirmation tables according to availability and business rules (priority, location selection).
+3. When confirmed, Core appends statuses to `inventory.statusHistory` and emits CDC events.
+4. Derived projections (for example latest stock summary, shortage report) refresh as needed.
+
+## Downstream Consumption
+- Order and channel integration modules read `inventory.reservation` and `inventory.statusHistory` to reflect reservation outcomes and shipping progress in their UIs.
+- Procurement confirms inbound receipts through `inventory.stockLedger` and reconciles stock increases.
+- Analytics and forecasting modules consume `inventory.stock` alongside `inventory.stockLedger` to evaluate inventory levels and turns.
+
+## CDC Flow Overview
+### Scenario: Order Line to Shipped
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Order as Order Module
+    participant OrderItem as order.orderItem
+    participant ReserveExecutor as inventory-reserve-on-order-item-created
+    participant ReservationIntent as inventory.reservationIntent
+    participant Reservation as inventory.reservation
+    participant FulfillmentExecutor as warehouse-fulfillment-task-progress
+    participant FulfillmentTask as inventory.fulfillmentTask
+    participant StatusHistory as inventory.statusHistory
+    participant StockLedger as inventory.stockLedger
+    participant Stock as inventory.stock
+
+    Order->>OrderItem: persist order line
+    OrderItem-->>ReserveExecutor: CDC new order item event
+    ReserveExecutor->>ReservationIntent: create reservation intent (sourceRef = orderItem.id)
+    ReservationIntent-->>ReserveExecutor: CDC new intent event
+    ReserveExecutor->>Reservation: persist reservation
+    ReserveExecutor->>StatusHistory: write reservation_confirmed
+    ReserveExecutor->>StockLedger: hold quantity delta
+    StockLedger-->>Stock: CDC projection updates available/on-hand
+
+    FulfillmentExecutor->>FulfillmentTask: create task (reservationId)
+    FulfillmentExecutor->>StatusHistory: write fulfillment_task_created
+
+    FulfillmentExecutor->>FulfillmentTask: mark picking complete
+    FulfillmentExecutor->>StatusHistory: write picked
+
+    FulfillmentExecutor->>FulfillmentTask: mark shipped
+    FulfillmentExecutor->>StatusHistory: write shipped
+    FulfillmentExecutor->>StockLedger: deduct shipment quantity
+    StockLedger-->>Stock: CDC projection updates available/on-hand
+```
+
+The shipping portion of this flow relies on the warehouse extension executor (`warehouse-fulfillment-task-progress`) to reflect physical operations; Inventory Core focuses on intents, reservations, ledger accuracy, and projecting those ledger deltas into `inventory.stock`.
+
+This scenario keeps the dependency pointing from Inventory back to Order: the order module publishes its own state change (`order.orderItem` row + CDC), and Inventory Core reacts via its executor without requiring an API call from Order into Inventory.
+
+## Dependency Guidelines
+- Inventory Core is the single source of truth for stock; only Core mutates quantities while other modules issue intents.
+- Core depends on shared SKU and location masters (typically from Commerce Core) but does not create reverse dependencies.
+- Industry modules extend the contracts, yet Core itself remains free of industry-specific fields or logic.
+
+## Versioning & Change Management
+- Introduce new optional fields on intent/confirmation tables and allow consumers a migration window.
+- Document naming guidelines and semantics whenever status vocabulary expands, and notify downstream modules.
+- When breaking changes are unavoidable, ship a parallel contract version (for example `inventory.reservationIntent.v2`).
+
+## Operational Considerations
+- Provide reconciliation tools (replay/rebuild) so `inventory.stock` can be regenerated from intents and the ledger.
+- Define locking strategies at SKU and location granularity to minimise contention.
+- Offer batch intents or aggregate APIs for high-volume updates to balance performance and consistency.
+- Establish retention and archiving policies for the ledger and status history based on audit requirements.
+
+## Extension Points for Industry Modules
+- **Lot/serial management**: Attach extension tables with foreign keys such as `lotId` / `serialId` and expose hooks within intent and ledger processing.
+- **Quality inspection**: Append quality-related statuses (for example `inventory:quality_hold`) to `inventory.statusHistory` and integrate with warehouse execution modules.
+- **Construction and bulky goods**: Extend location hierarchies so locations can represent job sites or delivery vehicles.
+- **Healthcare and food**: Track compliance attributes (expiry date, temperature band, etc.) via `attributes` and statuses; implement expiry blocking rules in the extension module.
+
+With this contract in place, scenario documents (channel integration, procurement, inventory reservation, etc.) can gradually migrate to reference Inventory Core. Industry modules achieve required granularity through schema extensions and additional statuses.

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

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

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

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