@izumisy-tailor/omakase-modules 0.2.0 → 0.3.0

package/src/config/module-loader.ts

@@ -1,9 +1,4 @@
 import { ConfiguredModule } from "../builder/helpers";
-import {
-  clearModuleRegistry,
-  getConfiguredModule,
-  registerConfiguredModules,
-} from "./module-registry";
 
 /**
  * Module loader
@@ -40,6 +35,16 @@ export type LoadedModules = {
   }) => {
     config: C;
   };
+  /**
+   * Get the tables from a dependency module by calling its factory function.
+   * This is used when an executor or resolver needs to reference tables from another module.
+   *
+   * @param factory The factory function exported by the dependency module's tailordb/index.ts
+   * @returns The tables created by the factory
+   */
+  getTables: <T>(
+    factory: (loadedModules: LoadedModules) => Promise<T>
+  ) => Promise<T>;
 };
 
 /**
@@ -50,12 +55,8 @@ export type LoadedModules = {
 export const loadModules = (
   configurator: (loader: ModuleLoader) => ModuleLoader
 ): LoadedModules => {
-  clearModuleRegistry();
-
   const emptyLoader = new ModuleLoader();
-  const modules = registerConfiguredModules(
-    configurator(emptyLoader)._getModules()
-  );
+  const modules = configurator(emptyLoader)._getModules();
 
   const loadedModules = modules.reduce<Record<string, ConfiguredModule<any>>>(
     (acc, module) => {
@@ -65,12 +66,12 @@ export const loadModules = (
     {}
   );
 
-  return {
+  const loadedModulesResult: LoadedModules = {
     loadedModules,
     loadConfig: <C extends Record<string, unknown>>(module: {
       packageName: string;
     }) => {
-      const loadedModule = getConfiguredModule(module.packageName);
+      const loadedModule = loadedModules[module.packageName];
       if (!loadedModule) {
         throw new Error(
           `Module "${module.packageName}" has not been configured. Ensure it is added via loadModules.`
@@ -81,5 +82,12 @@ export const loadModules = (
         config: loadedModule.moduleProps.config as C,
       };
     },
+    getTables: async <T>(
+      factory: (loadedModules: LoadedModules) => Promise<T>
+    ): Promise<T> => {
+      return factory(loadedModulesResult);
+    },
   };
+
+  return loadedModulesResult;
 };

package/src/config/sdk/paths.ts

@@ -1,20 +1,49 @@
 import path from "node:path";
 import { LoadedModules } from "../module-loader";
+import { generateWrapperFiles, OMAKASE_WRAPPER_DIR } from "./wrapper/generator";
 
-export const getModulesReference = (loadedModules: LoadedModules) => {
-  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+export type GetModulesReferenceOptions = {
+  /**
+   * Base path for the application (defaults to process.cwd())
+   */
+  basePath?: string;
+  /**
+   * Whether to suppress log output (defaults to false)
+   */
+  silent?: boolean;
+};
 
-  return {
-    tailordb: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "tailordb", "*.ts")
-    ),
+export const getModulesReference = async (
+  loadedModules: LoadedModules,
+  options: GetModulesReferenceOptions = {}
+) => {
+  const { basePath = process.cwd(), silent = false } = options;
 
-    resolver: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "resolvers", "*.ts")
-    ),
+  // Log loaded modules information
+  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+  if (!silent) {
+    console.log(`[omakase] Loaded ${modulePackageNames.length} module(s):\n`);
+    for (const name of modulePackageNames) {
+      console.log(` * ${name}`);
+    }
+    console.log("");
+  }
+
+  // Generate wrapper files and return paths to them
+  const wrapperPaths = await generateWrapperFiles(loadedModules, basePath);
 
-    executor: modulePackageNames.map((name) =>
-      path.join("node_modules", name, "src", "executors", "*.ts")
-    ),
+  return {
+    tailordb:
+      wrapperPaths.tailordb.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "tailordb", "*.ts")]
+        : [],
+    resolver:
+      wrapperPaths.resolver.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "resolvers", "*.ts")]
+        : [],
+    executor:
+      wrapperPaths.executor.length > 0
+        ? [path.join(OMAKASE_WRAPPER_DIR, "*", "executors", "*.ts")]
+        : [],
   };
 };

