# Package Simulators — Developers

**Audience:** Engineers shipping product-owned simulator packages.  
**Related:** [Overview](../00-overview/developers/BOOK.md) · [Behaviors](../01-behaviors/developers/BOOK.md)

---

## 1. What a package simulator is

A **package simulator** is a small product-owned package that uses `@x12i/api-simulator` as the engine and ships its own:

- **logic** — `simulation` handlers (and optional `createStore` state)
- **data** — seeds under `api.data` and/or fixture JSON
- **metadata** — when the product speaks Memorix, declarative packs and explorer fixtures

The core library stays **zero runtime dependencies** and does not load data or metadata from disk, MongoDB, or HTTP. Your package (or an example like `examples/flowstate-simulator`) owns that.

---

## 2. Recommended structure

```text
my-provider-simulator/
├─ mocks/                    # optional — shared with static-memorix when used
│  ├─ data/
│  ├─ metadata/
│  └─ metadata-packs/
├─ src/
│  ├─ data/                  # seeds for api.data / createStore
│  ├─ simulations/           # package-specific handlers
│  ├─ api.ts                 # createApiSimulator({ apis: [...] })
│  ├─ memorix.ts             # optional — buildServer({ MOCKS_DIR })
│  └─ server.ts              # Node/HTTP entry: core-service + tryDispatch ± forward
└─ package.json
```

Keep provider-specific data and simulation logic outside `@x12i/api-simulator`. The core remains the reusable engine.

HTTP entrypoints that bind a port use [`@x12i/core-service`](https://www.npmjs.com/package/@x12i/core-service) (see [Adapters — HTTP process compliance](../02-adapters/developers/BOOK.md#2-http-process-compliance-local-services)). Shared helper in this repo: [`scripts/create-simulator-http.mjs`](../../../scripts/create-simulator-http.mjs).

---

## 3. Plain REST library-demo

If the API is ordinary REST (no Memorix), follow [`examples/library-demo/TUTORIAL.md`](../../../examples/library-demo/TUTORIAL.md):

1. Data modules seed `api.data` / `createStore`.
2. Relative endpoints for list/read shapes; simulation handlers for writes and branching.
3. `createApiSimulator` + optional Node HTTP entry — **no** `@x12i/static-memorix`.

Runnable reference: [`examples/library-demo/`](../../../examples/library-demo).

---

## 4. With static-memorix

For Memorix Explorer (`/api/explorer/*`) and Metadata (`/api/metadata/*`) parity without MongoDB/Redis, compose [`@x12i/static-memorix`](https://www.npmjs.com/package/@x12i/static-memorix):

1. Keep a shared `mocks/` tree (`data/`, `metadata/`, `metadata-packs/`).
2. Load seeds into package REST via small helpers (see the FlowState example’s `src/bridge.mjs`).
3. Run `buildServer()` / `startServer()` with `MOCKS_DIR` pointing at that tree.
4. Serve one port with `@x12i/core-service`: `tryHandleCore` → `tryDispatch` package routes → forward misses to static-memorix (`inject`).

| Surface | Owner |
|--------|--------|
| `/health`, `/_live` | `@x12i/core-service` (zone `api-simulator`) |
| `/api/v1/<your-product>/*` | `@x12i/api-simulator` endpoints in your package |
| `/api/explorer/*`, `/api/metadata/*` | `@x12i/static-memorix` (`MOCKS_DIR` → shared `mocks/`) |

**Org scope:** `x-memorix-org-id` may be sent for client realism; it is a **no-op for isolation** in this simulator (not `memorix-service`).

static-memorix is not a substitute for full `memorix-service` (pipelines, relationship materialize, abstract reverse-write, etc.).

---

## 5. FlowState walkthrough

Full compose walkthrough: [`examples/flowstate-simulator/TUTORIAL.md`](../../../examples/flowstate-simulator/TUTORIAL.md).

```bash
node examples/flowstate-simulator/demo.mjs
node examples/flowstate-simulator/src/server.mjs   # :5522
```