# Ship a package simulator

> **Use case id:** `ship-package-simulator`
> **Goal:** Structure a product-owned package with logic, data, optional static-memorix composition, and core-service on the HTTP entry.
> **Audiences:** developers
> **Tags:** packages, memorix, core-service

## Reading path

1. **Package Simulators** (developers) → chapters: `1-what-a-package-simulator-is`, `2-recommended-structure`, `4-with-static-memorix`
1. **Adapters and Helpers** (developers) → chapters: `2-http-process-compliance-local-services`

## From: Package Simulators — 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.

---

## From: Package Simulators — 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).

---

## From: Package Simulators — 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.).

---

## From: Adapters and Helpers — 2. HTTP process compliance (local services)

Any example or package simulator that **binds an HTTP port** should use [`@x12i/core-service`](https://www.npmjs.com/package/@x12i/core-service) (pulls `@x12i/api-live-view`; uses `@x12i/ports-manager`).

Product contract (current **`@x12i/memorix-docs`**, not old memorix-ebooks):

- Use case **`http-process-compliance`**
- Building Services (developers) → **HTTP process compliance (local services)**
- Deep reference: package READMEs for `core-service`, `ports-manager`, `api-live-view`

This repo applies that contract in zone **`api-simulator` (5520–5539)** — not Memorix’s 5100–5119.

| Surface | Role |
|--------|------|
| Port from zone map | `scripts/api-simulator-ports.mjs` / `createSimulatorHttp` |
| `GET /health` | Process liveness |
| `/_live` | In-process request rings (api-live-view) |
| `x-correlation-id` | Request/response correlation |
| Startup banner | origin · health · live · docs |

Shared helper:

```js
import { createSimulatorHttp } from '../../scripts/create-simulator-http.mjs';

const { core, announce } = createSimulatorHttp({
  id: 'my-simulator',
  title: 'My package simulator',
  portKey: 'api', // or flowstate / libraryDemo
  portEnv: 'API_SIMULATOR_API_PORT'
});

const server = createServer(async (req, res) => {
  if (await core.tryHandleCore(req, res)) return;
  await createNodeHttpHandler(simulator)(req, res);
});

await announce(server);
```

Published `@x12i/api-simulator` stays **zero runtime dependencies**. Remote *clients* do not install these kits; *servers that bind* do.

---

## Also see

- **Package Simulators** (`03-package-simulators`) — Ship logic, data, and optional Memorix fixtures in a product package — with or without static-memorix.
- **Adapters and Helpers** (`02-adapters`) — Expose simulators over HTTP, compose helpers, and plug into Express, Fastify, or fetch runtimes.

---

_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._