package/src/config/sdk/wrapper/base.ts

@@ -0,0 +1,141 @@
+import dedent from "dedent";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Path alias for importing modules config.
+ * App's tsconfig.json should have: "@omakase-modules/config": ["./modules"]
+ */
+export const MODULES_IMPORT_PATH = "@omakase-modules/config";
+
+/**
+ * Category types for wrapper generation
+ */
+export type Category = "tailordb" | "resolvers" | "executors";
+
+/**
+ * Abstract base class for category-specific wrapper generation
+ */
+export abstract class WrapperStrategy {
+  constructor(
+    protected readonly packageName: string,
+    protected readonly basePath: string
+  ) {}
+
+  /**
+   * The category this strategy handles
+   */
+  abstract readonly category: Category;
+
+  /**
+   * Filter files to process for this category
+   */
+  abstract filterFiles(files: string[]): string[];
+
+  /**
+   * Get the module export path
+   */
+  abstract getExportPath(fileName: string): string;
+
+  /**
+   * Generate the export statements using the factory result.
+   * Default implementation exports the result as default export.
+   */
+  protected generateExports(): Promise<string> {
+    return Promise.resolve("export default result;");
+  }
+
+  /**
+   * Generate wrapper file content using template method
+   *
+   * The common header, imports, and factory call are included here.
+   */
+  async generateContent(moduleExportPath: string): Promise<string> {
+    const exports = await this.generateExports();
+
+    return dedent`
+      /**
+       * Auto-generated wrapper file by @izumisy-tailor/omakase-modules
+       * DO NOT EDIT THIS FILE MANUALLY
+       *
+       * This file calls the module's factory function with the app's loadModules result,
+       * ensuring proper configuration injection and avoiding tree-shaking issues.
+       */
+
+      // Import the loadModules result from the app's modules.ts
+      import modules from "${MODULES_IMPORT_PATH}";
+
+      // Import the factory function from the module
+      import createFactory from "${moduleExportPath}";
+
+      // Call the factory with loadModules result
+      const result = await createFactory(modules);
+
+      ${exports}
+    `;
+  }
+
+  /**
+   * Generate wrapper files for this category
+   */
+  async generateFiles(wrapperDir: string): Promise<string[]> {
+    const sourcePath = path.join(
+      this.basePath,
+      "node_modules",
+      this.packageName,
+      "src",
+      this.category
+    );
+
+    // Check if the source directory exists
+    if (!(await this.exists(sourcePath))) {
+      return [];
+    }
+
+    const allFiles = await fs.readdir(sourcePath);
+    const files = this.filterFiles(allFiles);
+    const wrapperPaths: string[] = [];
+
+    for (const file of files) {
+      const wrapperPath = await this.generateFile(wrapperDir, file);
+      wrapperPaths.push(wrapperPath);
+    }
+
+    return wrapperPaths;
+  }
+
+  /**
+   * Generate a single wrapper file for this category
+   */
+  private async generateFile(
+    wrapperDir: string,
+    fileName: string
+  ): Promise<string> {
+    const categoryWrapperDir = path.join(
+      wrapperDir,
+      this.packageName,
+      this.category
+    );
+    await fs.mkdir(categoryWrapperDir, { recursive: true });
+
+    const wrapperFilePath = path.join(categoryWrapperDir, fileName);
+    const moduleExportPath = this.getExportPath(fileName);
+    const content = await this.generateContent(moduleExportPath);
+
+    await fs.writeFile(wrapperFilePath, content, "utf-8");
+
+    return wrapperFilePath;
+  }
+
+  /**
+   * Check if a path exists
+   */
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/config/sdk/wrapper/generator.ts

@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { LoadedModules } from "../../module-loader";
+import { createStrategy } from "./strategies";
+
+/**
+ * Directory where wrapper files are generated
+ */
+export const OMAKASE_WRAPPER_DIR = ".tailor-sdk/.omakase";
+
+/**
+ * Generates wrapper files for each module's tailordb, executor, and resolver files.
+ * These wrappers import the factory functions from modules and call them with
+ * the loadModules result from the app's modules.ts.
+ */
+export const generateWrapperFiles = async (
+  loadedModules: LoadedModules,
+  basePath: string = process.cwd()
+) => {
+  const wrapperDir = path.join(basePath, OMAKASE_WRAPPER_DIR);
+  const modulePackageNames = Object.keys(loadedModules.loadedModules);
+
+  // Clean up existing wrapper directory
+  try {
+    await fs.access(wrapperDir);
+    await fs.rm(wrapperDir, { recursive: true });
+  } catch {
+    // Directory doesn't exist, no need to clean up
+  }
+
+  const result = {
+    tailordb: [] as string[],
+    resolver: [] as string[],
+    executor: [] as string[],
+  };
+
+  for (const packageName of modulePackageNames) {
+    const strategyFor = createStrategy(packageName, basePath);
+
+    result.tailordb.push(
+      ...(await strategyFor("tailordb").generateFiles(wrapperDir))
+    );
+    result.resolver.push(
+      ...(await strategyFor("resolvers").generateFiles(wrapperDir))
+    );
+    result.executor.push(
+      ...(await strategyFor("executors").generateFiles(wrapperDir))
+    );
+  }
+
+  return result;
+};

package/src/config/sdk/wrapper/strategies.ts

@@ -0,0 +1,102 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { Category, WrapperStrategy } from "./base";
+
+/**
+ * Strategy for tailordb category
+ */
+class TailorDBStrategy extends WrapperStrategy {
+  readonly category = "tailordb" as const;
+  filterFiles(files: string[]) {
+    return files.filter((file) => file === "index.ts");
+  }
+
+  getExportPath() {
+    return `${this.packageName}/backend/tailordb`;
+  }
+
+  protected async generateExports() {
+    const tableNames = await this.importTableNames();
+    return tableNames
+      .map((name) => `export const ${name}Table = result.${name};`)
+      .join("\n");
+  }
+
+  /**
+   * Import tableNames from a module's tailordb/index.ts using dynamic import.
+   * Uses createRequire to leverage Node.js module resolution from the app's context.
+   */
+  private async importTableNames(): Promise<readonly string[]> {
+    try {
+      const appRequire = createRequire(
+        path.join(this.basePath, "package.json")
+      );
+      const modulePath = appRequire.resolve(
+        `${this.packageName}/backend/tailordb`
+      );
+      const module = await import(`file://${modulePath}`);
+      if (!module.tableNames) {
+        console.warn(
+          `[warn] tableNames not found in ${this.packageName}/backend/tailordb. Expected: export const tableNames = [...] as const;`
+        );
+        return [];
+      }
+      return module.tableNames;
+    } catch (error) {
+      console.warn(
+        `[warn] Failed to import ${this.packageName}/backend/tailordb:`,
+        error
+      );
+      return [];
+    }
+  }
+}
+
+/**
+ * Strategy for resolvers category
+ */
+class ResolversStrategy extends WrapperStrategy {
+  readonly category = "resolvers" as const;
+
+  filterFiles(files: string[]) {
+    return files.filter((file) => file.endsWith(".ts") && file !== "index.ts");
+  }
+
+  getExportPath(fileName: string) {
+    const baseName = fileName.replace(/\.ts$/, "");
+    return `${this.packageName}/backend/resolvers/${baseName}`;
+  }
+}
+
+/**
+ * Strategy for executors category
+ */
+class ExecutorsStrategy extends WrapperStrategy {
+  readonly category = "executors" as const;
+
+  filterFiles(files: string[]) {
+    return files.filter((file) => file.endsWith(".ts") && file !== "index.ts");
+  }
+
+  getExportPath(fileName: string) {
+    const baseName = fileName.replace(/\.ts$/, "");
+    return `${this.packageName}/backend/executors/${baseName}`;
+  }
+}
+
+/**
+ * Factory to create strategy instance for each category.
+ * Returns a function that takes a category and returns a strategy.
+ */
+export const createStrategy =
+  (packageName: string, basePath: string) =>
+  (category: Category): WrapperStrategy => {
+    switch (category) {
+      case "tailordb":
+        return new TailorDBStrategy(packageName, basePath);
+      case "resolvers":
+        return new ResolversStrategy(packageName, basePath);
+      case "executors":
+        return new ExecutorsStrategy(packageName, basePath);
+    }
+  };

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

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