> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Commerce and Inventory Simulations

> Run isolated 1.39 what-if episodes and compare inventory policies with exact cash, stock-flow reconciliation, and explicit assumptions.

The 1.39 simulation runner executes typed commerce and replenishment scenarios through the
real embedded engine in fresh private stores. It does not read your live store, contact
suppliers, or transfer funds. Results are conditional projections from supplied assumptions.
This surface is different from legacy A2A demos, which have separate `--scenario`/`--live` options.

## Discover the contract

The core MCP profile includes six tools:

| Tool | Use |
| - | - |
| `get_simulation_kernel_contract` | Input schemas, actions, limits, observations, and failure/time semantics |
| `simulate_commerce_scenario` | Orders, captures/refunds, retries, procurement, receiving, shipment and inspection |
| `compare_commerce_scenarios` | Two or three independent typed episodes |
| `simulate_inventory_plan` | Bounded demand, replenishment, stockouts, receipts and cash |
| `compare_inventory_plans` | Independent policy cases with comparison-condition flags |
| `simulate_inventory_experiment` | One to three policies across shared seeds |

The JavaScript entrypoint is `@stateset/cli/simulation`; discovery and simulation tools are
read-permission tools because business mutations are confined to private episode stores.
They allocate local resources, so read permission does not mean zero cost.

## Run a replenishment plan

Install `@stateset/cli@1.39.0`, save this as `inventory-plan.json`, then run the command below:

```json theme={null}
{
  "name": "mug-replenishment",
  "currency": "USD",
  "days": 4,
  "seed": 42,
  "startingCash": "20.00",
  "products": [{
    "sku": "MUG",
    "initialStock": 2,
    "unitPrice": "3.00",
    "unitCost": "1.00",
    "demand": { "dailyUnits": [1, 1, 2, 1] },
    "reorderPoint": 1,
    "targetStock": 4,
    "leadTimeDays": 1,
    "purchasing": { "reviewIntervalDays": 1 }
  }]
}
```

```bash theme={null}
stateset-simulate --inventory-plan inventory-plan.json --json
```

Inspect `success`, run outcomes and `reconciliation`, not only the process exit. Reports retain
per-SKU daily inventory, first unmet-demand stockout, daily cash, and first minimum cash.
An ending zero balance alone is not a stockout. Independent replay checks physical
availability before sales, receipt timing, order sizing and final native balances.

## State the assumptions

* Demand can be seeded ranges/history or an explicit `dailyUnits` schedule of exactly `days`
  entries. Supplied seeds do not alter explicit demand schedules.
* Supplier lead-time/first-fill schedules use order-placement days **0 through days** and
  therefore need `days + 1` entries. Split/delayed receipts retain prepaid inbound value.
* Receipts precede sales, which precede new purchasing. Day-zero purchasing counts toward cash.
* Minimum order sizes, case packs and inventory-position ceilings apply before whole-order
  cash constraints. `cashReserve` withholds shared spending capacity; blocked orders are not shrunk.
* `reviewIntervalDays` defaults to daily. Reviews occur on day zero and interval multiples;
  deferred attempts make no PO or cash movement, and quantities are recomputed at the next review.

## Compare policies and goals

Experiments use two to eight distinct shared seeds with no per-policy seed. Compare exact
financial deltas and `comparisonToBaseline.changedConditions`: opening capital/stock,
prices/costs, purchase priority, reserve, horizon and realized paths may differ.
Path-diversity counts expose repeated trajectories; different seeds do not prove independence.

Money means are exact numerator/denominator fractions. Fill rate is exact sold/demanded;
zero demand is `null`, and service goals are not evaluable. Goals include overall/per-product
fill rates, ending/minimum cash, gross margin and purchasing spend. All goals must pass on
the same seed. A goal miss is a valid result and need not make execution fail. A minimum-cash
goal evaluates policy; `cashReserve` changes spending behavior.

## Limits and interpretation

| Limit | Source value |
| - | - |
| Input | 128 KiB, 16,384 nodes, depth 32 |
| Worker budget | Two active workers per runner process; 30-second timeout |
| Commerce | 32 products, 100 actions; 100 total actions across a comparison |
| Planning | Eight SKUs, 60 days, at most 120 product-days |
| Comparisons / experiments | At most 180 product-days total |
| Experiment | At most 12 native policy/seed runs |

UUIDs and timestamps are not deterministic; aliases and financial outcomes are normalized.
Episodes may span native transactions: inspect state after refusals. Empirical percentiles
summarize selected runs, not calibrated confidence intervals. Taxes, fees, holding costs,
permanent supplier loss and automatic seasonal fitting are outside the reviewed model.
Use [governed execution](/stateset-icommerce/governed-execution) to turn a reviewed decision
into an authorized live operation; a simulation result grants no production authority.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.