@crvouga/mockingbird-service-junction 0.1.2 → 0.3.0

package/README.md

@@ -1,20 +1,26 @@
 # @crvouga/mockingbird-service-junction
 
-Stateful, in-process mock of the [Junction (formerly Vital) API](https://docs.junction.com/) for
-test suites: users (`/v2/user`), the lab-testing catalog, lab orders (create, cancel, simulate,
-results, requisitions), and at-home phlebotomy / patient-service-center (PSC) scheduling
-(availability, booking, reschedule, cancel), plus the `labtest.order.*` and
-`labtest.appointment.updated` webhook events. All 39 operations in the vendored OpenAPI subset are
-served; behaviour is verified by differential property tests against the Junction sandbox.
+Stateful mock of the [Junction (formerly Vital) API](https://docs.junction.com/): users
+(`/v2/user`), the lab-testing catalog, lab orders (create, cancel, simulate, results,
+requisitions), at-home phlebotomy and patient-service-center (PSC) scheduling, and the
+`labtest.order.*` / `labtest.appointment.updated` webhooks. All 40 operations in the vendored
+OpenAPI subset are served, and behaviour is checked by differential property tests against the
+Junction sandbox.
 
-Use it when your backend calls Junction via `fetch` or `@tryvital/vital-node` and you want tests to
-run offline, deterministically, with no sandbox key.
+Use it to take Junction off your suite's critical path: no sandbox key, no shared 50-user sandbox
+cap (the mock enforces no sandbox limit unless a test [asks for one](#sandbox-limits)), no
+cross-suite interference. Serve it as a local origin with one command, or run it in-process.
+
+```bash
+npx mockingbird-junction serve   # http://127.0.0.1:8787, recorded sandbox corpus loaded
+```
 
 - Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/SUPPORT.md)
-- Drop-in readiness, sealed corpus and sandbox quirks the mock mirrors:
+- Drop-in readiness and the sandbox quirks the mock mirrors:
   [docs/drop-in.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/drop-in.md)
-- Consumer wiring checklist: [docs/qa-followon.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/qa-followon.md)
 - Behaviour notes: [docs/behavior.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/behavior.md)
+- **What the mock does not model:** [below](#what-is-and-is-not-modelled). Read it before trusting a
+  green suite.
 
 ## Install
 
@@ -22,22 +28,125 @@ run offline, deterministically, with no sandbox key.
 npm install -D @crvouga/mockingbird-service-junction
 ```
 
-ESM only. Requires Node >= 22 or Bun >= 1.2. No native dependencies: state lives in an in-memory
-SQLite engine (pure TypeScript, bundled in). To serve it over HTTP use `Bun.serve` under Bun, or
-install `@hono/node-server` under Node.
+ESM only; Node >= 22 or Bun >= 1.2 (CommonJS callers on Node >= 22.12 can `require()` it). No
+native dependencies: state lives in an in-memory SQLite engine written in TypeScript, bundled in.
+
+| Entry point | Runtime | What it is |
+| --- | --- | --- |
+| `@crvouga/mockingbird-service-junction` | any (Node, Bun, Workers, browsers) | `JunctionAPI`, `createRuntime`, corpus and verify tools |
+| `@crvouga/mockingbird-service-junction/server` | Node | `createServer()` — a listening HTTP server |
+| `@crvouga/mockingbird-service-junction/corpus` | any | `defaultCorpus` — the recording shipped in the package (a separate entry, so importing the mock never parses it) |
+| `mockingbird-junction` (bin) | Node | `serve`, `corpus pull`, `corpus diff`, `verify` |
 
 ## Usage
 
-Behaviour the examples rely on (all from the source):
+### `mockingbird-junction serve`
+
+```bash
+npx mockingbird-junction serve --port 8787
+npx mockingbird-junction serve --corpus ./test/junction-corpus.json --lab-accounts ./test/lab-accounts.json
+npx mockingbird-junction serve --webhook-url http://127.0.0.1:3100/webhooks/junction --webhook-secret whsec_...
+npx mockingbird-junction serve --help
+```
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--port <n>` | `8787` | Port to listen on (`0` for any free port; the bound URL is printed) |
+| `--host <host>` | `127.0.0.1` | Interface to bind |
+| `--corpus <default\|none\|file>` | `default` | The shipped corpus, no corpus (synthetic data), or a file from `corpus pull` |
+| `--geo <corpus\|synthetic>` | `corpus` with a corpus | How unknown ZIPs are answered; see [Geo](#geo-corpus-or-synthetic) |
+| `--lab-accounts <file>` | built-in fixtures | [Lab accounts](#lab-accounts): a JSON array, or `{ "presets": [...], "accounts": [...] }` |
+| `--team-id <uuid>` | the corpus's team | The [team](#team-identity) the mock answers as |
+| `--max-users <n>` | unlimited | Enforce the sandbox's [live-user cap](#sandbox-limits) |
+| `--identity <strict\|adopt-users>` | `strict` | Unknown `user_id`s: 404, or [create on first use](#fixtures-and-identity) |
+| `--fixtures <file>` | — | [Users and orders](#fixtures-and-identity) every namespace starts with |
+| `--journal-size <n>` | `1000` | Requests each namespace's [journal](#is-this-the-mock) keeps |
+| `--webhook-url <url>` / `--webhook-secret <whsec_…>` | off | Deliver [signed webhooks](#webhooks) (secret also from `MOCKINGBIRD_JUNCTION_WEBHOOK_SECRET`) |
+| `--webhook-retry-delays <ms,…>` | Svix's schedule | Delay before each delivery attempt, e.g. `0,1000,5000` in tests |
+| `--webhook-scope <scope>` | — | Sent as `x-mockingbird-scope` on every delivery |
+| `--admin-key <key>` | open | Require `x-mockingbird-admin-key` on `/__admin/*` (also `MOCKINGBIRD_ADMIN_KEY`) |
+| `--seed <seed>` | `0` | Seeds fault rates and retry jitter |
+| `--log <pretty\|json\|off>` | `pretty` | One line per request: operation id, status, duration, namespace, fault |
+| `--log-requests` | — | Same as `--log json`: one JSON line per request with the ids it touched, never bodies |
+| `--seed-url <url>` / `--seed-key <key>` | — | Pull a corpus from a live team at boot. Slow and a live dependency; prefer a committed `corpus pull` file |
+| `--config <file>` | — | Serve every service in a `mockingbird.json` instead ([below](#many-services-from-one-config)) |
+
+At startup it prints the listen address, the loaded corpus (its version label, observation, ZIP,
+lab-test and lab-account counts, recording date and source), the geo mode, the team id, the
+lab-account count, which sandbox limits are on (normally none), the identity mode, and whether
+webhook delivery is on.
+
+### Many services from one config
+
+Any Mockingbird service's CLI can boot every service in a config file, so a stack adds a config
+entry per vendor instead of a wrapper process per vendor. Each service named must be installed
+(`junction` loads `@crvouga/mockingbird-service-junction`).
+
+```json
+{
+  "log": "json",
+  "services": {
+    "junction": {
+      "port": 8787,
+      "adminKey": "local-admin",
+      "options": { "corpus": "./test/junction-corpus.json", "webhook-url": "http://127.0.0.1:3100/webhooks/junction" }
+    },
+    "stripe": { "port": 12111 }
+  }
+}
+```
+
+```bash
+npx mockingbird-junction serve --config mockingbird.json
+```
+
+`options` takes the service's own `serve` flags by long name.
+
+### `createServer` (Node)
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-junction/server"
+
+const server = await createServer() // shipped corpus, any free port
+const health = await fetch(`${server.url}/health`)
+console.log(health.status) // 200
+
+// Point the Vital SDK (or your backend's Junction base URL) at server.url, then:
+await server.close()
+```
+
+`createServer(options)` takes every [`createRuntime`](#createruntime-any-fetch-server) option plus
+`port` (default `0`), `host` (default `127.0.0.1`) and `corpus` (`"default"`, `"none"`, a file path
+or a loaded corpus). The result has `url`, `port`, `runtime` and `close()`.
+
+### `createRuntime` (any Fetch server)
+
+`createRuntime` is the whole served mock — health, admin, namespaces, clock, faults, metrics — as a
+single runtime-neutral `fetch(request)`. Hand it to `Bun.serve`, a Worker, or call it directly:
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-junction"
+import { defaultCorpus } from "@crvouga/mockingbird-service-junction/corpus"
+
+const junction = createRuntime({ corpus: defaultCorpus })
+const as = (worker: string) => ({
+  "x-vital-api-key": "sk_us_mockingbird",
+  "x-mockingbird-namespace": worker, // isolates this worker's data
+  "content-type": "application/json",
+})
+
+await junction.fetch(
+  new Request("http://junction.local/v2/user", {
+    method: "POST",
+    headers: as("worker-1"),
+    body: JSON.stringify({ client_user_id: "patient-1" }),
+  }),
+)
+const other = await junction.fetch(new Request("http://junction.local/v2/user", { headers: as("worker-2") }))
+console.log(await other.json()) // worker-2 sees none of worker-1's users
 
-- **Any host works.** Routing uses only the path (`/v2/...`, `/v3/...`).
-- **Auth:** every request needs an `x-vital-api-key` header; any value is accepted (sandbox keys
-  look like `sk_us_*` / `sk_eu_*`). Without it the response is `401 {"detail":"Missing x-vital-api-key"}`.
-  State is not partitioned by key: all requests share one team (`team_id`
-  `11111111-1111-4111-8111-111111111111`).
-- Bodies are JSON with the API's snake_case field names.
-- A default synthetic catalog is installed at construction (lab tests with methods
-  `walk_in_test`, `testkit` and `at_home_phlebotomy`); `installCorpus` replaces it with a recording.
+await junction.reset("worker-1") // or junction.reset("*") for every namespace
+```
 
 ### In-process (inject `fetch`)
 
@@ -95,169 +204,559 @@ console.log(junction.webhookEvents().map((event) => event.event_type)) // ["labt
 simulations (`POST /v3/order/{id}/test?final_status=completed&delay=<seconds>`) become due; the
 delayed transition is applied on the next `GET /v3/order/{id}` whose `now` is past the due time.
 
-### Over HTTP
+### Pointing `@tryvital/vital-node` at it
 
-```ts
-import { JunctionAPI } from "@crvouga/mockingbird-service-junction"
+The official SDK takes the base URL as `environment` (this is how the package's SDK drop-in test
+constructs it):
 
-const junction = new JunctionAPI()
-const server = Bun.serve({
-  port: 0, // ephemeral
-  hostname: "127.0.0.1",
-  fetch: (request) => junction.fetch(request),
-})
-const baseUrl = `http://127.0.0.1:${server.port}`
+```js
+import { VitalClient } from "@tryvital/vital-node"
+
+const client = new VitalClient({ apiKey: "sk_us_mockingbird", environment: baseUrl })
+const user = await client.user.create({ clientUserId: "app-user-1" })
+```
+
+If your app guards Junction hosts with an allowlist, allow `127.0.0.1` / `localhost` for tests
+while keeping the production and sandbox guards intact.
+
+## The service contract
+
+Every Mockingbird service answers the same control surface, outside the vendor's auth gate:
+
+- `GET /health` — unauthenticated readiness probe:
+  `{ "status": "ok", "service": "junction", "corpus": "<label>", "geo": "corpus", … }`.
+- `/__admin/*` — the control plane. Open by default; with `--admin-key` / `adminKey` it requires
+  `x-mockingbird-admin-key`, which is separate from any vendor key. Admin errors have one shape,
+  `{ "error": { "type": "mockingbird_admin", "message": "…" } }`, so they can never be confused
+  with a Junction error. `GET /__admin` lists every route.
+- `x-mockingbird-namespace: <name>` — isolates a request's data (`[A-Za-z0-9_.-]{1,64}`). Each
+  namespace is a separate team over one shared database, so parallel workers share one process
+  without seeing each other. The corpus is shared read-only; creating a namespace is cheap. Admin
+  routes take the namespace from `?namespace=`, then the header, then `default`. Configuration set
+  through the admin API (lab accounts, limits, identity, geo) belongs to one namespace and survives
+  that namespace's `POST /__admin/reset`; data does not.
+- `x-mockingbird: junction@<version>; ns=<namespace>` — on **every** response: vendor answers,
+  errors, faults, admin and health. Junction never sends it, so it tells the mock from the vendor
+  (see [Is this the mock?](#is-this-the-mock)).
+
+| Route | Does |
+| --- | --- |
+| `POST /__admin/reset` | Reset the request's namespace; `?all=1` resets every namespace |
+| `GET /__admin/namespaces` | Namespaces created so far |
+| `POST /__admin/snapshots` | Snapshot the namespace; returns `{ id }` |
+| `POST /__admin/snapshots/{id}/restore` | Restore it (an assignment: later writes are discarded) |
+| `DELETE /__admin/snapshots/{id}` | Forget a snapshot |
+| `GET` / `POST /__admin/clock` | Read or move the clock: `{ "set": "2030-01-01T00:00:00Z" }`, `{ "advance": "2h" }`, `{ "freeze": true }`, `{ "reset": true }` |
+| `GET` / `POST` / `DELETE /__admin/faults` | List, add or clear [fault rules](#faults-and-error-shapes) (`DELETE ?id=` removes one) |
+| `POST /__admin/faults/presets/{name}` | Add a named Junction fault; body may override `count`, `rate`, `operationId`… |
+| `GET /__admin/metrics` | Requests by operation and status, fault count, and **unmatched routes** |
+| `GET /__admin/orders` | Orders in the namespace with their current status |
+| `POST /__admin/orders/{id}/transition` | Move an order: `{ "to": "completed", "result": "abnormal" }` ([order control](#order-control)) |
+| `GET` / `PUT /__admin/results/{id}` | Read or install an exact result payload / PDF for an order |
+| `GET /__admin/result-fixtures` | The named results |
+| `GET` / `PUT /__admin/lab-accounts` | Read or replace the namespace's [lab accounts](#lab-accounts) (`{ "accounts": [...], "presets": [...] }`; `{ "accounts": null }` restores the default) |
+| `POST /__admin/lab-accounts` | Add one account; 409 if the id exists |
+| `PATCH` / `DELETE /__admin/lab-accounts/{id}` | Merge fields into an account (`{ "status": "suspended" }`, `{ "states": [...] }`) / remove it; 404 if absent |
+| `GET /__admin/lab-accounts/presets` | Every [preset](#lab-account-presets), with its full record |
+| `POST /__admin/lab-accounts/presets/{name}` | Add a preset account; body `{ "id": "…" }` overrides its id |
+| `GET /__admin/team` | `{ "teamId" }` — the [team](#team-identity) the namespace answers as |
+| `GET` / `PUT /__admin/limits` | Read or change the namespace's [sandbox limits](#sandbox-limits) |
+| `GET` / `PUT /__admin/identity` | Read or set `{ "mode": "strict" \| "adopt-users" }` ([identity](#fixtures-and-identity)) |
+| `POST /__admin/users`, `POST /__admin/users/bulk` | Insert a user (or `{ "users": [...] }`, all or none) with a chosen `user_id`; 409 on a duplicate id or `client_user_id` |
+| `DELETE /__admin/users/{id}` | Remove a user outright, leaving no deletion tombstone |
+| `POST /__admin/orders` | Insert an order, optionally already in a `status`, through `create_order`'s record builder |
+| `POST /__admin/import` | `{ "users": [...], "orders": [...] }` in one call |
+| `GET` / `DELETE /__admin/requests` | The namespace's [request journal](#is-this-the-mock) (`?operationId=`, `?status=`, `?since=`, `?limit=`, `?all=1`) / clear it |
+| `GET /__admin/corpus`, `PUT /__admin/geo` | The loaded corpus; switch [geo mode](#geo-corpus-or-synthetic) |
+| `GET /__admin/webhooks` | [Deliveries](#webhooks) with every attempt |
+| `POST /__admin/webhooks/{id}/replay`, `POST /__admin/webhooks/flush` | Redeliver one message; run pending retries now |
+| `GET /__admin/webhooks/events` | Every event recorded, delivered or not |
+
+`GET /__admin/metrics` → `unmatched` counts requests to paths the contract does not have. It is how
+a new SDK call shows up — as a count — before it fails a suite as a 404.
+
+## Corpus
+
+Provider-owned inventory — area serviceability, PSC site lists, the lab catalog, labs, lab
+accounts — cannot be synthesized faithfully. A corpus is an exact recording of those
+parameter-stable reads, and the mock answers them byte for byte.
+
+**The shipped corpus** (`defaultCorpus`, and what `serve` loads unless told otherwise) was recorded
+from the Junction sandbox. It covers area and PSC serviceability for 57 ZIPs across the US, the PSC
+labs those ZIPs reach, and the recording team's catalog. The catalog and lab accounts belong to the
+**recording team**: lab-test ids are per team, so your product's ids will not be in it. For your
+catalog and your lab accounts, record your own team and commit the file:
+
+```bash
+npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --out test/junction-corpus.json
+npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --base test/junction-corpus.json \
+  --zip 10001,94105 --coverage-only --out test/junction-corpus.json   # add ZIPs to it
+npx mockingbird-junction corpus diff test/junction-corpus.json /tmp/fresh.json   # exit 1 when they differ
+```
+
+`corpus pull` only issues GETs, refuses non-sandbox keys (`sk_us_…` / `sk_eu_…`) unless given
+`--allow-any-key`, and stamps the file with a SHA-256 `fingerprint` of its content (not its
+recording time), so re-pulling unchanged data yields the same fingerprint. Availability is never
+recorded: its slot dates and single-use `booking_key`s cannot be replayed, so it always comes from
+the deterministic generator.
+
+### Geo: corpus or synthetic
+
+With a corpus loaded, serviceability reads (`area/info`, `psc/info`, phlebotomy and PSC
+availability) answer **only** for ZIPs the corpus covers. Any other well-formed ZIP gets:
+
+```json
+{
+  "detail": {
+    "error_type": "MOCKINGBIRD_UNKNOWN_ZIP",
+    "error_message": "ZIP 00501 is not in the loaded Junction corpus (57 ZIPs covered). Record it with `mockingbird-junction corpus pull --zip 00501`, or serve with --geo synthetic to invent coverage.",
+    "zip_code": "00501",
+    "corpus": "v1-2026-09-18-HqFDuEAuhkwD"
+  }
+}
+```
+
+with status **424**, which Junction never sends and HTTP clients do not retry: a fixture gap fails
+loudly instead of silently disagreeing with production. A malformed ZIP still gets Junction's own
+422. `--geo synthetic` (the default without a corpus) invents plausible, deterministic coverage
+instead — right for property tests that walk random ZIPs, wrong for a suite standing in for
+production.
 
-const response = await fetch(`${baseUrl}/v2/user`, {
-  headers: { "x-vital-api-key": "sk_us_mockingbird" },
+## Lab accounts
+
+`create_order` routes, accepts and rejects `lab_account_id` against the team's lab accounts,
+following Junction's documented rules: an explicit id must exist, be linked to the team, belong to
+the ordered lab and be active; with no id, one active account for the lab is selected, several are
+an error, and a lab with none falls back to Junction's platform account. The billing type must be
+allowed in the patient's state by the account's `allowed_billing`.
+
+The accounts come from, in order: `labAccounts` / `--lab-accounts`, else the corpus (a pulled
+corpus carries your team's real accounts), else built-in fixtures. Configure them as
+`ClientFacingLabAccount`s, with `states` as shorthand for client-bill states:
+
+```ts
+import { createRuntime, US_STATES } from "@crvouga/mockingbird-service-junction"
+
+const junction = createRuntime({
+  labAccounts: [
+    { id: "acct-bioref-nynj", lab: "bioreference", states: ["NY", "NJ"] },
+    {
+      id: "acct-labcorp-47",
+      lab: "labcorp",
+      states: US_STATES.filter((state) => !["NY", "NJ", "RI"].includes(state)),
+    },
+    { id: "acct-quest", lab: "quest", delegated_flow: "order_delegated" },
+  ],
 })
-console.log(response.status) // 200
+console.log(junction.instance().labAccounts().length) // 3
+```
+
+Rejections keep Junction's body shape, `400 {"detail": "Lab account is not associated with lab labcorp"}`.
+`delegated_flow` is stored and listed, but see [not modelled](#what-is-and-is-not-modelled).
+
+Availability reads that take a `lab_account_id` (`GET /v3/order/area/info`) check it against the
+same live list, so an id `create_order` accepts is never a 404 there.
 
-server.stop()
+### Changing accounts at runtime
+
+Each namespace has its own layout, kept across its own reset. Change one account at a time, or
+replace them all:
+
+```bash
+curl -X POST  localhost:8787/__admin/lab-accounts/presets/bioreference_ny_nj_delegated
+curl -X PATCH localhost:8787/__admin/lab-accounts/$ID -d '{"status": "suspended"}'
+curl -X POST  localhost:8787/__admin/lab-accounts -d '{"id": "…", "lab": "quest", "states": ["AZ"]}'
+curl -X DELETE localhost:8787/__admin/lab-accounts/$ID
+curl -X PUT   localhost:8787/__admin/lab-accounts -d '{"presets": ["quest_platform"], "accounts": []}'
 ```
 
-On Node use any Fetch-style server, e.g. `@hono/node-server` (`npm install -D @hono/node-server`),
-whose callback receives the bound port:
+A bad field is a 400 in the admin shape naming it, e.g. `lab account x: states: ZZ is not a US
+state code`. `--lab-accounts` and the `labAccounts` option take the same layout, so a stack can
+declare it at boot with no admin call:
 
-```js
-import { serve } from "@hono/node-server"
-const server = serve(
-  { fetch: (request) => junction.fetch(request), port: 0, hostname: "127.0.0.1" },
-  (info) => console.log(`http://127.0.0.1:${info.port}`),
-)
-// ... later: server.close()
+```json
+{ "presets": ["bioreference_ny_nj_delegated", { "name": "quest_platform", "id": "…" }], "accounts": [] }
 ```
 
-### Pointing `@tryvital/vital-node` at it
+### Lab-account presets
 
-The official SDK takes the base URL as `environment` (this is how the package's SDK drop-in test
-constructs it):
+Named after what they model; ids are `deterministicUuid("junction:lab-account:<name>")` unless
+given. Where a preset copies an account recorded from a real BioReference-linked sandbox team
+(2026-09-21), its billing states are the recording's. `PLATFORM_ACCOUNT_STATES` is every state
+but NJ, NY and RI (47).
 
-```js
-import { VitalClient } from "@tryvital/vital-node"
+| Preset | `lab` | `delegated_flow` | `allowed_billing` | `team_id_allowlist` | Source |
+| --- | --- | --- | --- | --- | --- |
+| `bioreference_ny_nj_delegated` | `bioreference` | `order_delegated` | `client_bill`: NY, NJ | the team | requested shape, **not** a recorded account |
+| `bioreference_delegated_multi_state` | `bioreference` | `order_delegated` | `client_bill`: every state but NY, NJ (48) | the team | recorded |
+| `bioreference_customer_multi_state` | `bioreference` | `not_delegated` | `client_bill`: `PLATFORM_ACCOUNT_STATES` | `[]` | recorded ("Junction BioReference Account") |
+| `bioreference_patient_bill_passthrough` | `bioreference` | `not_delegated` | `patient_bill_passthrough`: NJ, NY | the team | recorded |
+| `quest_platform` / `labcorp_platform` | `quest` / `labcorp` | `not_delegated` | `client_bill`: `PLATFORM_ACCOUNT_STATES` | `[]` | recorded ("Junction Quest/Labcorp Account") |
+| `suspended_bioreference` / `suspended_quest` / `suspended_labcorp` | as above | `not_delegated` | as the platform accounts | `[]` | the platform shapes with `status: "suspended"` |
 
-const client = new VitalClient({ apiKey: "sk_us_mockingbird", environment: baseUrl })
-const user = await client.user.create({ clientUserId: "app-user-1" })
+Every preset is `status: "active"` unless named `suspended_*`. `GET /__admin/lab-accounts/presets`
+returns the full records.
+
+### Team identity
+
+The mock answers as one team: `team_id` on users, orders and webhooks, and the team that
+`team_id_allowlist` is checked against. It is, in order: `teamId` / `--team-id`, the team a
+version-2 corpus recorded (`corpus pull` reads it from a listed user, else from the accounts'
+allowlists), else the fixed `MOCK_TEAM_ID`. `GET /__admin/team` reports it.
+
+A version-2 corpus keeps each account's allowlist **verbatim**, so an account the real team is not
+linked to answers `400 {"detail": "Lab account is not linked to your team"}` exactly as it does
+live. A version-1 corpus (no `teamId`) still loads and behaves as 0.2.0 did: every recorded account
+is also linked to the mock team.
+
+**Open question — empty allowlists.** Junction's own Quest, Labcorp and BioReference accounts carry
+`team_id_allowlist: []`, and a real team's listing returns them, so the mock lists them and treats
+them as linked. Whether *ordering* through one — by explicit id, or when it is one of several
+active accounts for a lab with the id omitted — behaves the same live is **not verified**.
+`verify --orders` checks it whenever the corpus has such an account; until a run records the
+answer, a suite that depends on it should run against the sandbox too.
+
+## Sandbox limits
+
+The mock exists to escape the sandbox's restrictions, so it enforces none of them unless a test
+asks — this is a tested guarantee (500 users in a loop all succeed), not an accident.
+
+| Sandbox limit | Modelled | Default | Turn it on |
+| --- | --- | --- | --- |
+| 50 live users per team | yes, byte-exact body; deleted users free their slot | off (unlimited) | `limits: { maxUsers: 50 }`, `--max-users 50`, `PUT /__admin/limits {"maxUsers": 50}` |
+| `POST /v3/order/{id}/test` only in sandbox | as a switch: refuses a key that is not `sk_us_…`/`sk_eu_…` (400, body not recorded) | off | `simulateRequiresSandbox: true` |
+| Rate limits | as a per-namespace budget: 429 `{"detail":"Too Many Requests"}`, `retry-after: 1` (shape not recorded) | off | `rateLimitPerSecond: n` |
+
+`PUT /__admin/limits` merges (`null` lifts a numeric limit) and is per namespace;
+`GET /__admin/limits` returns the effective values. For a one-off failure instead of a standing
+limit, the `sandbox_user_quota` [fault preset](#faults-and-error-shapes) is still there.
+
+## Fixtures and identity
+
+A suite often needs state the public API cannot build: database fixtures that already carry real
+Junction `user_id`s, or an order already in some status. Insert them directly:
+
+```bash
+curl -X POST localhost:8787/__admin/users -d '{"user_id": "3f0c…", "client_user_id": "patient-1"}'
+curl -X POST localhost:8787/__admin/orders -d '{"user_id": "3f0c…", "lab_test_id": "…", "status": "completed"}'
+curl -X POST localhost:8787/__admin/import -d @test/junction-fixtures.json
 ```
 
-If your app guards Junction hosts with an allowlist, allow `127.0.0.1` / `localhost` for tests
-while keeping the production and sandbox guards intact.
+- Users take `user_id?`, `client_user_id`, `created_on?`, `fallback_time_zone?`,
+  `fallback_birth_date?`, `ingestion_start?`, `ingestion_end?`. A duplicate `user_id` or
+  `client_user_id` is a 409; `POST /__admin/users/bulk` inserts all or none.
+- Orders take `order_id?`, `user_id`, `lab_test_id`, `lab_account_id?`, `status?` (any
+  [transition target](#order-control)), `collection_method?`, `patient_details?`,
+  `patient_address?`, `billing_type?`, `created_at?` and `result_fixture?` (as
+  `PUT /__admin/results/{id}` takes it). Request validation is skipped; references are not — the
+  user and lab test must exist (404 otherwise).
+- Inserted records go through the same builders as `create_user` / `create_order`, so every read
+  path (`GET /v2/user/{id}`, resolve by `client_user_id`, `GET /v3/order/{id}`,
+  `GET /v3/orders?user_id=`) sees them as API-created. Default timestamps read the mock clock.
+- **No webhook fires** unless the body has `"emitWebhooks": true`: fixtures should not trigger
+  backend side effects.
+- `fixtures` / `--fixtures <file>` loads `{ "users": [...], "orders": [...] }` into every namespace
+  at creation and again on each reset.
+
+For flow suites that do not care about Junction identity, `identity: "adopt-users"` (or
+`--identity adopt-users`, or `PUT /__admin/identity {"mode": "adopt-users"}` per namespace) creates
+an unknown, well-formed `user_id` on first use — in `create_order` and `GET /v3/orders?user_id=` —
+and the request proceeds. The journal marks the request `adopted: true`. **Orders are never
+adopted**: an unknown order id always 404s, because inventing an order hides real bugs. The default,
+`strict`, is Junction's own behaviour.
+
+## Is this the mock?
+
+A mock 404 and a sandbox 404 are byte-identical, which is how a backend half-pointed at the sandbox
+goes unnoticed. Three things make it visible:
+
+- **`x-mockingbird` on every response.** Assert on it in a test helper:
+
+  ```ts
+  import { expect } from "vitest"
+
+  /** Wrap the fetch your Junction client uses; fails any call that did not reach the mock. */
+  export const mockOnlyFetch =
+    (inner: typeof fetch = fetch): typeof fetch =>
+    async (input, init) => {
+      const response = await inner(input, init)
+      expect(response.headers.get("x-mockingbird"), `${String(input)} did not reach the Junction mock`).toMatch(
+        /^junction@/,
+      )
+      return response
+    }
+  ```
+
+- **The request journal.** Each namespace keeps its last 1000 requests (`--journal-size`,
+  `journalSize`): operation id, method, path, status, duration, fault id, the user / order /
+  lab-account ids it touched, and when (mock clock). `GET /__admin/requests?operationId=create_order_v3_order_post`
+  proves an order was placed here; an empty answer proves it was not. Never bodies.
+- **Miss headers on 404s.** A missing user or order keeps Junction's body byte for byte and adds
+  `x-mockingbird-miss: order <id>` (or `user <id>`, `user client:<client_user_id>`) and
+  `x-mockingbird-known: users=<n> orders=<n>`.
+
+`--log-requests` prints the same fields as one JSON line per request.
+
+## Order control
+
+`simulate_order` (`POST /v3/order/{id}/test`) behaves like the sandbox's, including its stepwise
+rules. For direct control, the admin API moves an order straight to a status, recording the same
+event, dates and appointment cascade, and publishing the same webhook, a real transition does:
 
-### Webhooks
+```bash
+curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "collected"}'
+curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "completed", "result": "critical"}'
+curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "cancelled.testkit.do_not_process"}'
+```
 
-`onWebhook` is called synchronously with every event the mock records
-(`labtest.order.created`, `labtest.order.updated`, `labtest.appointment.updated`). Delivery and
-signing are up to you. Junction delivers through Svix; the contributor server script signs with
-`svix-id`, `svix-timestamp` and `svix-signature: v1,<base64 HMAC-SHA256 of "<timestamp>.<body>">`,
-keyed by the base64-decoded secret after stripping a `whsec_` prefix:
+`to` is a full status (`completed.testkit.completed`), a `<phase>.<event>` pair, or a name that maps
+onto the contract's own status for the order's collection method:
+
+| Name | `at_home_phlebotomy` | `on_site_collection` | `testkit` | `walk_in_test` |
+| --- | --- | --- | --- | --- |
+| `requisition_created` | `received.…requisition_created` | same | same | same |
+| `scheduled` | `collecting_sample.…appointment_scheduled` | — | — | `collecting_sample.…appointment_scheduled` |
+| `shipped` / `delivered` | — | — | `collecting_sample.…transit_customer` / `…with_customer` | — |
+| `collected` | `collecting_sample.…draw_completed` | `sample_with_lab.…draw_completed` | `collecting_sample.…transit_lab` | — |
+| `at_lab` | — | `sample_with_lab.…draw_completed` | `sample_with_lab.…delivered_to_lab` | — |
+| `partial_results` | `sample_with_lab.…partial_results` | same | — | same |
+| `completed` / `corrected` / `cancelled` / `failed` | `completed.…completed` / `completed.…corrected` / `cancelled.…cancelled` / `failed.…sample_error` | same | same | same |
+
+A name with no real status for the method (`collected` for a walk-in test) is refused with the
+valid choices, never approximated. `result` picks a named result — `normal`, `abnormal`,
+`critical`, `missing_results` — which steers the generator so the payload keeps Junction's exact
+shape. For an exact payload, `PUT /__admin/results/{id}` with `{ "results": [...],
+"missing_results": null, "interpretation": "critical", "pdf_base64": "…" }`.
+
+There is no `isTestCancelled` in Junction's contract; cancelling produces the vendor's
+`cancelled.<method>.cancelled` event and webhook, which is what a consumer derives that flag from.
+
+**Time.** Every timestamp reads the runtime clock. `POST /__admin/clock {"advance": "2h"}` makes
+delayed simulations (`?delay=<seconds>`) due and moves appointment windows, with no sleeping.
+
+## Faults and error shapes
+
+Error bodies the mock reproduces byte for byte, checked against the sandbox by `verify` and the
+parity suite (`ORDER_NOT_FOUND` holds the unknown-order text per operation id):
+
+| Case | Status | Body |
+| --- | --- | --- |
+| `GET /v2/user/{unknown id}` | 404 | `{"detail":"Not found"}` |
+| `GET /v2/user/resolve/{unknown client_user_id}` | 404 | `{"detail":"User not found"}` |
+| Unknown order: get order, requisition PDF | 404 | `{"detail":"This order doesn't exist"}` |
+| Unknown order: cancel, simulate | 404 | `{"detail":"Order doesn't exist"}` |
+| Unknown order: result, result metadata, result PDF | 404 | `{"detail":"Order not found"}` |
+| Unknown order: every phlebotomy / PSC appointment route | 404 | `{"detail":"This order doesn't exist."}` (trailing period included) |
+| Missing `x-vital-api-key` | 401 | `{"detail":"Missing x-vital-api-key"}` |
+| Request validation | 422 | `{"detail":[{"type":…,"loc":[…],"msg":…,"input":…}]}` (Pydantic shape) |
+| Business rule | 400 | `{"detail":"<message>"}` or `{"detail":{"error_type":"INVALID_REQUEST","error_message":"…"}}` |
+
+Faults reproduce the sandbox's failure modes on demand, for retry paths and error handling:
+
+| Preset | Fault | Fidelity |
+| --- | --- | --- |
+| `sandbox_user_quota` | `create_user` → 400 `{"detail":{"error_type":"INVALID_REQUEST","error_message":"You have reached the maximum of 50 Sandbox users"}}` | byte-exact, as observed from a sandbox team |
+| `rate_limited` | 429 `{"detail":"Too Many Requests"}`, `retry-after: 1` | shape-plausible, not verified |
+| `server_error` / `bad_gateway` / `unavailable` | 500 / 502 / 503 | shape-plausible, not verified |
 
 ```ts
-import { createHmac, randomUUID } from "node:crypto"
-import { JunctionAPI } from "@crvouga/mockingbird-service-junction"
+import { createRuntime, FAULT_PRESETS } from "@crvouga/mockingbird-service-junction"
 
-const WEBHOOK_URL = "http://127.0.0.1:3100/webhooks/junction"
-const WEBHOOK_SECRET = "whsec_bW9ja2luZ2JpcmQtdGVzdC1zZWNyZXQ="
-
-const junction = new JunctionAPI({
-  onWebhook: (event) => {
-    const timestamp = Math.floor(Date.now() / 1000).toString()
-    const body = JSON.stringify(event)
-    const key = Buffer.from(WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64")
-    const signature = createHmac("sha256", key).update(`${timestamp}.${body}`).digest("base64")
-    void fetch(WEBHOOK_URL, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "svix-id": randomUUID(),
-        "svix-timestamp": timestamp,
-        "svix-signature": `v1,${signature}`,
-      },
-      body,
-    }).catch(() => undefined)
-  },
-})
-console.log(junction.webhookEvents().length) // 0
+const junction = createRuntime()
+junction.faults.add({ ...FAULT_PRESETS.sandbox_user_quota, id: "quota", count: 1 }) // next create_user only
+junction.faults.add({ id: "flaky-orders", operationId: "create_order_v3_order_post", status: 503, rate: 0.25 })
 ```
 
-`webhookDeliveryAttempts()` returns the retry schedule Junction would follow for each event
-(8 attempts: immediately, then 5s, 5m, 30m, 2h, 5h, 10h, 10h, with jitter controlled by the
-`webhook` option). It is a record only; nothing is re-sent.
+A rule matches on `operationId`, `method`, `pathPrefix` and `namespace` (all optional), fires
+`count` times or forever, for a `rate` of matching requests (seeded, so a run replays identically),
+after an optional `delayMs`. A rule added through the admin API defaults to the calling namespace,
+so one worker's injected failure never lands on another's request; one added in-process, as above,
+applies to every namespace unless given a `namespace`. Over HTTP: `POST /__admin/faults` with the same fields, or
+`POST /__admin/faults/presets/sandbox_user_quota`.
+
+## Webhooks
 
-### Resetting between tests
+With `webhooks` / `--webhook-url`, every event is delivered signed, with retries:
 
-`reset()` clears users, orders, appointments and webhook events, then re-installs the default
-catalog, or the corpus passed to `installCorpus` if there was one:
+- **Standard Svix signatures**: `svix-id`, `svix-timestamp`, and `svix-signature: v1,<base64
+  HMAC-SHA256 of "<svix-id>.<svix-timestamp>.<body>">`, keyed by the base64 part of `whsec_…`. The
+  official `svix` verifier, and a receiver written for real Junction, accept it unchanged. (Signing
+  `"<timestamp>.<body>"` without the message id, as this package's own server script did before,
+  is not Svix-compatible.)
+- Timestamps are wall-clock even when the mock clock is moved, because receivers reject timestamps
+  outside a few minutes of their own clock.
+- Any 2xx is delivered; anything else is retried on Svix's schedule (immediately, 5 s, 5 min,
+  30 min, 2 h, 5 h, 10 h, 10 h) or `retryDelaysMs`. `POST /__admin/webhooks/flush` runs pending
+  retries now; `POST /__admin/webhooks/{id}/replay` redelivers one message.
 
 ```ts
-import { beforeEach, expect, test } from "bun:test"
-import { JunctionAPI } from "@crvouga/mockingbird-service-junction"
+import { createRuntime, verifySvix } from "@crvouga/mockingbird-service-junction"
 
-const junction = new JunctionAPI()
-beforeEach(() => junction.reset())
+const secret = "whsec_bW9ja2luZ2JpcmQtdGVzdC1zZWNyZXQ="
+const junction = createRuntime({
+  webhooks: { url: "http://127.0.0.1:3100/webhooks/junction", secret, retryDelaysMs: [0, 500, 2000] },
+})
 
-test("starts with no users", async () => {
-  const response = await junction.fetch(
-    new Request("https://api.sandbox.tryvital.io/v2/user", {
-      headers: { "x-vital-api-key": "sk_us_mockingbird" },
-    }),
+// In a test receiver:
+const accept = async (request: Request) =>
+  verifySvix(
+    secret,
+    {
+      "svix-id": request.headers.get("svix-id") ?? "",
+      "svix-timestamp": request.headers.get("svix-timestamp") ?? "",
+      "svix-signature": request.headers.get("svix-signature") ?? "",
+    },
+    await request.text(),
   )
-  expect(await response.json()).toMatchObject({ users: [], total: 0 })
-})
+console.log(typeof accept, junction.webhooks?.deliveries().length) // "function" 0
 ```
 
-### Sealed corpus (optional, higher fidelity)
-
-Provider-owned inventory (area serviceability, PSC site lists, the team's lab catalog, labs, lab
-accounts) cannot be synthesized faithfully. A sealed corpus is an exact sandbox recording of those
-parameter-stable GETs; installing it makes the mock answer them byte-for-byte. The recording in the
-repo (`corpus/sandbox-sealed.json`) is not shipped in the npm package; copy it or record your own
-(see Development).
+## Verify
 
-```ts
-import { readFileSync } from "node:fs"
-import { JunctionAPI, parseSealedCorpus } from "@crvouga/mockingbird-service-junction"
+`verify` is the fidelity guarantee: it runs the same requests against real Junction and the mock
+and reports every divergence.
 
-const junction = new JunctionAPI()
-const recording: unknown = JSON.parse(readFileSync("test/junction-sandbox-sealed.json", "utf8"))
-junction.installCorpus(parseSealedCorpus(recording)) // re-applied on every reset()
+```bash
+npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --corpus test/junction-corpus.json
+npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --orders --sample 50 --json
 ```
 
-Availability is never recorded (its slot dates and single-use `booking_key`s cannot be replayed);
-it always comes from the deterministic generator.
+- **Drift**: re-fetches each recorded observation (or `--sample n` of them) and reports any that no
+  longer match production — the signal to re-pull.
+- **Scenario**: creates a user, reads it back, provokes the documented 404s (including every
+  order-scoped operation against a random unknown order), reads the catalog (paged and bare) and a
+  covered ZIP's serviceability, and deletes the user; with `--orders`, also places, reads and
+  cancels an order for the corpus's first lab test, and — when the corpus has an account with an
+  empty `team_id_allowlist` — orders through it with and without its id. Status codes must match;
+  bodies must match in shape, and byte for byte for the documented error bodies.
+
+It exits 1 on any divergence. The scenario always deletes its user (and cancels its order), because
+it runs against the same capped sandbox the mock exists to relieve. `verifyAgainstReal` is the same
+check as a function. This repo runs it in CI against the Junction sandbox.
+
+## Determinism
+
+With a fixed clock (`clock` / `POST /__admin/clock {"set": …, "freeze": true}`) and `seed`, a run
+replays exactly. Stable across runs: user ids, order ids, event ids, sample ids, booking keys and
+webhook message ids (derived from sequence numbers), timestamps (from the clock), generated
+availability, and which requests a partial-`rate` fault hits. Wall-clock by design: webhook
+`svix-timestamp`, `/health` uptime, and request log durations.
+
+## What is and is not modelled
+
+A mock that is silent about its gaps is how a green suite starts lying. Specifically:
+
+- **Corpus-backed** (byte-exact): area and PSC serviceability for covered ZIPs; the catalog, labs,
+  expected results and lab accounts of the team the corpus was recorded from.
+- **Synthetic** (deterministic, shape-faithful, values invented): availability slots and booking
+  keys; results (biomarker lines and PDFs) unless a fixture is installed; requisition PDFs;
+  coverage for any ZIP in `--geo synthetic` mode.
+- **Not modelled**:
+  - `delegated_flow`-specific ordering. Accounts carry the field and orders follow the documented
+    selection and billing rules above, but any additional behaviour Junction applies to delegated
+    accounts is not reproduced. Run `verify --orders` with your team's corpus to check what you rely on.
+  - Rate limits and outages, except when injected as faults or switched on as
+    [limits](#sandbox-limits).
+  - Whether an account with an empty `team_id_allowlist` can be ordered through (see
+    [Team identity](#team-identity)); the mock assumes it can.
+  - Adopted users (`adopt-users`) have `client_user_id` equal to their `user_id`; nothing in
+    Junction corresponds to adoption.
+  - Real 429 / 5xx bodies: the presets are plausible, not recorded.
+  - Phlebotomy availability breadth: the sandbox serves it only for `85004`; the mock generates slots
+    for any covered ZIP.
+  - Webhook retry jitter across a snapshot restore (the jitter stream is not part of a snapshot).
+  - Operations outside the vendored OpenAPI subset: they return 404 and are counted as
+    `unmatched` in `/__admin/metrics`.
 
 ## API
 
+Main entry (`@crvouga/mockingbird-service-junction`, runtime-neutral):
+
 | Export | Description |
 | --- | --- |
-| `JunctionAPI` | Class. `new JunctionAPI(options?)`; implements the Fetch contract `fetch(request: Request): Promise<Response>`. |
-| `JUNCTION_NAMESPACE` | `"junction"` — SQLite namespace holding the mock's state when sharing a `sqlite` client. |
+| `createRuntime` | `(options?: JunctionRuntimeOptions) => JunctionRuntime` — the served mock (health, admin, namespaces, clock, faults, metrics, journal, webhooks) as one `fetch`. Options: `corpus`, `geo`, `labAccounts`, `teamId`, `limits`, `identity`, `fixtures`, `journalSize`, `webhooks`, `onWebhook`, `sqlite`, `clock`, `seed`, `adminKey`, `onLog`. |
+| `JunctionAPI` | Class. `new JunctionAPI(options?)`: one namespace's mock, implementing `fetch(request: Request): Promise<Response>`. |
+| `JUNCTION_NAMESPACE` | `"junction"` — the default namespace's storage key when sharing a `sqlite` client. |
 | `document` | The vendored Junction OpenAPI document (Mockingbird subset) that drives routing. |
 | `operationIds` | Every `operationId` in `document`. |
 | `supportedOperationIds` | The `operationId`s the mock implements (all of them). |
+| `pullCorpus` | `(options: PullCorpusOptions) => Promise<SealedCorpus>` — record a corpus from a real team (GETs only). |
+| `diffCorpus` | `(before, after) => CorpusDiff` — ZIPs, lab tests, lab accounts and observations added / removed / changed. |
+| `fingerprintCorpus` | `(corpus) => Promise<string>` — SHA-256 of a corpus's content. |
+| `corpusLabel` | `(corpus) => string` — the short label `/health` and logs show, e.g. `v1-2026-09-18-HqFDuEAuhkwD`. |
 | `parseSealedCorpus` | `(value: unknown) => SealedCorpus`; throws on a non-object or unsupported `version`. |
-| `SEALED_CORPUS_VERSION` | Current sealed-corpus format version (`1`). |
-| `observationCacheKey` | `(url, method = "GET", body?) => string` — the `"<METHOD> <path>?<sorted query> <json>"` key used by the observation cache and corpus. |
-| `prefetchCoverageObservations` | Parity helper: records coverage-ZIP area/PSC/availability reads from the real sandbox into an observation cache before `seedFrom`. |
+| `SEALED_CORPUS_VERSION` | Current corpus format version (`2`: adds `teamId`). |
+| `SUPPORTED_SEALED_CORPUS_VERSIONS` | Versions `parseSealedCorpus` loads (`[1, 2]`). |
+| `MOCK_TEAM_ID` | The team id used when neither `teamId` nor the corpus gives one. |
+| `OTHER_TEAM_ID` | A team that is not the mock's, for fixtures modelling another team's account. |
+| `isLinkedToTeam` | `(account, teamId) => boolean` — the allowlist rule (`[]` counts as linked). |
+| `LAB_ACCOUNT_PRESETS` | The [lab-account presets](#lab-account-presets), without ids. |
+| `presetAccountId` | `(name) => string` — a preset's default id. |
+| `PLATFORM_ACCOUNT_STATES` / `DELEGATED_ACCOUNT_STATES` | The recorded 47- and 48-state client-bill lists. |
+| `LabAccountConflict` | Thrown by `addLabAccount` for an id that exists. |
+| `DEFAULT_LIMITS` | Every [sandbox limit](#sandbox-limits), off. |
+| `sandboxUserQuotaBody` | `(max) => body` — the sandbox's user-cap 400 body. |
+| `IDENTITY_MODES` | `["strict", "adopt-users"]`. |
+| `FixtureError` | Thrown by the fixture inserts; `status` is 400, 404 or 409. |
+| `ORDER_NOT_FOUND` | Junction's unknown-order `detail`, by operation id. |
+| `MISS_HEADER` / `KNOWN_HEADER` | `"x-mockingbird-miss"` / `"x-mockingbird-known"`. |
+| `verifyAgainstReal` | `(options: VerifyOptions) => Promise<VerifyReport>` — the `verify` command as a function. |
+| `DEFAULT_JUNCTION_BASE_URL` | `"https://api.sandbox.tryvital.io"`. |
+| `isSandboxKey` / `SANDBOX_KEY_PREFIXES` | Whether a key is a sandbox team key (`sk_us_` / `sk_eu_`). |
+| `UNKNOWN_ZIP_STATUS` / `UNKNOWN_ZIP_ERROR_TYPE` | `424` / `"MOCKINGBIRD_UNKNOWN_ZIP"` — the corpus-mode unknown-ZIP error. |
+| `labAccountFromInput` | `(input: LabAccountInput) => LabAccountRecord` — normalize (and validate) a configured account. |
+| `TEAM_LAB_ACCOUNTS` | The built-in lab-account fixtures. |
+| `US_STATES` | The 50 `USState` codes Junction accepts. |
+| `ORDER_STATUSES_BY_METHOD` | Every order status in the contract, by collection method. |
+| `TRANSITION_ALIASES` | The transition names above, by method. |
+| `resolveTransition` | `(method, target) => { status } \| { error }` — how `/__admin/orders/{id}/transition` reads `to`. |
+| `RESULT_FIXTURES` | Named results (`normal`, `abnormal`, `critical`, `missing_results`). |
+| `FAULT_PRESETS` | Named Junction faults (`sandbox_user_quota`, `rate_limited`, `server_error`, `bad_gateway`, `unavailable`). |
+| `createWebhookDispatcher` | `(endpoint: WebhookEndpoint) => WebhookDispatcher` — signed delivery with retries, standalone. |
+| `signSvix` / `verifySvix` | Produce / check a standard Svix `svix-signature`. |
+| `observationCacheKey` | `(url, method = "GET", body?) => string` — the `"<METHOD> <path>?<sorted query> <json>"` key corpora use. |
+| `prefetchCoverageObservations` | Parity helper: records coverage-ZIP reads from the sandbox into an observation cache before `seedFrom`. |
 | `reshapeCoverageGeoCommand` | Parity-walk hook that pins geo/availability parameters onto the coverage corpus. |
-| `COVERAGE_ZIPS` | ZIP codes the coverage corpus seals for area/PSC reads. |
+| `COVERAGE_ZIPS` | The ZIPs the shipped corpus covers. |
 | `PSC_AVAILABILITY_ZIPS` | ZIPs that also get PSC availability observations. |
-| `PHLEBOTOMY_AVAILABILITY_ZIPS` | ZIPs served for phlebotomy availability (`["85004"]`). |
+| `PHLEBOTOMY_AVAILABILITY_ZIPS` | ZIPs the sandbox serves phlebotomy availability for (`["85004"]`). |
 | `PSC_LAB_IDS` | Lab ids used for PSC reads (`[4, 6, 13, 25]`). |
 | `AVAILABILITY_ADDRESS` | Stable Phoenix, AZ address used in availability requests so cache keys match. |
 | `AVAILABILITY_START_DATE` | Far-future availability `start_date` (`"2099-06-15"`). |
 
+`./server` (Node): `createServer(options?) => Promise<JunctionServer>`, `serveTarget` (what
+`serve` and `serve --config` use), `loadCorpus(source)`, `DEFAULT_PORT` (`8787`).
+`./corpus`: `defaultCorpus`.
+
+`JunctionRuntime` (from `createRuntime`) members: `fetch`, `instance(namespace?)`, `namespaces()`,
+`reset(namespace? | "*")`, `snapshot(namespace?)`, `restore(snapshot, namespace?)`, `clock`
+(`now`, `set`, `advance`, `freeze`, `unfreeze`, `reset`, `state`), `faults` (`add`, `list`,
+`remove`, `clear`), `metrics` (`report`, `reset`), `journal` (`list`, `clear`, `size`), `webhooks`
+(`deliveries`, `replay`, `flush`, `idle`, `clear`), `sqlite`, `rng`.
+
 `JunctionAPI` members:
 
 | Member | Description |
 | --- | --- |
 | `fetch(request)` | Handle one Junction REST request. |
-| `reset()` | `Promise<void>` — clear state; re-install the default catalog or the installed corpus. |
-| `installCorpus(corpus)` | Install a `SealedCorpus` (observation cache, catalog, labs, lab accounts). |
+| `reset()` | `Promise<void>` — clear state; re-install the corpus or default catalog, and the configured lab accounts. |
+| `installCorpus(corpus)` | Install a `SealedCorpus`: observations (shared, read-only), catalog, labs, lab accounts, ZIP coverage. |
+| `corpusInfo()` | `CorpusInfo \| undefined` — label, recording date, source and counts. |
+| `geoMode` | `"corpus" \| "synthetic"`, settable. |
+| `configureLabAccounts(layout?)` / `labAccounts()` | Replace (a list, or `{ presets, accounts }`; `undefined` restores the default) / read the team's lab accounts. |
+| `addLabAccount(input)` / `addLabAccountPreset(name, id?)` / `patchLabAccount(id, patch)` / `removeLabAccount(id)` | Change one account; kept across `reset()`. |
+| `teamId` | The team this namespace answers as. |
+| `limits` / `configureLimits(input)` | Read / change the sandbox limits; kept across `reset()`. |
+| `identity` | `"strict" \| "adopt-users"`, settable. |
+| `insertUsers(users)` / `insertOrders(orders, { emitWebhooks? })` / `importFixtures(fixtures, options?)` / `hardDeleteUser(id)` | The [fixture backdoor](#fixtures-and-identity). |
+| `order(id)` / `orders()` | Read orders. |
+| `transitionOrder(id, status, { now, flags? })` | Move an order to a full status and publish its webhook. |
+| `installResultFixture(orderId, fixture)` / `resultFixture(orderId)` | Serve an exact result payload / PDF for an order. |
 | `seedFrom(source, observations?)` | `Promise<SeedReport>` — copy users, orders, appointments, catalog and labs from a real Junction environment. |
 | `ensureLabTests(source, ids)` / `ensureOrders(source, ids)` | `Promise<number>` — fetch specific lab tests / orders from `source` if missing. |
 | `markUserDeleted(userId)` | Mark a user as deleted (subsequent reads behave like a deleted user). |
 | `webhookEvents()` | `JunctionWebhookEvent[]`, oldest first. |
-| `webhookDeliveryAttempts()` | Recorded retry schedule per event. |
+| `webhookDeliveryAttempts()` | The retry schedule Junction would follow per event (a record; see `webhooks` for delivery). |
 | `app` / `sqlite` | The underlying Hono app and `SqliteClient`. |
 
 Options and types:
@@ -265,21 +764,31 @@ Options and types:
 ```text
 type JunctionAPIOptions = {
   sqlite?: SqliteClient          // share one client across services; default: fresh in-memory DB
+  namespace?: string             // storage namespace; default "junction"
   now?: () => number             // clock in ms; default Date.now
+  corpus?: SealedCorpus          // installed now and on every reset()
+  geo?: "corpus" | "synthetic"   // default "corpus" with a corpus, else "synthetic"
+  labAccounts?: LabAccountInput[] | { presets?: (string | { name; id? })[]; accounts?: LabAccountInput[] }
+  teamId?: string                // default: the corpus's recorded team, else MOCK_TEAM_ID
+  limits?: { maxUsers?: number | null; simulateRequiresSandbox?: boolean; rateLimitPerSecond?: number | null }
+  identity?: "strict" | "adopt-users"  // default "strict"
+  fixtures?: { users?: UserFixture[]; orders?: OrderFixture[] }  // loaded now and on every reset()
   onWebhook?: WebhookPublisher   // called with every recorded event
   webhook?: JunctionWebhookOptions
 }
-type JunctionWebhookOptions = { seed?: number; jitterRatio?: number /* 0..1, default 0.1 */; timeoutMs?: number /* default 15000 */ }
+type LabAccountInput = { id; lab; status?; delegated_flow?; account_name?; provider_account_id?; org_id?;
+  business_units?; default_clinical_notes?; allowed_billing?: Record<billingType, State[]>; states?: State[];
+  team_id_allowlist? }
+type WebhookEndpoint = { url; secret: "whsec_…"; retryDelaysMs?: number[]; timeoutMs?; headers?; fetch? }
+type ResultFixture = { name; results?: unknown[]; missing_results?: unknown[] | null; interpretation?; pdf_base64? }
+type FaultRule = { id; operationId?; method?; pathPrefix?; status; body?; headers?; count?; rate?; delayMs? }
+type JunctionWebhookOptions = { seed?: number; jitterRatio?: number /* 0..1, default 0.1 */; timeoutMs?: number }
 type JunctionWebhookEvent = {
   event_type: "labtest.order.created" | "labtest.order.updated" | "labtest.appointment.updated"
   data: Record<string, unknown>; team_id: string; user_id: string; client_user_id: string
 }
-type WebhookPublisher = (event: JunctionWebhookEvent) => void
+type SealedCorpus = { version: 1 | 2; recordedAt; source; teamId?; fingerprint?; observations; catalog: { labTests; labs; expectedResults }; labAccounts }
 type SeedSource = { fetch: (request: Request) => Promise<Response>; baseUrl: string; headers: Record<string, string> }
-type SeedObservations = { getCache?: ReadonlyMap<string, GetCacheEntry> }
-type SeedReport = { users; orders; appointments; catalogTests; labs; cacheEntries: number }
-type GetCacheEntry = { status: number; headers: Record<string, string>; body: unknown }
-type SealedCorpus = { version: 1; recordedAt; source; observations; catalog: { labTests; labs; expectedResults }; labAccounts }
 type OperationId / SupportedOperationId  // string unions of operationIds / supportedOperationIds
 ```
 
@@ -299,23 +808,19 @@ console.log(report.users, report.orders)
 
 ## Development
 
-For contributors to the mockingbird repo only; these scripts and the corpus are not shipped in the
-npm package.
+For contributors to the mockingbird repo only.
 
 ```bash
 bun test                                   # offline suites, incl. scheduling state space
-bun test junction.seed.property.test.ts    # offline monkey (no network)
+bun test junction.runtime.property.test.ts # service contract, corpus, lab accounts, faults, webhooks, verify
 bun test junction.sdk.property.test.ts     # drives the served mock through @tryvital/vital-node
 
-bun run mock:serve                         # HOST=127.0.0.1 PORT=8787; GET /health, POST /__admin/reset
-MOCKINGBIRD_JUNCTION_CORPUS=corpus/sandbox-sealed.json bun run mock:serve
-bun run corpus:record                      # record corpus/sandbox-sealed.json (needs a sandbox key)
+bun run mock:serve                         # env-configured `serve`: HOST, PORT, MOCKINGBIRD_JUNCTION_CORPUS,
+                                           # MOCKINGBIRD_JUNCTION_WEBHOOK_URL / _SECRET / _SCOPE
+bun run corpus:record -- --force           # re-record the shipped corpus/sandbox-sealed.json (Vault key)
+bun run verify -- --real-key "$KEY"        # `mockingbird-junction verify` from source
 ```
 
-`mock:serve` installs `corpus/sandbox-sealed.json` when present, and signs webhooks to
-`MOCKINGBIRD_JUNCTION_WEBHOOK_URL` with `MOCKINGBIRD_JUNCTION_WEBHOOK_SECRET` (delivery is disabled
-without a secret). `/health` and `/__admin/reset` bypass the `x-vital-api-key` gate.
-
 Live parity (primary proof is seedParity: warmup N on the sandbox, `seedFrom`, then lockstep M):
 
 ```bash
@@ -326,6 +831,5 @@ bun run parity -- --mode=empty                   # legacy empty-start differenti
 
 Webhook parity needs a public receiver; see
 [docs/webhook-parity.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/junction/docs/webhook-parity.md).
-The `client-parity*.ts` SDK scenarios are deprecated as proof and kept only as manual probes.
 
 Part of [mockingbird](https://github.com/crvouga/mockingbird) — agent integration guide: [README](https://github.com/crvouga/mockingbird#readme) · [llms.txt](https://github.com/crvouga/mockingbird/blob/main/llms.txt).