@crvouga/mockingbird-service-junction 1.8.2 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog — @crvouga/mockingbird-service-junction
 
+## 2.0.0 (2026-10-04)
+
+### ⚠️ Breaking changes
+
+- isolate internal routes ([5e19b21](https://github.com/crvouga/mockingbird/commit/5e19b21d403acc74b04778a8b545e80bcbdf8d51))
+
+### Features
+
+- add route filtering ([4e59b1d](https://github.com/crvouga/mockingbird/commit/4e59b1d42a76550f844b744f8431a637433a0781))
+- publish agent package indexes ([eca61d3](https://github.com/crvouga/mockingbird/commit/eca61d358b86982cf0b777ae8bd7feaa3663aaa6))
+
+### Fixes and improvements
+
+- clarify runtime prefix options ([f899a78](https://github.com/crvouga/mockingbird/commit/f899a7891f29413e4f08e9534d0c977f16acf7d7))
+- honor configured prefixes ([4f569d7](https://github.com/crvouga/mockingbird/commit/4f569d74ca8089f2ed5e33a1abf32b90973f41dd))
+- explain configurable internal paths ([21b47ae](https://github.com/crvouga/mockingbird/commit/21b47ae4d4a096cdf63189aaeaf721ccb369bcf3))
+- parse ISO journal timestamps ([20b39a2](https://github.com/crvouga/mockingbird/commit/20b39a2c738e278533d610dfc91f1cb3ae9b3f1e))
+- scope collector controls ([af9ee8f](https://github.com/crvouga/mockingbird/commit/af9ee8f4ccd98695831cd04eb0655ebd0280ecf6))
+- harden shared controls ([7822614](https://github.com/crvouga/mockingbird/commit/7822614f6cba0387aeb60ba7320b0379aa1ef690))
+
+### Dependencies
+
+- `@crvouga/mockingbird-service-sqlite`
+
+## 1.9.0 (2026-10-01)
+
+### Features
+
+- coordinate HTTP and protocol mocks ([3168653](https://github.com/crvouga/mockingbird/commit/31686534c55a9823fdaa92afc9cc456cf741b809))
+
+### Fixes and improvements
+
+- decouple smoke types from built packages ([a4b31c6](https://github.com/crvouga/mockingbird/commit/a4b31c6205d92aa0c6f7c9de3518d5ae44d38829))
+- protect child admin endpoints ([5410b94](https://github.com/crvouga/mockingbird/commit/5410b948a30dcedc21e9a70e44fd415c1ea25394))
+- harden protocol startup and state ([6f5b557](https://github.com/crvouga/mockingbird/commit/6f5b557e87b48b31985949e04f3b5ef58f51d295))
+- preserve checkpoints and lifecycle ([50e8c32](https://github.com/crvouga/mockingbird/commit/50e8c322feded2f7f45afce9d8cdef43c37ab9ab))
+- clean branch state on reset ([3b714d4](https://github.com/crvouga/mockingbird/commit/3b714d4a5df8e75fee0bb31e98d7c7566e164381))
+- type signal listener cleanup ([5279852](https://github.com/crvouga/mockingbird/commit/5279852e56ea60262ccf17aa6e46b3c31091a34a))
+
 ## 1.8.2 (2026-10-01)
 
 ### Fixes and improvements

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-junction discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-junction/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Users, orders, and lab results**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- junction`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `junction`.

package/README.md

@@ -111,7 +111,7 @@ npx mockingbird-junction serve --config mockingbird.json
 import { createServer } from "@crvouga/mockingbird-service-junction/server"
 
 const server = await createServer() // shipped corpus, any free port
-const health = await fetch(`${server.url}/health`)
+const health = await fetch(`${server.url}/__admin/health`)
 console.log(health.status) // 200
 
 // Point the Vital SDK (or your backend's Junction base URL) at server.url, then:
@@ -226,7 +226,7 @@ while keeping the production and sandbox guards intact.
 
 Every Mockingbird service answers the same control surface, outside the vendor's auth gate:
 
-- `GET /health` — unauthenticated readiness probe:
+- `GET /__admin/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,
@@ -696,7 +696,7 @@ With a fixed clock (`clock` / `POST /__admin/clock {"set": …, "freeze": true}`
 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.
+`svix-timestamp`, `/__admin/health` uptime, and request log durations.
 
 ## What is and is not modelled
 
@@ -739,7 +739,7 @@ Main entry (`@crvouga/mockingbird-service-junction`, runtime-neutral):
 | `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`. |
+| `corpusLabel` | `(corpus) => string` — the short label `/__admin/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 corpus format version (`2`: adds `teamId`). |
 | `SUPPORTED_SEALED_CORPUS_VERSIONS` | Versions `parseSealedCorpus` loads (`[1, 2]`). |

package/SUPPORT.md

@@ -0,0 +1,50 @@
+# Junction API (Mockingbird subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **40**
+- supported by the mock: **40**
+- parity enabled: **22**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `get_teams_users_v2_user_get` | `GET /v2/user` | ✅ supported | ✅ |  |
+| `create_user_v2_user_post` | `POST /v2/user` | ✅ supported | ✅ |  |
+| `get_user_v2_user__user_id__get` | `GET /v2/user/{user_id}` | ✅ supported | ✅ |  |
+| `delete_user_v2_user__user_id__delete` | `DELETE /v2/user/{user_id}` | ✅ supported | ✅ |  |
+| `patch_user_v2_user__user_id__patch` | `PATCH /v2/user/{user_id}` | ✅ supported | ✅ |  |
+| `get_user_by_client_user_id_v2_user_resolve__client_user_id__get` | `GET /v2/user/resolve/{client_user_id}` | ✅ supported | ✅ |  |
+| `patch_user_info_v2_user__user_id__info_patch` | `PATCH /v2/user/{user_id}/info` | ✅ supported | ✅ |  |
+| `get_latest_user_info_user_v2_user__user_id__info_latest_get` | `GET /v2/user/{user_id}/info/latest` | ✅ supported | ✅ |  |
+| `get_paginated_lab_tests_for_team_v3_lab_test_get` | `GET /v3/lab_test` | ✅ supported | ✅ |  |
+| `get_team_lab_accounts_v3_lab_test_lab_account_get` | `GET /v3/lab_test/lab_account` | ✅ supported | ❌ disabled | lab-account inventory is fixture-owned; the mock models the documented shape, filters and routing rules, not a live account inventory |
+| `get_lab_tests_for_team_v3_lab_tests_get` | `GET /v3/lab_tests` | ✅ supported | ✅ |  |
+| `get_lab_test_for_team_v3_lab_tests__lab_test_id__get` | `GET /v3/lab_tests/{lab_test_id}` | ✅ supported | ✅ |  |
+| `get_labs_v3_lab_tests_labs_get` | `GET /v3/lab_tests/labs` | ✅ supported | ✅ |  |
+| `get_markers_for_lab_test_v3_lab_tests__lab_test_id__markers_get` | `GET /v3/lab_tests/{lab_test_id}/markers` | ✅ supported | ✅ |  |
+| `list_order_set_markers_v3_lab_tests_list_order_set_markers_post` | `POST /v3/lab_tests/list_order_set_markers` | ✅ supported | ✅ |  |
+| `create_order_v3_order_post` | `POST /v3/order` | ✅ supported | ✅ |  |
+| `get_area_info_v3_order_area_info_get` | `GET /v3/order/area/info` | ✅ supported | ❌ disabled | central_labs presence, within_radius counts and getlabs market coverage are provider-owned geo data that a mock cannot replicate per-zip; covered by the client-parity scenario shape checks instead |
+| `get_psc_info_v3_order_psc_info_get` | `GET /v3/order/psc/info` | ✅ supported | ❌ disabled | patient_service_centers are real site inventories per zip (thousands of sites, result-capped at 30) that a fixture mock cannot replicate per-zip; covered by the client-parity scenario shape checks instead |
+| `get_phlebotomy_appointment_availability_v3_order_phlebotomy_appointment_availability_post` | `POST /v3/order/phlebotomy/appointment/availability` | ✅ supported | ❌ disabled | availability slots are provider-side data whose values shift between sandbox calls; covered by the mock-internal scheduling property suite instead |
+| `get_phlebotomy_appointment_cancellation_reason_v3_order_phlebotomy_appointment_cancellation_reasons_get` | `GET /v3/order/phlebotomy/appointment/cancellation-reasons` | ✅ supported | ✅ |  |
+| `get_psc_appointment_availability_v3_order_psc_appointment_availability_post` | `POST /v3/order/psc/appointment/availability` | ✅ supported | ❌ disabled | availability slots are provider-side data whose values shift between sandbox calls; covered by the mock-internal scheduling property suite instead |
+| `get_psc_appointment_cancellation_reason_v3_order_psc_appointment_cancellation_reasons_get` | `GET /v3/order/psc/appointment/cancellation-reasons` | ✅ supported | ✅ |  |
+| `get_phlebotomy_appointment_v3_order__order_id__phlebotomy_appointment_get` | `GET /v3/order/{order_id}/phlebotomy/appointment` | ✅ supported | ❌ disabled | appointment payloads embed provider-side slot data; covered by the mock-internal scheduling property suite instead |
+| `book_phlebotomy_appointment_v3_order__order_id__phlebotomy_appointment_book_post` | `POST /v3/order/{order_id}/phlebotomy/appointment/book` | ✅ supported | ❌ disabled | booking depends on live provider slot state; covered by the mock-internal scheduling property suite instead |
+| `reschedule_phlebotomy_appointment_v3_order__order_id__phlebotomy_appointment_reschedule_patch` | `PATCH /v3/order/{order_id}/phlebotomy/appointment/reschedule` | ✅ supported | ❌ disabled | rescheduling depends on live provider slot state; covered by the mock-internal scheduling property suite instead |
+| `cancel_phlebotomy_appointment_v3_order__order_id__phlebotomy_appointment_cancel_patch` | `PATCH /v3/order/{order_id}/phlebotomy/appointment/cancel` | ✅ supported | ❌ disabled | cancellation depends on live provider appointment state; covered by the mock-internal scheduling property suite instead |
+| `get_psc_appointment_v3_order__order_id__psc_appointment_get` | `GET /v3/order/{order_id}/psc/appointment` | ✅ supported | ❌ disabled | appointment payloads embed provider-side slot data; covered by the mock-internal scheduling property suite instead |
+| `book_psc_appointment_v3_order__order_id__psc_appointment_book_post` | `POST /v3/order/{order_id}/psc/appointment/book` | ✅ supported | ❌ disabled | booking depends on live provider slot state; covered by the mock-internal scheduling property suite instead |
+| `reschedule_psc_appointment_v3_order__order_id__psc_appointment_reschedule_patch` | `PATCH /v3/order/{order_id}/psc/appointment/reschedule` | ✅ supported | ❌ disabled | rescheduling depends on live provider slot state; covered by the mock-internal scheduling property suite instead |
+| `cancel_psc_appointment_v3_order__order_id__psc_appointment_cancel_patch` | `PATCH /v3/order/{order_id}/psc/appointment/cancel` | ✅ supported | ❌ disabled | cancellation depends on live provider appointment state; covered by the mock-internal scheduling property suite instead |
+| `get_order_v3_order__order_id__get` | `GET /v3/order/{order_id}` | ✅ supported | ✅ |  |
+| `cancel_order_v3_order__order_id__cancel_post` | `POST /v3/order/{order_id}/cancel` | ✅ supported | ✅ |  |
+| `simulate_order_v3_order__order_id__test_post` | `POST /v3/order/{order_id}/test` | ✅ supported | ✅ |  |
+| `get_result_raw_v3_order__order_id__result_get` | `GET /v3/order/{order_id}/result` | ✅ supported | ❌ disabled | results carry provider-side specimen data; covered by the mock-internal results property suite instead |
+| `get_result_metadata_v3_order__order_id__result_metadata_get` | `GET /v3/order/{order_id}/result/metadata` | ✅ supported | ✅ |  |
+| `get_result_pdf_v3_order__order_id__result_pdf_get` | `GET /v3/order/{order_id}/result/pdf` | ✅ supported | ❌ disabled | PDF bytes are provider-rendered; compared by shape (byteLength) only in the scenario script |
+| `get_order_requisition_pdf_v3_order__order_id__requisition_pdf_get` | `GET /v3/order/{order_id}/requisition/pdf` | ✅ supported | ❌ disabled | PDF bytes are provider-rendered; compared by shape (byteLength) only in the scenario script |
+| `get_orders_v3_orders_get` | `GET /v3/orders` | ✅ supported | ✅ |  |
+| `get_order_transaction_v3_order_transaction__transaction_id__get` | `GET /v3/order_transaction/{transaction_id}` | ✅ supported | ❌ disabled | order transactions are not available to the sandbox team (feature not available) |
+| `get_order_transaction_result_v3_order_transaction__transaction_id__result_get` | `GET /v3/order_transaction/{transaction_id}/result` | ✅ supported | ❌ disabled | lab results are not available to the sandbox team (feature not available) |